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 #xxxx：

git 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/xxxx

• git 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 分支名为foo：

git clone [e-mail]:wagtail/wagtail.git cd wagtail git remote add johndoe [e-mail]: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