Wagtail 核心团队代码提交（Committing）全流程指南：从 PR 检出到推送 main

Wagtail 核心团队代码提交Committing全流程指南从 PR 检出到推送 main【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail本篇指南基于 Wagtail 官方贡献文档 docs/contributing/committing.md 整理面向 Wagtail 核心团队成员Core Team或任何希望了解代码如何被正式合入 Wagtail 仓库的开发者。你将掌握一套完整的、可执行的提交工作流本地检出他人 Pull Request、交互式 rebase 整理提交、更新CHANGELOG.txt与版本发布说明、补充贡献者名单、最终推送到main分支以及在出错时如何安全回滚、如何直接为他人 PR 追加提交。适用范围与核心原则本流程仅适用于已通过审查的代码。Wagtail 的提交规则非常明确代码只有在至少经过一位其他审查者或提交者committer评审之后才能被提交唯一例外是小的文档修改或错别字修正。如果评审后又做了额外修改只要这些修改没有争议、足够小引入新 bug 的概率极低则允许不再复审直接提交。绝大多数代码贡献以 GitHub Pull Request 的形式存在但PR 不应直接通过 GitHub 网页上的合并按钮合入小文档修复可以用 Squash and merge 除外。正确的做法是由提交者把代码在本地检出、检查并 rebase更新变更日志与发布说明最后推送到main分支。第一步在本地检出 PR 代码如果代码以 Pull Request 形式提交提交者需要先在自己的 Wagtail 仓库中拉取该 PR 的分支。文档推荐在~/.gitconfig中增加一个git pr别名假设upstream指向wagtail/wagtail[alias] pr !sh -c git fetch upstream pull/${1}/head:pr/${1} git checkout pr/${1}配置完成后检出编号为xxxx的 PR 只需一行命令git pr xxxx该别名先执行git fetch upstream pull/xxxx/head:pr/xxxx把远端 PR 的 head 分支抓取为本地分支pr/xxxx再切换过去。这样提交者就可以在本地完整查看、修改和测试这段代码。完整的本地开发环境搭建Node.js/fnm、pip install -e .[testing,docs]、npm ci、npm run build、测试运行方式等可参考 docs/contributing/developing.md。第二步Rebase 到 main 分支拿到代码后下一步是把这些提交 rebase 到最新的main分支上。Wagtail 明确偏好 rebase 而非 merge——merge 提交会让小改动small changes的历史变得难以阅读。rebase 过程中可以顺手修正提交里的细小错误如错别字、格式问题git rebase --interactive即git rebase -i是完成这一工作的利器。理想情况下应借此机会把改动 squash 成少量几个提交让每个提交只做一件有意义的改动且不破坏任何东西。如果改动性质特殊无法这样整理则接受两种折中方案要么全部 squash 成一个提交要么保持所有提交不压缩——选择在提交历史中更易读的那种。文档给出的完整命令序列# Get the latest commits from Wagtail git fetch upstream git checkout main git merge --ff-only upstream/main # Rebase this pull request on to main git checkout pr/xxxx git rebase main # Update main to this commit git checkout main git merge --ff-only pr/xxxx注意这里git merge --ff-only的使用它保证只做快进合并绝不产生额外的 merge commit从而维持线性历史。git rebase main会把 PR 分支的提交逐个重放到最新的main之上任何冲突都会在此时暴露并处理。第三步更新 CHANGELOG.txt 与版本发布说明注意这一步只能由核心提交者core committers执行且必须在改动已经过审查和接受之后进行。每个对 Wagtail 有意义的改动都应该在 CHANGELOG.txt 和当前版本的发布说明release notes中获得一条记录。CHANGELOG.txt 的条目格式CHANGELOG.txt 收录每个版本中每项新特性、重构或 bug 修复的一行短摘要。为了让用户最容易定位到与自己相关的改动条目按以下顺序分组主要特性无前缀——能激励用户升级到新版本的东西次要增强无前缀——对开发者或最终用户体验的其它改进Bug 修复前缀 Fix:——修复上个版本中被破坏的行为文档前缀 Docs:——不伴随特定代码改动的文档变更如文档重组、教程、食谱等维护前缀 Maintenance:——不影响开发者或最终用户体验的清理、重构及代码/工具链改动每条摘要的末尾需要以括号形式加上贡献者姓名例如* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)以当前仓库 CHANGELOG.txt 的 8.1 开发版记录为例可以看到真实条目形态* Fix: Avoid redundant writes back to the cache on get_rendition and get_renditions (Mason Lyons, Matt Westcott) * Fix: Allow ChooserBlock.bulk_to_python() to resolve records with primary keys that need converting to their native type, such as UUIDs (Saksham Chawla) * Docs: Fix broken links to Cloudflare and Handsontable documentation (Roshan Ramani) * Maintenance: Drop support for Python 3.10一个条目对应一次提交行文要精炼多位作者时用逗号分隔列在括号内。版本发布说明Release notes每个版本的发布说明会对每项主要特性给出更详细的描述并拥有独立的小标题次要增强Other features、bug 修复、文档和维护则以项目符号列在对应标题下——这些可以直接从 changelog 复制过来只需去掉 Fix:、Docs: 或 Maintenance: 前缀。同时还应包含向后兼容性说明backwards compatibility notes可参考既往版本的发布说明作为范例。每个版本的发布说明存放在docs/releases/x.x.x.md例如当前仓库中的 docs/releases/8.1.md 与 docs/releases/8.0.md。以 docs/releases/8.0.md 为参照它会为 Wagtail REST API v3、自定义基础 Page 模型等大特性撰写独立小节再以 Other features、Bug fixes、Documentation、Maintenance 分组罗列小条目最后是 Upgrade considerations升级注意系列章节其中包含移除的废弃功能、影响所有项目/定制项/未文档化内部实现的变更说明这正是文档所说的向后兼容性说明的具体落点。首次贡献者加入 CONTRIBUTORS.md如果这是该贡献者第一次向 Wagtail 提交代码还应将其添加到 CONTRIBUTORS.md 列表中。规则如下按时间顺序排列新贡献者追加到列表底部使用对方偏好的名字通常可从 GitHub 主页找到拿不准或主页上查不到名字时直接询问对方希望如何署名。把记录并入提交如果这次要合入的改动小到可以是一个提交就把CHANGELOG.txt、发布说明和贡献者名单的增补 amend 进这个提交git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit --amend --no-edit如果改动无法塞进单个提交则为这些记录新建一个提交提交信息写Release notes for #xxxxgit add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit -m Release notes for #xxxx第四步推送到 main所有改动就绪后推送前先做检查再正式推送最后清理临时分支# Check that everything looks OK git log upstream/main..main --oneline git push --dry-run upstream main # Push the commits! git push upstream main git branch -d pr/xxxxgit log upstream/main..main --oneline以一行一条的方式预览即将推送到 upstream 的提交确认内容无误git push --dry-run upstream main做一次不实际发送的预演确认远程状态、认证与将要推送的提交推送成功后git branch -d pr/xxxx删除本地临时 PR 分支保持工作区整洁。第五步犯了错怎么办人非圣贤提交失误在所难免。文档给出的处置方式是一旦意识到最近合入的改动产生了负面影响立即创建一个包含回滚revert的新 PR并无需等待审查直接合并它。这个回滚 PR 本身会作为该改动的附加文档留存并且会完整跑一遍 CI 测试从而尽早暴露回滚是否引发其它问题。进阶往别人的 PR 上追加提交拥有 wagtail/wagtail 写权限的核心成员可以直接在贡献者的 PR 分支上追加提交。假设贡献者用户名为johndoe、其 PR 分支名为foogit clone gitgithub.com:wagtail/wagtail.git cd wagtail git remote add johndoe gitgithub.com:johndoe/wagtail.git git fetch johndoe foo git checkout johndoe/foo # Make changes # Commit changes git push johndoe HEAD:foo要点在于以johndoe为远程名添加贡献者的 fork抓取其分支检出后做修改并提交最后git push johndoe HEAD:foo直接推回贡献者的远程分支改动会自动更新到其 PR 中供后续评审和 CI 继续验证。与整体贡献流程的衔接本提交流程是 Wagtail 贡献体系的一环外部贡献者从 docs/contributing/index.md 入门按 docs/contributing/first_contribution_guide.md 完成首次贡献在 docs/contributing/developing.md 搭建本地开发环境并通过make lint、make format、pre-commit、python runtests.py等保证代码质量只有经过评审后被接受才会进入本文描述的提交者流程。将改动推送到main后它们随下一个版本进入 docs/releases/ 目录下的正式发布说明并在 CHANGELOG.txt 中留下对用户友好的索引——这正是 Wagtail 提交流程审查-整理-记录-推送四步闭环的设计意图。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考