編寫 Remix 倉(cāng)庫(kù) Change Files.changes 發(fā)布說(shuō)明約定與完整工作流【免費(fèi)下載鏈接】remixThe fully-stacked web framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/remix導(dǎo)讀本文圍繞 Remix 倉(cāng)庫(kù)的make-changes技能規(guī)范.agents/skills/make-changes/SKILL.md完整講解在packages/*/.changes目錄下編寫與維護(hù)發(fā)布說(shuō)明release notes的命名約定、bump 規(guī)則、內(nèi)容規(guī)范與校驗(yàn)流程。讀完本文你將掌握如何為新增功能、破壞性變更、棄用和缺陷修復(fù)正確編寫 change file如何在 0.x 與 1.x 版本策略下選擇 bump 類型以及如何用pnpm changes:preview、pnpm changes:validate、pnpm changes:version三條命令驅(qū)動(dòng)變更校驗(yàn)、CHANGELOG 生成與版本提交。make-changes 技能定位make-changes是倉(cāng)庫(kù)內(nèi)面向 Agent 與開(kāi)發(fā)者的技能skill其 frontmatter 明確聲明了適用場(chǎng)景當(dāng)用戶請(qǐng)求發(fā)布說(shuō)明、變更記錄、缺失的 changelog 條目、預(yù)發(fā)布prerelease說(shuō)明或需要更新現(xiàn)有未發(fā)布變更記錄時(shí)都應(yīng)調(diào)用該技能。技能的完整定義位于 .agents/skills/make-changes/SKILL.md與之配套的 Agent 配置見(jiàn) .agents/skills/make-changes/agents/openai.yaml。該技能的核心目標(biāo)是用統(tǒng)一約定管理每個(gè)包未發(fā)布的變更使remix及其全部remix-run/*子包的 CHANGELOG 可以由腳本自動(dòng)、確定性地生成。從倉(cāng)庫(kù)根目錄的 package.json 可以看到三條配套腳本pnpm changes:preview→ 運(yùn)行 scripts/changes-preview.ts預(yù)覽渲染后的 changelog 輸出與發(fā)布列表pnpm changes:validate→ 運(yùn)行 scripts/changes-validate.ts校驗(yàn)全部 change file 與 CHANGELOG 完整性pnpm changes:version→ 運(yùn)行 scripts/changes-version.ts真正更新版本號(hào)、生成 CHANGELOG 并創(chuàng)建發(fā)布提交。完整工作流按技能規(guī)范編寫一份 change file 的標(biāo)準(zhǔn)流程如下讀取目標(biāo)包的package.json、已存在的.changes/目錄以及相關(guān)的 PR diff 或 commit 范圍確定變更的上下文與影響面。檢查是否已存在針對(duì)同一工作的未發(fā)布 change file若存在直接就地更新而不是新建重復(fù)條目避免同一變更在 CHANGELOG 中出現(xiàn)兩次。根據(jù)包的當(dāng)前版本與對(duì)用戶的影響面選擇 bump 類型major / minor / patch。若packages/package/.changes/目錄尚不存在按需創(chuàng)建。編寫面向用戶的發(fā)布說(shuō)明描述已交付的行為、API、導(dǎo)出、遷移或升級(jí)工作。運(yùn)行pnpm changes:preview驗(yàn)證渲染后的 changelog 輸出是否符合預(yù)期。若本次任務(wù)同時(shí)改動(dòng)了代碼、包元數(shù)據(jù)、文檔或發(fā)布工具再運(yùn)行 lint 或更廣泛的校驗(yàn)例如pnpm changes:validate。其中第 2 步是防止重復(fù)的關(guān)鍵change file 是未發(fā)布變更的暫存區(qū)同一邏輯變更不應(yīng)同時(shí)存在兩份說(shuō)明腳本在發(fā)布時(shí)會(huì)把變更折疊進(jìn) CHANGELOG 并刪除暫存文件見(jiàn) scripts/changes-version.ts 的deleteChangeFiles邏輯。Bump 規(guī)則0.x 與 1.x 的版本語(yǔ)義0.x 包的約定新功能與破壞性變更一律使用minor缺陷修復(fù)使用patch除非被明確指示否則不得對(duì) 0.x 包使用major0.x 下破壞性變更說(shuō)明必須以BREAKING CHANGE:開(kāi)頭。這一約定并非只是口頭規(guī)范校驗(yàn)?zāi)_本中實(shí)現(xiàn)了對(duì)應(yīng)強(qiáng)制邏輯。scripts/utils/changes.ts 會(huì)檢查對(duì) 1.x 包若內(nèi)容檢測(cè)到BREAKING CHANGE:前綴而 bump 不是major則報(bào)錯(cuò)并提示重命名為major.slug.md對(duì) 0.x 包且當(dāng)前版本非預(yù)發(fā)布若含破壞性前綴而 bump 不是minor同樣報(bào)錯(cuò)并提示重命名為minor.slug.md。前綴檢測(cè)由hasBreakingChangePrefix實(shí)現(xiàn)scripts/utils/changes.ts忽略首部空白與*/_加粗標(biāo)記后以小寫方式匹配breaking change:開(kāi)頭。1.x 包按標(biāo)準(zhǔn) semver 處理破壞性變更走major新功能走minor缺陷修復(fù)走patch。其他版本規(guī)則破壞性變更的判定基準(zhǔn)是相對(duì)main分支而非同一 PR 內(nèi)的早期 commit在remix的預(yù)發(fā)布模式下bump 類型主要決定 changelog 的分類Major/Minor/Patch Changes 分組實(shí)際版本號(hào)由預(yù)發(fā)布計(jì)數(shù)器推進(jìn)而不是由 bump 類型決定。這一點(diǎn)在 scripts/utils/changes.ts 的getNextVersion中實(shí)現(xiàn)當(dāng)包配置了prereleaseChannel且當(dāng)前版本已處于同一通道時(shí)僅調(diào)用 semver 的prerelease遞增計(jì)數(shù)器不再應(yīng)用 bump 類型。文件放置與命名命名模板通用命名packages/package/.changes/[major|minor|patch].short-description.mdslug描述段要求簡(jiǎn)短、具體、穩(wěn)定當(dāng)倉(cāng)庫(kù)對(duì)該類說(shuō)明已有確定性的命名模式時(shí)復(fù)用既有名稱保證同類條目命名可預(yù)期全新包的首次發(fā)布優(yōu)先使用minor.initial-release.mdremix包導(dǎo)出變更更新packages/remix/.changes/minor.remix.update-exports.md這一固定文件而不是發(fā)明一次性文件名對(duì)應(yīng)規(guī)范Remix-Specific Rules一節(jié)當(dāng)packages/remix/.changes鏡像某個(gè)被再導(dǎo)出包的 change file 時(shí)命名格式為packages/remix/.changes/[major|minor|patch].package.short-description.md其中package去掉remix-run/作用域前綴。文件名解析與強(qiáng)制校驗(yàn)?zāi)_本對(duì)文件名的解析邏輯位于 scripts/utils/changes.ts文件必須以.md結(jié)尾且文件名開(kāi)頭必須是major.、minor.或patch.前綴加非空描述否則直接報(bào)錯(cuò)預(yù)發(fā)布模式下例外bump 類型不影響版本號(hào)因此允許任意文件名此時(shí)統(tǒng)一按patch歸類。.changes目錄下僅README.md與config.json被跳過(guò)不參與解析。目錄與依賴關(guān)系.changes目錄按包組織位于每個(gè)包的packages/package/.changes/下。發(fā)布工具鏈在 scripts/utils/changes.ts 中還會(huì)計(jì)算直接變更包的傳遞依賴凡是依賴了被變更包的包也會(huì)被納入本次發(fā)布dependency-triggered release并自動(dòng)為其生成依賴升級(jí)dependency bump的 changelog 條目。說(shuō)明內(nèi)容編寫規(guī)范寫什么記錄用戶可見(jiàn)的行為、公開(kāi) API 變更、導(dǎo)出、遷移或升級(jí)工作內(nèi)部重構(gòu)如果沒(méi)有體現(xiàn)為真實(shí)的 API 或行為變化不要寫發(fā)布說(shuō)明每條說(shuō)明必須自包含讀者僅憑該條說(shuō)明即可理解交付的行為鏈接用于補(bǔ)充上下文而不是替代解釋當(dāng)變更關(guān)聯(lián)公開(kāi) issue、PR、RFC、decision doc、spec 或外部缺陷報(bào)告時(shí)在說(shuō)明中附上簡(jiǎn)短引用。優(yōu)先引用真正解決了該 issue/功能的 PRissue 可以從 PR 反查到同倉(cāng)庫(kù)引用使用行內(nèi)形式如(see #1234)外部倉(cāng)庫(kù)、spec 或報(bào)告使用完整 URL明確指出受影響的 API、路由約定、包、入口、運(yùn)行時(shí)、瀏覽器或工具版本幫助用戶判斷該說(shuō)明是否適用于自己。不同類型變更的寫法缺陷修復(fù)描述用戶可見(jiàn)的癥狀或失敗場(chǎng)景而不是只描述實(shí)現(xiàn)層的修復(fù)破壞性變更同時(shí)給出舊行為、新行為與遷移路徑棄用如果存在替代 API必須提及。格式約束不要手動(dòng)對(duì).changes/*.md中的散文做硬換行每個(gè)段落或列表項(xiàng)保持單行源碼由渲染后的 changelog 自然換行扁平列表僅在有助于清晰表達(dá)時(shí)使用短段落通常更合適除非被明確要求不要編輯歷史CHANGELOG.md條目?jī)H允許諸如修復(fù)壞鏈、錯(cuò)別字或明顯無(wú)效引用這類窄范圍修正。腳本側(cè)的格式校驗(yàn)scripts/utils/changes.ts 對(duì)內(nèi)容實(shí)施硬性校驗(yàn)change file 不能為空第一行不能以-或*開(kāi)頭的列表項(xiàng)開(kāi)始——CHANGELOG 渲染時(shí)會(huì)自動(dòng)為每條說(shuō)明加 bulletformatChangelogEntry會(huì)把首行轉(zhuǎn)為- xxx手寫 bullet 會(huì)導(dǎo)致重復(fù)標(biāo)題級(jí)別只能是 4、5、6 級(jí)####/#####/######禁止 1-3 級(jí)或 7 級(jí)以上標(biāo)題因?yàn)?change file 最終嵌套在已占用 1-3 級(jí)標(biāo)題的 changelog 內(nèi)部。包歸屬誰(shuí)該寫 change file規(guī)范的Package Ownership一節(jié)給出清晰的職責(zé)劃分手動(dòng) change file 應(yīng)加到擁有被變更 API、行為或?qū)崿F(xiàn)的那個(gè)包若另一包通過(guò)再導(dǎo)出re-export暴露了新增、刪除、重命名或變更的公開(kāi) API且用戶可通過(guò)該再導(dǎo)出入口消費(fèi)這些 API則再導(dǎo)出包也要寫 change file不要為僅通過(guò)依賴升級(jí)間接觀察到變更的包手動(dòng)添加 change file——發(fā)布腳本已包含傳遞依賴方并會(huì)為其生成依賴升級(jí)條目底層包的缺陷修復(fù)通常只給擁有該修復(fù)的包寫 change file僅當(dāng)再導(dǎo)出包自身的 changelog 需要直接點(diǎn)名該行為而不僅僅因?yàn)樾迯?fù)的依賴可達(dá)時(shí)才額外寫再導(dǎo)出包條目。Remix 特有的約束packages/remix/src/*的再導(dǎo)出文件是生成產(chǎn)物除非任務(wù)明確要求生成輸出否則不要手工編輯當(dāng)packages/remix/package.json新增或改變公開(kāi)導(dǎo)出時(shí)記錄到固定的minor.remix.update-exports.md不要發(fā)明一次性文件名如果變更通過(guò)remix/...暴露了其他包的新 API說(shuō)明要描述被暴露的remix/...入口而不僅是底層 workspace 包名。粒度層級(jí)包級(jí)說(shuō)明與 remix 匯總說(shuō)明規(guī)范的Detail Levels一節(jié)區(qū)分了兩級(jí)說(shuō)明的寫作深度包級(jí) change file 是事實(shí)來(lái)源source of truth。子包說(shuō)明需包含用戶理解變更所需的具體 API、行為、運(yùn)行時(shí)或工具細(xì)節(jié)當(dāng)新 API、遷移、破壞性變更或用法模式改變能借助 before/after 示例講清楚時(shí)務(wù)必包含同時(shí)附上有用的 PR、issue、RFC、decision、spec 或外部報(bào)告鏈接優(yōu)先引用能提供完整脈絡(luò)的實(shí)現(xiàn) PR。packages/remix/.changes的條目則要像面向remix用戶的傘式發(fā)布摘要比底層包說(shuō)明更簡(jiǎn)短聚焦于暴露出來(lái)的remix/...入口或發(fā)布級(jí)影響。不要把一個(gè)子包說(shuō)明中的詳細(xì)示例、遷移散文或?qū)崿F(xiàn)背景復(fù)制進(jìn)remix說(shuō)明除非傘式包自身行為發(fā)生了變化當(dāng)remix說(shuō)明匯總子包變更時(shí)鏈接到底層 changelog、release、PR 或其他可持久追蹤的細(xì)節(jié)來(lái)源方便讀者下鉆發(fā)布工具已自動(dòng)為發(fā)布的包 tag 添加依賴升級(jí)鏈接因此不要在remixchange file 中手工重建依賴升級(jí)列表。命令行驗(yàn)證preview、validate、versionpnpm changes:preview預(yù)覽scripts/changes-preview.ts 首先調(diào)用parseAllChangeFiles做全量解析與校驗(yàn)失敗則以紅色錯(cuò)誤信息退出exit 1成功且存在變更時(shí)依次打印有變更的包列表格式為包名: 當(dāng)前版本 → 下一版本 (bump 類型)每個(gè)包對(duì)應(yīng)的 CHANGELOG 渲染預(yù)覽生成的提交信息后續(xù)應(yīng)執(zhí)行的pnpm changes:version提示。若所有包都無(wú)待發(fā)布變更則打印No packages have changes to release.并正常退出。pnpm changes:validate校驗(yàn)scripts/changes-validate.ts 做兩件事遍歷全部包目錄檢查是否存在CHANGELOG.md缺失則報(bào)錯(cuò)調(diào)用parseAllChangeFiles校驗(yàn)所有 change file 的命名、內(nèi)容格式、bump 規(guī)則與預(yù)發(fā)布配置一致性。任一環(huán)節(jié)出錯(cuò)都會(huì)以 exit code 1 退出適合接入 CI 前置檢查。pnpm changes:version落地版本scripts/changes-version.ts 在通過(guò)全量校驗(yàn)后按發(fā)布列表逐個(gè)包執(zhí)行更新package.json的version字段在CHANGELOG.md中插入新版本條目插入到第一個(gè)##版本條目之前無(wú)版本條目時(shí)追加到末尾刪除.changes/下所有待發(fā)布 md change file空目錄一并移除默認(rèn)執(zhí)行g(shù)it add .并創(chuàng)建提交信息形如Release- 包名: 當(dāng)前版本 - 下一版本的提交傳--no-commit參數(shù)時(shí)只更新文件不提交并打印供人工審閱與手動(dòng)git commit的指引。預(yù)發(fā)布prerelease模式細(xì)節(jié)預(yù)發(fā)布相關(guān)的配置與校驗(yàn)邏輯集中在 scripts/utils/changes.ts 與 scripts/utils/changes.ts每個(gè)包可在.changes/config.json中聲明prereleaseChannel非空字符串與可選的prereleaseStart非負(fù)整數(shù)且要求必須同時(shí)聲明prereleaseChannel當(dāng)版本預(yù)發(fā)布標(biāo)識(shí)與通道不一致如版本是 alpha 但配置為 beta、配置聲明了通道但版本是穩(wěn)定版且無(wú) change file、或版本是預(yù)發(fā)布但未配置通道且無(wú) change file 時(shí)均會(huì)報(bào)錯(cuò)要求通過(guò)添加 change file 完成通道遷移或轉(zhuǎn)正graduation從穩(wěn)定版進(jìn)入預(yù)發(fā)布模式必須包含一個(gè)major.前綴的 change filescripts/utils/changes.ts預(yù)發(fā)布模式下渲染的 changelog 把所有條目歸入單一的Pre-release Changes分組而不是按 Major/Minor/Patch 分節(jié)scripts/utils/changes.ts 與 scripts/utils/changes.ts。這套機(jī)制與 decisions/002-branching-and-releasing.md 描述的發(fā)布策略相呼應(yīng)main分支持續(xù)可發(fā)布子包破壞性變更在future分支積累并提前發(fā)布 major最終合并回main再切remix主版本change file 體系正是這條發(fā)布流水線的入口。變更說(shuō)明的效果CHANGELOG 渲染規(guī)則scripts/utils/changes.ts 定義了 changelog 的渲染規(guī)則同包多條說(shuō)明按 bump 類型分組為### Major Changes、### Minor Changes、### Patch Changes三節(jié)空節(jié)跳過(guò)節(jié)內(nèi)排序把破壞性變更置頂其余按文件名slug字母序排列每條說(shuō)明自動(dòng)加 bullet單行直接變- 內(nèi)容多行時(shí)首行加 bullet、后續(xù)行縮進(jìn)兩格依賴升級(jí)產(chǎn)生的條目統(tǒng)一渲染為- Bumped \remix-run/* dependencies: 加帶 tag 鏈接的列表若包已有 patch 變更則并入現(xiàn)有 Patch Changes 節(jié)否則單獨(dú)生成一節(jié)。倉(cāng)庫(kù)內(nèi)包的 CHANGELOG.md如 packages/remix/CHANGELOG.md正是這些渲染規(guī)則的產(chǎn)物其中預(yù)發(fā)布版本條目使用### Pre-release Changes分組與生成邏輯完全一致可作為編寫 change file 時(shí)的參照樣例。結(jié)束前自檢清單規(guī)范Before Finishing一節(jié)給出了收尾自查項(xiàng)也是每次提交前的最終把關(guān)是否先檢查了既有的未發(fā)布.changes文件避免重復(fù)說(shuō)明是否描述用戶可見(jiàn)的變更而不是實(shí)現(xiàn)細(xì)節(jié)是否運(yùn)行過(guò)pnpm changes:preview且渲染出的 changelog 條目符合預(yù)期小結(jié)make-changes把寫發(fā)布說(shuō)明這件看似自由發(fā)揮的事固化為一套命名可解析、內(nèi)容可校驗(yàn)、渲染可預(yù)覽、落地可自動(dòng)化的工程流程文件名前綴決定 bump 分類BREAKING CHANGE:前綴與版本段強(qiáng)制綁定內(nèi)容格式由腳本兜底校驗(yàn)remix傘包與子包各司其職預(yù)發(fā)布通道由config.json驅(qū)動(dòng)。對(duì)倉(cāng)庫(kù)維護(hù)者與 Agent 而言只要遵循本文梳理的命名、內(nèi)容與命令三部曲就能為任意remix-run/*包或remix本身穩(wěn)定地產(chǎn)出高質(zhì)量、可發(fā)布的變更記錄。【免費(fèi)下載鏈接】remixThe fully-stacked web framework項(xiàng)目地址: https://gitcode.com/GitHub_Trending/re/remix創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考