OpenToonz 贡献评审检查清单以不干扰既有用法为核心的 PR 合并策略与源码实践【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz本文基于 OpenToonz 官方仓库 doc/development_checklist.md草稿展开该清单提炼自 OpenToonz 核心维护者 Shun Iwasawa 在 Discussion #6332 中发布的开发政策。核心原则一句话即可概括一个 Pull Request 只要不干扰既有用法就可以合并。本文面向贡献者、评审者与维护者逐条拆解这份检查清单的每一项要求并结合仓库内的许可文件、Fx 预设、翻译资源、用户档案布局与构建流程等真实证据说明每一项检查在 OpenToonz 代码库中的落点帮助读者理解什么变更会被接受、什么变更需要升级审批、以及如何为自己的 PR 自检。1. 文档定位评审辅助工具而非硬性裁决development_checklist.md在开篇即明确自己的定位它是面向**贡献者contributors、评审者reviewers和维护者maintainers**的实用辅助工具并不取代维护者的判断或项目特定评审流程。因此在实际评审中清单被击中并不意味着 PR 被自动拒绝而是提示这里存在一个需要显式决策的分歧点。该文档同时声明了两条重要边界检查清单冲突不自动拒绝变更而是标识一个需要明确批准explicit approval的决策破坏既有用法、兼容性、许可预期或其他政策的变更可能需要维护者或项目所有者owner批准且批准可能耗时——因此文档建议尽早识别这类冲突。从仓库配套文档看该清单在项目中并非孤立存在根目录 README.md 的 Development 一节将 Development checklist (draft) 与 AI-assisted development checklist (draft) 并列列出后者针对 AI 辅助贡献场景补充了 OT-Dev 探索与上游提交Upstream Readiness Gate的额外要求CONTRIBUTING.md 则给出了 fork、clone、建分支、格式化、提交与提 PR 的操作流程。三份文档共同构成 OpenToonz 的贡献与评审体系。2. 核心合并要求Core Merge Requirement清单第 1 节给出了合并 PR 之前必须确认的三项基本要求确认变更不会干扰 OpenToonz 的既有用法考虑使一种工作流受益的变更是否会让另一种工作流失衡在可能发生工作流冲突时考虑将行为设计为可选或用户可选择优先通过用户档案user profiles或适当的设置项实现。不干扰既有用法是贯穿全清单的总纲。理解这一原则需要结合 OpenToonz 的软件形态它是一款被 Studio Ghibli、DWANGO 等专业动画工作室长期使用的全功能 2D 动画制作软件用户群中存在大量沿用多年的既有制作流程。仓库中stuff/profiles/layouts/目录存放了 172 个布局/预设文件fxs/*.xml效果器预设、房间布局等stuff/config/qss/存放各主题样式表Default、Dark、Clay 等stuff/config/下还有brush.txt、reslist.txt、colornames.txt等默认配置。这些默认用户档案一旦被无声改变会直接影响所有使用默认配置的用户——这正是以用户档案承载可选行为这一条款的现实意义。3. 例外与升级机制Exceptions and Escalation清单紧接着解释了冲突出现时的处理路径核心要点如下检查清单冲突不自动拒绝变更它只是标识需要显式批准的决策破坏既有用法、兼容性、许可预期或其他政策的变更需要maintainer 或 owner 批准批准可能需要时间应尽早识别重大变更可能需要先在OT-Dev或独立 fork 中给出可运行演示再用于对比收益、回归、迁移成本与受影响工作流不要把例外当作隐含批准必须记录该例外、其影响以及允许它的决策依据。这意味着提交 PR 前作者应自行判断自己的变更是否触及既有用法/兼容性/许可敏感区。若属于重大行为变更主动准备演示如新效果器的对比渲染、迁移前后场景对比能显著加快审批流程。4. 许可审查License Review检查 PR 是否引入了可能与 OpenToonz 现有许可冲突的代码、库、资源、算法或其他材料如果存在许可冲突的可能在 owner 审查完成之前不要合并。许可审查在 OpenToonz 仓库中有非常具体的落点。根目录 LICENSE.txt 明确OpenToonz 主体采用BSD 3-Clause New or Revised License各贡献者对其贡献分别持有版权Git 版本历史记录了全部贡献来源信息。同时该文件划定了两块例外区域thirdparty/目录内含 glew、libpng、zlib、libjpeg-turbo、SuperLU、OpenBLAS、kiss_fft、lz4、tinyexr、tiff、lzo、boost、canon 等第三方库需查阅各自 README 或源码中的许可声明仓库stuff/doc/LICENSE/下也集中收录了LICENSE_glew.txt、LICENSE_opencv.txt、LICENSE_boost.txt、LICENSE_libjpeg-turbo.txt等副本stuff/library/mypaint brushes/目录需参见stuff/library/mypaint brushes/Licenses.txt。因此引入新依赖或资源时贡献者需要判断其许可证如 GPL、专有许可与 BSD-3 及 thirdparty 许可体系是否兼容AI 辅助贡献场景下的许可与来源provenance核查则由 doc/ai_assisted_development_checklist.md 第 5 节进一步约束不引入与 OpenToonz 不兼容许可的代码/资产输出与第三方材料相似时核查来源等。5. 稳定版发布限制Stable Release Restrictions在公告稳定版发布前的数月冻结期内判断 PR 是否属于feature PR功能型 PR冻结期内不要合并 feature PR适当的bug 修复及其他非功能变更仍按核心原则继续评估。这一条要求贡献者与维护者共同关注版本节奏即使一个功能 PR 质量很高、完全符合不干扰既有用法原则若处于预发布稳定期也应推迟到冻结期结束后再合入。判断是否为 feature以该 PR 是否引入新功能为界纯修复与内部重构不属于被冻结的对象。6. 通常适合合并的变更类型清单第 4 节列出了在满足核心合并要求与常规评审标准的前提下一般可接受的变更类型Bug fixes缺陷修复Refactoring重构Enhancements / speed improvements增强与性能改进Translations翻译New Effects (Fx)新效果器New commands新命令New panels新面板New presets新预设包括 Fx 预设、摄像机设置、快捷键等Changes to default user profiles默认用户档案变更包括偏好设置、面板布局、快捷键这些类型在仓库中都能找到对应的落地形态可作为贡献者选题的参考New Effects (Fx)toonz/sources/stdfx/306 个文件是内置效果器含 iwa 系列 GPU/CPU 效果器的实现目录stuff/fxs/presets/STD_particlesFx/下存放了 13 个粒效果器预设Bubbles.fx、Falling snow.fx、Fireworks.fx、Flock.fx、Rain.fx、Smoke.fx、Starfield.fx、Steam.fx等stuff/profiles/layouts/fxs/下还有按效果器分组的预设 XML如STD_adjustLevelsFx.xml、SHADER_*系列Translationstoonz/sources/translations/下存放 77 个 Qt 翻译源文件.ts按 CONTRIBUTING.md 的说明翻译工作使用 Qt Linguist并需同时提供.qm文件生成后放入stuff/config/loc由安装器安装到 stuff 目录New commands / New panels命令与面板的实现主要位于toonz/sources/toonz/与toonz/sources/toonzqt/后者含 97 个 cpp、160 个 svg 图标资源是面板与控件层的核心目录New presets / 默认用户档案预设与布局文件的默认集散地即上文提到的stuff/profiles/layouts/与stuff/config/。7. UI 变更User Interface Changes对于无法通过用户档案控制的 UI 变更——典型如向面板添加按钮、向上下文菜单添加命令——清单要求确认新增不会干扰常规/既有用法检查新 UI 元素是否不必要地阻碍、挤占或复杂化既定工作流当行为可能对不同工作流产生不同影响时考虑是否可合理地做成可选。清单给出的结论是只要能保留常规用法这类变更基本可以接受合入。也就是说UI 新增的审查重心不是加不加而是加了之后是否让原有用户的操作路径发生变化——新增按钮出现在面板角落与插入到常用操作快捷键序列中间前者大概率可接受后者则需要谨慎评估或提供开关。8. 既有 Fx 与渲染行为Existing Effects and Rendering Behavior这是本清单技术性最强、也最体现 OpenToonz生产软件属性的部分。对既有 Fx 或渲染行为的修改使用旧版本 OpenToonz 创建的场景/工作流进行测试确保变更不改变旧版本创建的场景的渲染结果将向后兼容渲染视为合并要求除非有明确审查过的理由需要打破兼容当新行为值得引入但会改变既有结果时考虑以可选/新模式提供而不是静默改变既有行为。这一条的深层原因在于OpenToonz 的场景文件.tnz与 Fx 网络是长生命周期的生产资产动画工作室可能用同一套场景跨越多个软件版本反复渲染输出。一个让新版本效果更好看但改变像素输出的改动会导致旧场景重新渲染时画面突变直接冲击生产一致性。仓库toonz/sources/stdfx/、toonz/sources/image/中保存的效果器与图像处理实现以及stuff/fxs/presets/中的既有预设都是渲染结果兼容条款的直接约束对象——贡献者在修改效果器时应额外做一次旧场景新旧版本渲染对比的验证而不是只看新效果的视觉表现。9. 工作流兼容性检查Workflow Compatibility Check由于 OpenToonz 支持多种不同的动画制作工作流传统赛璐璐手绘动画、无纸动画、特效合成、定格动画等toonz/sources/stopmotion/等目录即为不同管线模块考虑 PR 目标工作流之外的其他工作流询问改善一个工作流是否会给另一个带来劣势或行为变化在可行时保留既有工作流当多个合理工作流需求冲突时优先采用可选择/可选行为。工作流兼容性检查与第 2、7、8 节是一脉相承的核心合并原则在具体评审中分别落在默认配置层用户档案交互层UI和渲染层Fx 输出三个层面而可选化optional是贯穿三者的统一解法。10. 最终合并检查Final Merge Check合并前逐项核验既有用法保持可用既有工作流未被不必要地干扰修改既有 Fx/渲染行为时既有场景渲染保持兼容潜在冲突的工作流变更在合适位置已可选化没有需要 owner 审查的未解决许可问题PR 符合当前稳定版开发阶段release-phase的限制。这份终检清单本质上是前面所有章节的压缩汇总适合评审者在点下 Merge 按钮前作为最后一道速查。11. 配套流程从提交 PR 到合并清单之外仓库提供了完整的配套流程文档贡献者可将它们组合使用贡献与提交流程CONTRIBUTING.md 给出标准工作流fork → clone → 建分支如fix/fatal-bugs、feature/new-useful-gui→ 修改并测试 → 提交 →git pull --rebase upstream master同步上游 → 按 toonz/sources/.clang-format 格式化在toonz/sources下运行./beautification.sh或beautification.bat→ push → 发起 PR。格式化环节与代码评审可读性直接相关是进入评审前的硬性准备AI 辅助贡献doc/ai_assisted_development_checklist.md 针对 AI 辅助开发增加了 OT-Dev 探索规范与上游就绪门禁Upstream Readiness Gate每个 PR 单一主题、变更与理由必须成文、尽量附 AI 模型与版本信息、人类必须能解释与维护变更、AI 评审不能替代人类判断并最终仍须通过本文档的开发检查清单合入前的实测doc/how_to_test_prs.md 面向非开发者用户提供了在 PR 合并前试用构建产物的完整方法通过 AppVeyor CIappveyor.yml配置或 GitHub Actions 构建产物下载 OpenToonz 可执行包解压到独立目录运行切勿覆盖现有安装测试后可在 PR 评论区反馈。这也从实践层面呼应了清单反复强调的用旧场景/旧工作流验证不回归——社区的 PR 实测正是核心合并原则的群众化保障。12. 来源与适用范围该检查清单整理自 Shun Iwasawa 在 OpenToonz Discussion #6332 发布的开发政策其中心规则即PR 可以在不干扰既有用法does not interfere existing usages的前提下合并。本文以及原文档是对该政策的实践性重述属于草稿性质不取代维护者判断。另有一份面向AI 辅助贡献的独立检查清单doc/ai_assisted_development_checklist.md与之配套。无论是人工开发还是 AI 辅助开发向 OpenToonz 提交代码前对照本文第 210 节的每一项自检都是提高 PR 被顺利合入概率最直接有效的方式。【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考