隊(duì)代碼提交（Committing）全流程指南：從 PR 檢出到推送 main)
Wagtail 核心團(tuán)隊(duì)代碼提交Committing全流程指南從 PR 檢出到推送 main【免費(fèi)下載鏈接】wagtailA Django content management system focused on flexibility and user experience項(xiàng)目地址: https://gitcode.com/GitHub_Trending/wa/wagtail本篇指南基于 Wagtail 官方貢獻(xiàn)文檔 docs/contributing/committing.md 整理面向 Wagtail 核心團(tuán)隊(duì)成員Core Team或任何希望了解代碼如何被正式合入 Wagtail 倉(cāng)庫(kù)的開發(fā)者。你將掌握一套完整的、可執(zhí)行的提交工作流本地檢出他人 Pull Request、交互式 rebase 整理提交、更新CHANGELOG.txt與版本發(fā)布說明、補(bǔ)充貢獻(xiàn)者名單、最終推送到main分支以及在出錯(cuò)時(shí)如何安全回滾、如何直接為他人 PR 追加提交。適用范圍與核心原則本流程僅適用于已通過審查的代碼。Wagtail 的提交規(guī)則非常明確代碼只有在至少經(jīng)過一位其他審查者或提交者committer評(píng)審之后才能被提交唯一例外是小的文檔修改或錯(cuò)別字修正。如果評(píng)審后又做了額外修改只要這些修改沒有爭(zhēng)議、足夠小引入新 bug 的概率極低則允許不再?gòu)?fù)審直接提交。絕大多數(shù)代碼貢獻(xiàn)以 GitHub Pull Request 的形式存在但PR 不應(yīng)直接通過 GitHub 網(wǎng)頁上的合并按鈕合入小文檔修復(fù)可以用 Squash and merge 除外。正確的做法是由提交者把代碼在本地檢出、檢查并 rebase更新變更日志與發(fā)布說明最后推送到main分支。第一步在本地檢出 PR 代碼如果代碼以 Pull Request 形式提交提交者需要先在自己的 Wagtail 倉(cāng)庫(kù)中拉取該 PR 的分支。文檔推薦在~/.gitconfig中增加一個(gè)git pr別名假設(shè)upstream指向wagtail/wagtail[alias] pr !sh -c git fetch upstream pull/${1}/head:pr/${1} git checkout pr/${1}配置完成后檢出編號(hào)為xxxx的 PR 只需一行命令git pr xxxx該別名先執(zhí)行g(shù)it fetch upstream pull/xxxx/head:pr/xxxx把遠(yuǎn)端 PR 的 head 分支抓取為本地分支pr/xxxx再切換過去。這樣提交者就可以在本地完整查看、修改和測(cè)試這段代碼。完整的本地開發(fā)環(huán)境搭建Node.js/fnm、pip install -e .[testing,docs]、npm ci、npm run build、測(cè)試運(yùn)行方式等可參考 docs/contributing/developing.md。第二步Rebase 到 main 分支拿到代碼后下一步是把這些提交 rebase 到最新的main分支上。Wagtail 明確偏好 rebase 而非 merge——merge 提交會(huì)讓小改動(dòng)small changes的歷史變得難以閱讀。rebase 過程中可以順手修正提交里的細(xì)小錯(cuò)誤如錯(cuò)別字、格式問題git rebase --interactive即git rebase -i是完成這一工作的利器。理想情況下應(yīng)借此機(jī)會(huì)把改動(dòng) squash 成少量幾個(gè)提交讓每個(gè)提交只做一件有意義的改動(dòng)且不破壞任何東西。如果改動(dòng)性質(zhì)特殊無法這樣整理則接受兩種折中方案要么全部 squash 成一個(gè)提交要么保持所有提交不壓縮——選擇在提交歷史中更易讀的那種。文檔給出的完整命令序列# 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的使用它保證只做快進(jìn)合并絕不產(chǎn)生額外的 merge commit從而維持線性歷史。git rebase main會(huì)把 PR 分支的提交逐個(gè)重放到最新的main之上任何沖突都會(huì)在此時(shí)暴露并處理。第三步更新 CHANGELOG.txt 與版本發(fā)布說明注意這一步只能由核心提交者core committers執(zhí)行且必須在改動(dòng)已經(jīng)過審查和接受之后進(jìn)行。每個(gè)對(duì) Wagtail 有意義的改動(dòng)都應(yīng)該在 CHANGELOG.txt 和當(dāng)前版本的發(fā)布說明release notes中獲得一條記錄。CHANGELOG.txt 的條目格式CHANGELOG.txt 收錄每個(gè)版本中每項(xiàng)新特性、重構(gòu)或 bug 修復(fù)的一行短摘要。為了讓用戶最容易定位到與自己相關(guān)的改動(dòng)條目按以下順序分組主要特性無前綴——能激勵(lì)用戶升級(jí)到新版本的東西次要增強(qiáng)無前綴——對(duì)開發(fā)者或最終用戶體驗(yàn)的其它改進(jìn)Bug 修復(fù)前綴 Fix:——修復(fù)上個(gè)版本中被破壞的行為文檔前綴 Docs:——不伴隨特定代碼改動(dòng)的文檔變更如文檔重組、教程、食譜等維護(hù)前綴 Maintenance:——不影響開發(fā)者或最終用戶體驗(yàn)的清理、重構(gòu)及代碼/工具鏈改動(dòng)每條摘要的末尾需要以括號(hào)形式加上貢獻(xiàn)者姓名例如* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)以當(dāng)前倉(cāng)庫(kù) CHANGELOG.txt 的 8.1 開發(fā)版記錄為例可以看到真實(shí)條目形態(tài)* 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一個(gè)條目對(duì)應(yīng)一次提交行文要精煉多位作者時(shí)用逗號(hào)分隔列在括號(hào)內(nèi)。版本發(fā)布說明Release notes每個(gè)版本的發(fā)布說明會(huì)對(duì)每項(xiàng)主要特性給出更詳細(xì)的描述并擁有獨(dú)立的小標(biāo)題次要增強(qiáng)Other features、bug 修復(fù)、文檔和維護(hù)則以項(xiàng)目符號(hào)列在對(duì)應(yīng)標(biāo)題下——這些可以直接從 changelog 復(fù)制過來只需去掉 Fix:、Docs: 或 Maintenance: 前綴。同時(shí)還應(yīng)包含向后兼容性說明backwards compatibility notes可參考既往版本的發(fā)布說明作為范例。每個(gè)版本的發(fā)布說明存放在docs/releases/x.x.x.md例如當(dāng)前倉(cāng)庫(kù)中的 docs/releases/8.1.md 與 docs/releases/8.0.md。以 docs/releases/8.0.md 為參照它會(huì)為 Wagtail REST API v3、自定義基礎(chǔ) Page 模型等大特性撰寫?yīng)毩⑿」?jié)再以 Other features、Bug fixes、Documentation、Maintenance 分組羅列小條目最后是 Upgrade considerations升級(jí)注意系列章節(jié)其中包含移除的廢棄功能、影響所有項(xiàng)目/定制項(xiàng)/未文檔化內(nèi)部實(shí)現(xiàn)的變更說明這正是文檔所說的向后兼容性說明的具體落點(diǎn)。首次貢獻(xiàn)者加入 CONTRIBUTORS.md如果這是該貢獻(xiàn)者第一次向 Wagtail 提交代碼還應(yīng)將其添加到 CONTRIBUTORS.md 列表中。規(guī)則如下按時(shí)間順序排列新貢獻(xiàn)者追加到列表底部使用對(duì)方偏好的名字通常可從 GitHub 主頁找到拿不準(zhǔn)或主頁上查不到名字時(shí)直接詢問對(duì)方希望如何署名。把記錄并入提交如果這次要合入的改動(dòng)小到可以是一個(gè)提交就把CHANGELOG.txt、發(fā)布說明和貢獻(xiàn)者名單的增補(bǔ) amend 進(jìn)這個(gè)提交git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit --amend --no-edit如果改動(dòng)無法塞進(jìn)單個(gè)提交則為這些記錄新建一個(gè)提交提交信息寫Release notes for #xxxxgit add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit -m Release notes for #xxxx第四步推送到 main所有改動(dòng)就緒后推送前先做檢查再正式推送最后清理臨時(shí)分支# 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以一行一條的方式預(yù)覽即將推送到 upstream 的提交確認(rèn)內(nèi)容無誤git push --dry-run upstream main做一次不實(shí)際發(fā)送的預(yù)演確認(rèn)遠(yuǎn)程狀態(tài)、認(rèn)證與將要推送的提交推送成功后git branch -d pr/xxxx刪除本地臨時(shí) PR 分支保持工作區(qū)整潔。第五步犯了錯(cuò)怎么辦人非圣賢提交失誤在所難免。文檔給出的處置方式是一旦意識(shí)到最近合入的改動(dòng)產(chǎn)生了負(fù)面影響立即創(chuàng)建一個(gè)包含回滾revert的新 PR并無需等待審查直接合并它。這個(gè)回滾 PR 本身會(huì)作為該改動(dòng)的附加文檔留存并且會(huì)完整跑一遍 CI 測(cè)試從而盡早暴露回滾是否引發(fā)其它問題。進(jìn)階往別人的 PR 上追加提交擁有 wagtail/wagtail 寫權(quán)限的核心成員可以直接在貢獻(xiàn)者的 PR 分支上追加提交。假設(shè)貢獻(xiàn)者用戶名為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要點(diǎn)在于以johndoe為遠(yuǎn)程名添加貢獻(xiàn)者的 fork抓取其分支檢出后做修改并提交最后git push johndoe HEAD:foo直接推回貢獻(xiàn)者的遠(yuǎn)程分支改動(dòng)會(huì)自動(dòng)更新到其 PR 中供后續(xù)評(píng)審和 CI 繼續(xù)驗(yàn)證。與整體貢獻(xiàn)流程的銜接本提交流程是 Wagtail 貢獻(xiàn)體系的一環(huán)外部貢獻(xiàn)者從 docs/contributing/index.md 入門按 docs/contributing/first_contribution_guide.md 完成首次貢獻(xiàn)在 docs/contributing/developing.md 搭建本地開發(fā)環(huán)境并通過make lint、make format、pre-commit、python runtests.py等保證代碼質(zhì)量只有經(jīng)過評(píng)審后被接受才會(huì)進(jìn)入本文描述的提交者流程。將改動(dòng)推送到main后它們隨下一個(gè)版本進(jìn)入 docs/releases/ 目錄下的正式發(fā)布說明并在 CHANGELOG.txt 中留下對(duì)用戶友好的索引——這正是 Wagtail 提交流程審查-整理-記錄-推送四步閉環(huán)的設(shè)計(jì)意圖。【免費(fèi)下載鏈接】wagtailA Django content management system focused on flexibility and user experience項(xiàng)目地址: https://gitcode.com/GitHub_Trending/wa/wagtail創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Wagtail 核心團(tuán)隊(duì)代碼提交（Committing）全流程指南：從 PR 檢出到推送 main
Wagtail 核心團(tuán)隊(duì)代碼提交Committing全流程指南從 PR 檢出到推送 main【免費(fèi)下載鏈接】wagtailA Django content management system focused on flexibility and user experience項(xiàng)目地址: https://gitcode.com/GitHub_Trending/wa/wagtail本篇指南基于 Wagtail 官方貢獻(xiàn)文檔 docs/contributing/committing.md 整理面向 Wagtail 核心團(tuán)隊(duì)成員Core Team或任何希望了解代碼如何被正式合入 Wagtail 倉(cāng)庫(kù)的開發(fā)者。你將掌握一套完整的、可執(zhí)行的提交工作流本地檢出他人 Pull Request、交互式 rebase 整理提交、更新CHANGELOG.txt與版本發(fā)布說明、補(bǔ)充貢獻(xiàn)者名單、最終推送到main分支以及在出錯(cuò)時(shí)如何安全回滾、如何直接為他人 PR 追加提交。適用范圍與核心原則本流程僅適用于已通過審查的代碼。Wagtail 的提交規(guī)則非常明確代碼只有在至少經(jīng)過一位其他審查者或提交者committer評(píng)審之后才能被提交唯一例外是小的文檔修改或錯(cuò)別字修正。如果評(píng)審后又做了額外修改只要這些修改沒有爭(zhēng)議、足夠小引入新 bug 的概率極低則允許不再?gòu)?fù)審直接提交。絕大多數(shù)代碼貢獻(xiàn)以 GitHub Pull Request 的形式存在但PR 不應(yīng)直接通過 GitHub 網(wǎng)頁上的合并按鈕合入小文檔修復(fù)可以用 Squash and merge 除外。正確的做法是由提交者把代碼在本地檢出、檢查并 rebase更新變更日志與發(fā)布說明最后推送到main分支。第一步在本地檢出 PR 代碼如果代碼以 Pull Request 形式提交提交者需要先在自己的 Wagtail 倉(cāng)庫(kù)中拉取該 PR 的分支。文檔推薦在~/.gitconfig中增加一個(gè)git pr別名假設(shè)upstream指向wagtail/wagtail[alias] pr !sh -c git fetch upstream pull/${1}/head:pr/${1} git checkout pr/${1}配置完成后檢出編號(hào)為xxxx的 PR 只需一行命令git pr xxxx該別名先執(zhí)行g(shù)it fetch upstream pull/xxxx/head:pr/xxxx把遠(yuǎn)端 PR 的 head 分支抓取為本地分支pr/xxxx再切換過去。這樣提交者就可以在本地完整查看、修改和測(cè)試這段代碼。完整的本地開發(fā)環(huán)境搭建Node.js/fnm、pip install -e .[testing,docs]、npm ci、npm run build、測(cè)試運(yùn)行方式等可參考 docs/contributing/developing.md。第二步Rebase 到 main 分支拿到代碼后下一步是把這些提交 rebase 到最新的main分支上。Wagtail 明確偏好 rebase 而非 merge——merge 提交會(huì)讓小改動(dòng)small changes的歷史變得難以閱讀。rebase 過程中可以順手修正提交里的細(xì)小錯(cuò)誤如錯(cuò)別字、格式問題git rebase --interactive即git rebase -i是完成這一工作的利器。理想情況下應(yīng)借此機(jī)會(huì)把改動(dòng) squash 成少量幾個(gè)提交讓每個(gè)提交只做一件有意義的改動(dòng)且不破壞任何東西。如果改動(dòng)性質(zhì)特殊無法這樣整理則接受兩種折中方案要么全部 squash 成一個(gè)提交要么保持所有提交不壓縮——選擇在提交歷史中更易讀的那種。文檔給出的完整命令序列# 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的使用它保證只做快進(jìn)合并絕不產(chǎn)生額外的 merge commit從而維持線性歷史。git rebase main會(huì)把 PR 分支的提交逐個(gè)重放到最新的main之上任何沖突都會(huì)在此時(shí)暴露并處理。第三步更新 CHANGELOG.txt 與版本發(fā)布說明注意這一步只能由核心提交者core committers執(zhí)行且必須在改動(dòng)已經(jīng)過審查和接受之后進(jìn)行。每個(gè)對(duì) Wagtail 有意義的改動(dòng)都應(yīng)該在 CHANGELOG.txt 和當(dāng)前版本的發(fā)布說明release notes中獲得一條記錄。CHANGELOG.txt 的條目格式CHANGELOG.txt 收錄每個(gè)版本中每項(xiàng)新特性、重構(gòu)或 bug 修復(fù)的一行短摘要。為了讓用戶最容易定位到與自己相關(guān)的改動(dòng)條目按以下順序分組主要特性無前綴——能激勵(lì)用戶升級(jí)到新版本的東西次要增強(qiáng)無前綴——對(duì)開發(fā)者或最終用戶體驗(yàn)的其它改進(jìn)Bug 修復(fù)前綴 Fix:——修復(fù)上個(gè)版本中被破壞的行為文檔前綴 Docs:——不伴隨特定代碼改動(dòng)的文檔變更如文檔重組、教程、食譜等維護(hù)前綴 Maintenance:——不影響開發(fā)者或最終用戶體驗(yàn)的清理、重構(gòu)及代碼/工具鏈改動(dòng)每條摘要的末尾需要以括號(hào)形式加上貢獻(xiàn)者姓名例如* Fix: Tags added on the multiple image uploader are now saved correctly (Alex Smith)以當(dāng)前倉(cāng)庫(kù) CHANGELOG.txt 的 8.1 開發(fā)版記錄為例可以看到真實(shí)條目形態(tài)* 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一個(gè)條目對(duì)應(yīng)一次提交行文要精煉多位作者時(shí)用逗號(hào)分隔列在括號(hào)內(nèi)。版本發(fā)布說明Release notes每個(gè)版本的發(fā)布說明會(huì)對(duì)每項(xiàng)主要特性給出更詳細(xì)的描述并擁有獨(dú)立的小標(biāo)題次要增強(qiáng)Other features、bug 修復(fù)、文檔和維護(hù)則以項(xiàng)目符號(hào)列在對(duì)應(yīng)標(biāo)題下——這些可以直接從 changelog 復(fù)制過來只需去掉 Fix:、Docs: 或 Maintenance: 前綴。同時(shí)還應(yīng)包含向后兼容性說明backwards compatibility notes可參考既往版本的發(fā)布說明作為范例。每個(gè)版本的發(fā)布說明存放在docs/releases/x.x.x.md例如當(dāng)前倉(cāng)庫(kù)中的 docs/releases/8.1.md 與 docs/releases/8.0.md。以 docs/releases/8.0.md 為參照它會(huì)為 Wagtail REST API v3、自定義基礎(chǔ) Page 模型等大特性撰寫?yīng)毩⑿」?jié)再以 Other features、Bug fixes、Documentation、Maintenance 分組羅列小條目最后是 Upgrade considerations升級(jí)注意系列章節(jié)其中包含移除的廢棄功能、影響所有項(xiàng)目/定制項(xiàng)/未文檔化內(nèi)部實(shí)現(xiàn)的變更說明這正是文檔所說的向后兼容性說明的具體落點(diǎn)。首次貢獻(xiàn)者加入 CONTRIBUTORS.md如果這是該貢獻(xiàn)者第一次向 Wagtail 提交代碼還應(yīng)將其添加到 CONTRIBUTORS.md 列表中。規(guī)則如下按時(shí)間順序排列新貢獻(xiàn)者追加到列表底部使用對(duì)方偏好的名字通常可從 GitHub 主頁找到拿不準(zhǔn)或主頁上查不到名字時(shí)直接詢問對(duì)方希望如何署名。把記錄并入提交如果這次要合入的改動(dòng)小到可以是一個(gè)提交就把CHANGELOG.txt、發(fā)布說明和貢獻(xiàn)者名單的增補(bǔ) amend 進(jìn)這個(gè)提交git add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit --amend --no-edit如果改動(dòng)無法塞進(jìn)單個(gè)提交則為這些記錄新建一個(gè)提交提交信息寫Release notes for #xxxxgit add CHANGELOG.txt docs/releases/x.x.x.md CONTRIBUTORS.md git commit -m Release notes for #xxxx第四步推送到 main所有改動(dòng)就緒后推送前先做檢查再正式推送最后清理臨時(shí)分支# 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以一行一條的方式預(yù)覽即將推送到 upstream 的提交確認(rèn)內(nèi)容無誤git push --dry-run upstream main做一次不實(shí)際發(fā)送的預(yù)演確認(rèn)遠(yuǎn)程狀態(tài)、認(rèn)證與將要推送的提交推送成功后git branch -d pr/xxxx刪除本地臨時(shí) PR 分支保持工作區(qū)整潔。第五步犯了錯(cuò)怎么辦人非圣賢提交失誤在所難免。文檔給出的處置方式是一旦意識(shí)到最近合入的改動(dòng)產(chǎn)生了負(fù)面影響立即創(chuàng)建一個(gè)包含回滾revert的新 PR并無需等待審查直接合并它。這個(gè)回滾 PR 本身會(huì)作為該改動(dòng)的附加文檔留存并且會(huì)完整跑一遍 CI 測(cè)試從而盡早暴露回滾是否引發(fā)其它問題。進(jìn)階往別人的 PR 上追加提交擁有 wagtail/wagtail 寫權(quán)限的核心成員可以直接在貢獻(xiàn)者的 PR 分支上追加提交。假設(shè)貢獻(xiàn)者用戶名為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要點(diǎn)在于以johndoe為遠(yuǎn)程名添加貢獻(xiàn)者的 fork抓取其分支檢出后做修改并提交最后git push johndoe HEAD:foo直接推回貢獻(xiàn)者的遠(yuǎn)程分支改動(dòng)會(huì)自動(dòng)更新到其 PR 中供后續(xù)評(píng)審和 CI 繼續(xù)驗(yàn)證。與整體貢獻(xiàn)流程的銜接本提交流程是 Wagtail 貢獻(xiàn)體系的一環(huán)外部貢獻(xiàn)者從 docs/contributing/index.md 入門按 docs/contributing/first_contribution_guide.md 完成首次貢獻(xiàn)在 docs/contributing/developing.md 搭建本地開發(fā)環(huán)境并通過make lint、make format、pre-commit、python runtests.py等保證代碼質(zhì)量只有經(jīng)過評(píng)審后被接受才會(huì)進(jìn)入本文描述的提交者流程。將改動(dòng)推送到main后它們隨下一個(gè)版本進(jìn)入 docs/releases/ 目錄下的正式發(fā)布說明并在 CHANGELOG.txt 中留下對(duì)用戶友好的索引——這正是 Wagtail 提交流程審查-整理-記錄-推送四步閉環(huán)的設(shè)計(jì)意圖。【免費(fèi)下載鏈接】wagtailA Django content management system focused on flexibility and user experience項(xiàng)目地址: https://gitcode.com/GitHub_Trending/wa/wagtail創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考