OpenToonz 贡献指南从 Pull Request 工作流、Bug 报告到多语言翻译的完整实践【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz本指南以 OpenToonz 官方贡献文档 CONTRIBUTING.md 为核心系统讲解向 OpenToonz 提交贡献Pull Request、报告 Bug、提议新功能以及参与 GUI 多语言翻译的完整流程与规范。读完本文你将掌握一套可直接上手的贡献工作流包括分支管理、基于 clang-format 的代码格式化、与上游同步的 rebase 操作以及.ts/.qm翻译文件的生成与提交方法并能结合仓库内的 .clang-format、beautification.sh、appveyor.yml 等真实文件理解其背后的工程约定。一、贡献方式总览Pull Request 是唯一入口OpenToonz 是一个基于Toonz Studio Ghibli Version开发的开源全功能 2D 动画制作软件见 README.md。项目组织欢迎任何形式的贡献——从修正拼写错误、代码重构到新增功能与界面翻译统统可以通过Pull RequestPR提交。社区对 PR 的处理流程是固定的三步先review审查再决定accept接受、add comments for rework提出修改意见后返工或decline拒绝。这意味着提交前应自行充分测试减少审查往返审查意见是改进的一部分按意见返工后再次提交是正常流程即使被拒绝也有助于理解项目维护者的取舍标准。仓库的 doc/development_checklist.md 给出了更细的合并判定原则其核心一条是“只要不干扰现有用法PR 就可以被合并”。理解这条原则有助于你判断什么样的改动更容易被接受——例如新增可选行为、保留既有渲染结果不变、不破坏现有工作流等。二、Pull Request 完整工作流分步详解CONTRIBUTING.md 给出了一套从 fork 到 PR 的编号流程下面结合仓库实际结构逐条展开。第 0 步Fork 仓库进入opentoonz/opentoonz仓库页面点击页面右上角的Fork按钮将仓库复制到你的个人账号下。Fork 之后你拥有一个完全可控的副本后续所有修改都在这份副本上进行。第 1 步Clone 与配置 upstream将你的 fork 克隆到本地并把官方仓库添加为名为upstream的远程仓库用于随时同步上游最新代码git clone gitgithub.com:your-github-account/opentoonz.git git remote add upstream https://github.com/opentoonz/opentoonz.git实践建议clone 后先用git remote -v确认origin你的 fork与upstream官方仓库两条远程都已就位。此后origin用于推送你的分支upstream仅用于拉取合并。第 2 步创建功能分支并提交修改永远不要直接在master上开发而是基于最新的上游状态创建独立分支分支名应能体现改动意图git checkout -b your-branch-name文档给出的命名范例包括fix/fatal-bugs—— 修复严重 Bugfeature/new-useful-gui—— 新增 GUI 功能。建议采用类型/描述的语义化命名如fix/、feature/、refactor/这样在浏览 PR 列表时能一眼看出改动性质。修改完成后用信息完整、能说明“做了什么、为什么这么做”的提交信息提交git commit注意OpenToonz 的改动分散在多个子模块中——核心源码位于 toonz/sources 下的common、image、toonzlib、toonzqt、stdfx等目录每个目录都对应一个构建模块第三方依赖位于thirdparty/。提交前请确认只包含与你改动相关的文件不要把无关的构建产物或本地配置一并提交。第 3 步同步上游最新代码并格式化PR 被审查前需确保你的分支基于最新的上游master并应用项目统一的代码风格git pull upstream master # 或使用 git pull --rebase upstream master--rebase方式会把你的提交“垫”到上游最新提交之上形成线性历史推荐优先使用若出现冲突按冲突提示逐个解决后再git rebase --continue。随后对修改过的源码执行clang-format格式化。仓库在 toonz/sources/.clang-format 中固化了格式规则其关键配置包括配置项值含义BasedOnStyleGoogle以 Google 风格为基底Standardc17按 C17 标准解析代码UseTabNever一律使用空格缩进PointerAlignmentLeft指针星号靠左int* pAlignConsecutiveAssignmentstrue连续赋值语句按等号对齐AlignTrailingCommentstrue行尾注释对齐SortIncludesfalse不自动重排 include 顺序在toonz/sources目录下执行仓库自带的格式化脚本cd toonz/sources ./beautification.sh # 或 Windows 下的 beautification.bat查看 beautification.sh 的源码可以发现它的实现逻辑git diff master --name-only | egrep \.\(c\|cpp\|h\|hpp\)$ | xargs clang-format -stylefile -i即仅对相对master有改动且扩展名为.c、.cpp、.h、.hpp的源码文件以-stylefile模式读取.clang-format配置就地格式化-i。这意味着脚本只会触碰你真正改过的文件不会污染其他代码。格式化后如有改动再次提交git commit第 4 步推送并创建 Pull Requestgit push origin your-branch-name推送成功后GitHub 会给出创建 PR 的链接或在仓库页面选择你的分支后点击 “Compare pull request”。在 PR 描述中清晰说明改动内容、动机以及测试情况能显著加快审查速度。三、Bug 报告如何提供高质量 issue如果发现 Bug请通过仓库的Issues页报告并包含能够复现问题所需的全部信息操作系统如 Windows / macOS / Linux必要时注明版本号与问题直接相关的信息OpenToonz 版本、所用场景scene文件、相关操作步骤屏幕截图或录屏文档明确指出指向观察到的画面截图、或记录复现步骤的视频链接非常有帮助——渲染、绘画、特效类 Bug 尤其依赖可视化证据。维护者会尝试复现并修复。同时文档也坦诚地提醒部分 Bug 可能只在你的环境中出现上游无法复现这种情况下如果你有能力定位问题欢迎直接提交修复 PR。仓库在 doc/how_to_test_prs_chs.md另有英文版 doc/how_to_test_prs.md中提供了如何下载 CI 构建产物提前测试 PR 的图文步骤可用于验证“该 PR 是否修复了你遇到的 Bug”。四、新功能先实现再讨论如果你有新的功能想法首选路径是直接实现并提交 PR。若暂时无法自己实现可以在 Google Group 讨论页开启主题与社区共同探讨实现方案。文档特别注明了一项维护约定没有活跃开发者认领或缺乏资金支持的功能请求会被关闭以避免 issue 跟踪器被大量无法兑现的功能请求淹没。因此用 PR 说话是让功能落地的最高效方式。功能类 PR 还应留意 doc/development_checklist.md 中的几条约束修改既有 Fx 或渲染行为时不得改变旧版本创建场景的渲染结果若需要新行为应提供可选/新模式而非静默改变既有结果UI 变更应避免挤占、阻碍或复杂化既有工作流在稳定版发布前的冻结期功能类 PR 不会合入仅评估 Bug 修复等非功能改动。五、翻译贡献.ts / .qm 文件与 Qt LinguistOpenToonz GUI 的翻译源文件.ts位于toonz/sources/translations目录。仓库现状印证了文档描述该目录下已有chinese、japanese、french、german、korean、russian、spanish、italian、czech、norwegian_bokmal、portuguese_brazil等多个语言子目录并附带一个 update.sh 更新脚本以中文为例toonz/sources/translations/chinese 下包含toonz.ts、toonzqt.ts、tnztools.ts、toonzlib.ts、image.ts、colorfx.ts、tnzcore.ts等文件分别对应不同模块的界面字符串。贡献翻译的方式创建新语言或更新已有语言在translations下新增或修改.ts文件然后以 PR 形式提交使用 Qt Linguist 工具Qt Linguist 是 Qt 官方提供的翻译编辑器专门用于编辑.ts文件可逐条对照原文与译文同时提供.qm文件OpenToonz 运行时实际加载的是由.ts编译生成的.qm文件。如果你有能力做下述修改请将.qm与.ts一并提交用 Qt Linguist 的 “Release” 功能从.ts生成.qm将生成的.qm文件放入stuff/config/loc目录——这是文档规定的固定位置OpenToonz 安装器会把该目录中的.qm安装到stuff目录下使软件在运行时正确加载翻译。提示当前源码仓库的stuff/config下见 stuff/config并未包含loc子目录它属于安装期生成的运行时目录提交时请按文档约定放到stuff/config/loc由安装流程负责分发。六、仓库配套CI、代码风格与检查清单虽然 CONTRIBUTING.md 未展开但仓库为贡献者提供了直接相关的配套设施理解它们能让你的 PR 一次通过率更高持续集成CIappveyor.yml 配置了 Windows 上的 AppVeyor 构建对应toonz/sources的 CMake 构建并配置skip_commits规则——仅修改doc/**、.github/**或README.md时跳过构建GitHub Actions 则覆盖 Windows / macOS / Linux 三平台见 README.md 的徽章区。CI 会为每个 PR 自动编译并产出构件审查与测试者可直接下载验证流程见 doc/how_to_test_prs_chs.md。开发检查清单doc/development_checklist.md 总结了“不干扰既有用法”的合并核心原则、许可审查要求、稳定版冻结期规则以及 Bug 修复/重构/翻译/新 Fx/新命令/新面板/新预设等“一般适合合入”的改动类型。AI 辅助开发检查清单doc/ai_assisted_development_checklist.md 规定了使用 AI 辅助开发时的要求说明目的、测试或评估改动、对结果负责、标注 AI 协助信息、在提交上游前拆分主题、保留许可证与来源信息等。若你的贡献借助了 AI 工具建议先阅读该文档。代码风格toonz/sources/.clang-format 与 beautification.sh 已在上文详述是提交前必须执行的最后一环。七、总结一次合格的贡献提交清单综合 CONTRIBUTING.md 与仓库配套约定一次高质量的 OpenToonz 贡献应满足基于最新upstream master创建语义化分支如fix/、feature/改动范围聚焦单一主题提交信息完整git pull --rebase upstream master同步后在toonz/sources下执行./beautification.sh完成 clang-format 格式化并提交推送分支并创建描述清晰的 PR说明改动内容、动机与测试结果Bug 类问题在 issue 中提供操作系统、版本、复现步骤与截图/录屏功能类问题优先以 PR 实现翻译类改动在toonz/sources/translations下维护.ts用 Qt Linguist 生成.qm并放置到stuff/config/loc连同.ts一起提交。遵循这套流程无论你的贡献是修一个错别字还是新增一个 Fx 特效都能被 OpenToonz 社区高效地审查与合入。【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenToonz 贡献指南：从 Pull Request 工作流、Bug 报告到多语言翻译的完整实践
OpenToonz 贡献指南从 Pull Request 工作流、Bug 报告到多语言翻译的完整实践【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz本指南以 OpenToonz 官方贡献文档 CONTRIBUTING.md 为核心系统讲解向 OpenToonz 提交贡献Pull Request、报告 Bug、提议新功能以及参与 GUI 多语言翻译的完整流程与规范。读完本文你将掌握一套可直接上手的贡献工作流包括分支管理、基于 clang-format 的代码格式化、与上游同步的 rebase 操作以及.ts/.qm翻译文件的生成与提交方法并能结合仓库内的 .clang-format、beautification.sh、appveyor.yml 等真实文件理解其背后的工程约定。一、贡献方式总览Pull Request 是唯一入口OpenToonz 是一个基于Toonz Studio Ghibli Version开发的开源全功能 2D 动画制作软件见 README.md。项目组织欢迎任何形式的贡献——从修正拼写错误、代码重构到新增功能与界面翻译统统可以通过Pull RequestPR提交。社区对 PR 的处理流程是固定的三步先review审查再决定accept接受、add comments for rework提出修改意见后返工或decline拒绝。这意味着提交前应自行充分测试减少审查往返审查意见是改进的一部分按意见返工后再次提交是正常流程即使被拒绝也有助于理解项目维护者的取舍标准。仓库的 doc/development_checklist.md 给出了更细的合并判定原则其核心一条是“只要不干扰现有用法PR 就可以被合并”。理解这条原则有助于你判断什么样的改动更容易被接受——例如新增可选行为、保留既有渲染结果不变、不破坏现有工作流等。二、Pull Request 完整工作流分步详解CONTRIBUTING.md 给出了一套从 fork 到 PR 的编号流程下面结合仓库实际结构逐条展开。第 0 步Fork 仓库进入opentoonz/opentoonz仓库页面点击页面右上角的Fork按钮将仓库复制到你的个人账号下。Fork 之后你拥有一个完全可控的副本后续所有修改都在这份副本上进行。第 1 步Clone 与配置 upstream将你的 fork 克隆到本地并把官方仓库添加为名为upstream的远程仓库用于随时同步上游最新代码git clone gitgithub.com:your-github-account/opentoonz.git git remote add upstream https://github.com/opentoonz/opentoonz.git实践建议clone 后先用git remote -v确认origin你的 fork与upstream官方仓库两条远程都已就位。此后origin用于推送你的分支upstream仅用于拉取合并。第 2 步创建功能分支并提交修改永远不要直接在master上开发而是基于最新的上游状态创建独立分支分支名应能体现改动意图git checkout -b your-branch-name文档给出的命名范例包括fix/fatal-bugs—— 修复严重 Bugfeature/new-useful-gui—— 新增 GUI 功能。建议采用类型/描述的语义化命名如fix/、feature/、refactor/这样在浏览 PR 列表时能一眼看出改动性质。修改完成后用信息完整、能说明“做了什么、为什么这么做”的提交信息提交git commit注意OpenToonz 的改动分散在多个子模块中——核心源码位于 toonz/sources 下的common、image、toonzlib、toonzqt、stdfx等目录每个目录都对应一个构建模块第三方依赖位于thirdparty/。提交前请确认只包含与你改动相关的文件不要把无关的构建产物或本地配置一并提交。第 3 步同步上游最新代码并格式化PR 被审查前需确保你的分支基于最新的上游master并应用项目统一的代码风格git pull upstream master # 或使用 git pull --rebase upstream master--rebase方式会把你的提交“垫”到上游最新提交之上形成线性历史推荐优先使用若出现冲突按冲突提示逐个解决后再git rebase --continue。随后对修改过的源码执行clang-format格式化。仓库在 toonz/sources/.clang-format 中固化了格式规则其关键配置包括配置项值含义BasedOnStyleGoogle以 Google 风格为基底Standardc17按 C17 标准解析代码UseTabNever一律使用空格缩进PointerAlignmentLeft指针星号靠左int* pAlignConsecutiveAssignmentstrue连续赋值语句按等号对齐AlignTrailingCommentstrue行尾注释对齐SortIncludesfalse不自动重排 include 顺序在toonz/sources目录下执行仓库自带的格式化脚本cd toonz/sources ./beautification.sh # 或 Windows 下的 beautification.bat查看 beautification.sh 的源码可以发现它的实现逻辑git diff master --name-only | egrep \.\(c\|cpp\|h\|hpp\)$ | xargs clang-format -stylefile -i即仅对相对master有改动且扩展名为.c、.cpp、.h、.hpp的源码文件以-stylefile模式读取.clang-format配置就地格式化-i。这意味着脚本只会触碰你真正改过的文件不会污染其他代码。格式化后如有改动再次提交git commit第 4 步推送并创建 Pull Requestgit push origin your-branch-name推送成功后GitHub 会给出创建 PR 的链接或在仓库页面选择你的分支后点击 “Compare pull request”。在 PR 描述中清晰说明改动内容、动机以及测试情况能显著加快审查速度。三、Bug 报告如何提供高质量 issue如果发现 Bug请通过仓库的Issues页报告并包含能够复现问题所需的全部信息操作系统如 Windows / macOS / Linux必要时注明版本号与问题直接相关的信息OpenToonz 版本、所用场景scene文件、相关操作步骤屏幕截图或录屏文档明确指出指向观察到的画面截图、或记录复现步骤的视频链接非常有帮助——渲染、绘画、特效类 Bug 尤其依赖可视化证据。维护者会尝试复现并修复。同时文档也坦诚地提醒部分 Bug 可能只在你的环境中出现上游无法复现这种情况下如果你有能力定位问题欢迎直接提交修复 PR。仓库在 doc/how_to_test_prs_chs.md另有英文版 doc/how_to_test_prs.md中提供了如何下载 CI 构建产物提前测试 PR 的图文步骤可用于验证“该 PR 是否修复了你遇到的 Bug”。四、新功能先实现再讨论如果你有新的功能想法首选路径是直接实现并提交 PR。若暂时无法自己实现可以在 Google Group 讨论页开启主题与社区共同探讨实现方案。文档特别注明了一项维护约定没有活跃开发者认领或缺乏资金支持的功能请求会被关闭以避免 issue 跟踪器被大量无法兑现的功能请求淹没。因此用 PR 说话是让功能落地的最高效方式。功能类 PR 还应留意 doc/development_checklist.md 中的几条约束修改既有 Fx 或渲染行为时不得改变旧版本创建场景的渲染结果若需要新行为应提供可选/新模式而非静默改变既有结果UI 变更应避免挤占、阻碍或复杂化既有工作流在稳定版发布前的冻结期功能类 PR 不会合入仅评估 Bug 修复等非功能改动。五、翻译贡献.ts / .qm 文件与 Qt LinguistOpenToonz GUI 的翻译源文件.ts位于toonz/sources/translations目录。仓库现状印证了文档描述该目录下已有chinese、japanese、french、german、korean、russian、spanish、italian、czech、norwegian_bokmal、portuguese_brazil等多个语言子目录并附带一个 update.sh 更新脚本以中文为例toonz/sources/translations/chinese 下包含toonz.ts、toonzqt.ts、tnztools.ts、toonzlib.ts、image.ts、colorfx.ts、tnzcore.ts等文件分别对应不同模块的界面字符串。贡献翻译的方式创建新语言或更新已有语言在translations下新增或修改.ts文件然后以 PR 形式提交使用 Qt Linguist 工具Qt Linguist 是 Qt 官方提供的翻译编辑器专门用于编辑.ts文件可逐条对照原文与译文同时提供.qm文件OpenToonz 运行时实际加载的是由.ts编译生成的.qm文件。如果你有能力做下述修改请将.qm与.ts一并提交用 Qt Linguist 的 “Release” 功能从.ts生成.qm将生成的.qm文件放入stuff/config/loc目录——这是文档规定的固定位置OpenToonz 安装器会把该目录中的.qm安装到stuff目录下使软件在运行时正确加载翻译。提示当前源码仓库的stuff/config下见 stuff/config并未包含loc子目录它属于安装期生成的运行时目录提交时请按文档约定放到stuff/config/loc由安装流程负责分发。六、仓库配套CI、代码风格与检查清单虽然 CONTRIBUTING.md 未展开但仓库为贡献者提供了直接相关的配套设施理解它们能让你的 PR 一次通过率更高持续集成CIappveyor.yml 配置了 Windows 上的 AppVeyor 构建对应toonz/sources的 CMake 构建并配置skip_commits规则——仅修改doc/**、.github/**或README.md时跳过构建GitHub Actions 则覆盖 Windows / macOS / Linux 三平台见 README.md 的徽章区。CI 会为每个 PR 自动编译并产出构件审查与测试者可直接下载验证流程见 doc/how_to_test_prs_chs.md。开发检查清单doc/development_checklist.md 总结了“不干扰既有用法”的合并核心原则、许可审查要求、稳定版冻结期规则以及 Bug 修复/重构/翻译/新 Fx/新命令/新面板/新预设等“一般适合合入”的改动类型。AI 辅助开发检查清单doc/ai_assisted_development_checklist.md 规定了使用 AI 辅助开发时的要求说明目的、测试或评估改动、对结果负责、标注 AI 协助信息、在提交上游前拆分主题、保留许可证与来源信息等。若你的贡献借助了 AI 工具建议先阅读该文档。代码风格toonz/sources/.clang-format 与 beautification.sh 已在上文详述是提交前必须执行的最后一环。七、总结一次合格的贡献提交清单综合 CONTRIBUTING.md 与仓库配套约定一次高质量的 OpenToonz 贡献应满足基于最新upstream master创建语义化分支如fix/、feature/改动范围聚焦单一主题提交信息完整git pull --rebase upstream master同步后在toonz/sources下执行./beautification.sh完成 clang-format 格式化并提交推送分支并创建描述清晰的 PR说明改动内容、动机与测试结果Bug 类问题在 issue 中提供操作系统、版本、复现步骤与截图/录屏功能类问题优先以 PR 实现翻译类改动在toonz/sources/translations下维护.ts用 Qt Linguist 生成.qm并放置到stuff/config/loc连同.ts一起提交。遵循这套流程无论你的贡献是修一个错别字还是新增一个 Fx 特效都能被 OpenToonz 社区高效地审查与合入。【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考