编写 Remix 仓库 Change Files.changes 发布说明约定与完整工作流【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix导读本文围绕 Remix 仓库的make-changes技能规范.agents/skills/make-changes/SKILL.md完整讲解在packages/*/.changes目录下编写与维护发布说明release notes的命名约定、bump 规则、内容规范与校验流程。读完本文你将掌握如何为新增功能、破坏性变更、弃用和缺陷修复正确编写 change file如何在 0.x 与 1.x 版本策略下选择 bump 类型以及如何用pnpm changes:preview、pnpm changes:validate、pnpm changes:version三条命令驱动变更校验、CHANGELOG 生成与版本提交。make-changes 技能定位make-changes是仓库内面向 Agent 与开发者的技能skill其 frontmatter 明确声明了适用场景当用户请求发布说明、变更记录、缺失的 changelog 条目、预发布prerelease说明或需要更新现有未发布变更记录时都应调用该技能。技能的完整定义位于 .agents/skills/make-changes/SKILL.md与之配套的 Agent 配置见 .agents/skills/make-changes/agents/openai.yaml。该技能的核心目标是用统一约定管理每个包未发布的变更使remix及其全部remix-run/*子包的 CHANGELOG 可以由脚本自动、确定性地生成。从仓库根目录的 package.json 可以看到三条配套脚本pnpm changes:preview→ 运行 scripts/changes-preview.ts预览渲染后的 changelog 输出与发布列表pnpm changes:validate→ 运行 scripts/changes-validate.ts校验全部 change file 与 CHANGELOG 完整性pnpm changes:version→ 运行 scripts/changes-version.ts真正更新版本号、生成 CHANGELOG 并创建发布提交。完整工作流按技能规范编写一份 change file 的标准流程如下读取目标包的package.json、已存在的.changes/目录以及相关的 PR diff 或 commit 范围确定变更的上下文与影响面。检查是否已存在针对同一工作的未发布 change file若存在直接就地更新而不是新建重复条目避免同一变更在 CHANGELOG 中出现两次。根据包的当前版本与对用户的影响面选择 bump 类型major / minor / patch。若packages/package/.changes/目录尚不存在按需创建。编写面向用户的发布说明描述已交付的行为、API、导出、迁移或升级工作。运行pnpm changes:preview验证渲染后的 changelog 输出是否符合预期。若本次任务同时改动了代码、包元数据、文档或发布工具再运行 lint 或更广泛的校验例如pnpm changes:validate。其中第 2 步是防止重复的关键change file 是未发布变更的暂存区同一逻辑变更不应同时存在两份说明脚本在发布时会把变更折叠进 CHANGELOG 并删除暂存文件见 scripts/changes-version.ts 的deleteChangeFiles逻辑。Bump 规则0.x 与 1.x 的版本语义0.x 包的约定新功能与破坏性变更一律使用minor缺陷修复使用patch除非被明确指示否则不得对 0.x 包使用major0.x 下破坏性变更说明必须以BREAKING CHANGE:开头。这一约定并非只是口头规范校验脚本中实现了对应强制逻辑。scripts/utils/changes.ts 会检查对 1.x 包若内容检测到BREAKING CHANGE:前缀而 bump 不是major则报错并提示重命名为major.slug.md对 0.x 包且当前版本非预发布若含破坏性前缀而 bump 不是minor同样报错并提示重命名为minor.slug.md。前缀检测由hasBreakingChangePrefix实现scripts/utils/changes.ts忽略首部空白与*/_加粗标记后以小写方式匹配breaking change:开头。1.x 包按标准 semver 处理破坏性变更走major新功能走minor缺陷修复走patch。其他版本规则破坏性变更的判定基准是相对main分支而非同一 PR 内的早期 commit在remix的预发布模式下bump 类型主要决定 changelog 的分类Major/Minor/Patch Changes 分组实际版本号由预发布计数器推进而不是由 bump 类型决定。这一点在 scripts/utils/changes.ts 的getNextVersion中实现当包配置了prereleaseChannel且当前版本已处于同一通道时仅调用 semver 的prerelease递增计数器不再应用 bump 类型。文件放置与命名命名模板通用命名packages/package/.changes/[major|minor|patch].short-description.mdslug描述段要求简短、具体、稳定当仓库对该类说明已有确定性的命名模式时复用既有名称保证同类条目命名可预期全新包的首次发布优先使用minor.initial-release.mdremix包导出变更更新packages/remix/.changes/minor.remix.update-exports.md这一固定文件而不是发明一次性文件名对应规范Remix-Specific Rules一节当packages/remix/.changes镜像某个被再导出包的 change file 时命名格式为packages/remix/.changes/[major|minor|patch].package.short-description.md其中package去掉remix-run/作用域前缀。文件名解析与强制校验脚本对文件名的解析逻辑位于 scripts/utils/changes.ts文件必须以.md结尾且文件名开头必须是major.、minor.或patch.前缀加非空描述否则直接报错预发布模式下例外bump 类型不影响版本号因此允许任意文件名此时统一按patch归类。.changes目录下仅README.md与config.json被跳过不参与解析。目录与依赖关系.changes目录按包组织位于每个包的packages/package/.changes/下。发布工具链在 scripts/utils/changes.ts 中还会计算直接变更包的传递依赖凡是依赖了被变更包的包也会被纳入本次发布dependency-triggered release并自动为其生成依赖升级dependency bump的 changelog 条目。说明内容编写规范写什么记录用户可见的行为、公开 API 变更、导出、迁移或升级工作内部重构如果没有体现为真实的 API 或行为变化不要写发布说明每条说明必须自包含读者仅凭该条说明即可理解交付的行为链接用于补充上下文而不是替代解释当变更关联公开 issue、PR、RFC、decision doc、spec 或外部缺陷报告时在说明中附上简短引用。优先引用真正解决了该 issue/功能的 PRissue 可以从 PR 反查到同仓库引用使用行内形式如(see #1234)外部仓库、spec 或报告使用完整 URL明确指出受影响的 API、路由约定、包、入口、运行时、浏览器或工具版本帮助用户判断该说明是否适用于自己。不同类型变更的写法缺陷修复描述用户可见的症状或失败场景而不是只描述实现层的修复破坏性变更同时给出旧行为、新行为与迁移路径弃用如果存在替代 API必须提及。格式约束不要手动对.changes/*.md中的散文做硬换行每个段落或列表项保持单行源码由渲染后的 changelog 自然换行扁平列表仅在有助于清晰表达时使用短段落通常更合适除非被明确要求不要编辑历史CHANGELOG.md条目仅允许诸如修复坏链、错别字或明显无效引用这类窄范围修正。脚本侧的格式校验scripts/utils/changes.ts 对内容实施硬性校验change file 不能为空第一行不能以-或*开头的列表项开始——CHANGELOG 渲染时会自动为每条说明加 bulletformatChangelogEntry会把首行转为- xxx手写 bullet 会导致重复标题级别只能是 4、5、6 级####/#####/######禁止 1-3 级或 7 级以上标题因为 change file 最终嵌套在已占用 1-3 级标题的 changelog 内部。包归属谁该写 change file规范的Package Ownership一节给出清晰的职责划分手动 change file 应加到拥有被变更 API、行为或实现的那个包若另一包通过再导出re-export暴露了新增、删除、重命名或变更的公开 API且用户可通过该再导出入口消费这些 API则再导出包也要写 change file不要为仅通过依赖升级间接观察到变更的包手动添加 change file——发布脚本已包含传递依赖方并会为其生成依赖升级条目底层包的缺陷修复通常只给拥有该修复的包写 change file仅当再导出包自身的 changelog 需要直接点名该行为而不仅仅因为修复的依赖可达时才额外写再导出包条目。Remix 特有的约束packages/remix/src/*的再导出文件是生成产物除非任务明确要求生成输出否则不要手工编辑当packages/remix/package.json新增或改变公开导出时记录到固定的minor.remix.update-exports.md不要发明一次性文件名如果变更通过remix/...暴露了其他包的新 API说明要描述被暴露的remix/...入口而不仅是底层 workspace 包名。粒度层级包级说明与 remix 汇总说明规范的Detail Levels一节区分了两级说明的写作深度包级 change file 是事实来源source of truth。子包说明需包含用户理解变更所需的具体 API、行为、运行时或工具细节当新 API、迁移、破坏性变更或用法模式改变能借助 before/after 示例讲清楚时务必包含同时附上有用的 PR、issue、RFC、decision、spec 或外部报告链接优先引用能提供完整脉络的实现 PR。packages/remix/.changes的条目则要像面向remix用户的伞式发布摘要比底层包说明更简短聚焦于暴露出来的remix/...入口或发布级影响。不要把一个子包说明中的详细示例、迁移散文或实现背景复制进remix说明除非伞式包自身行为发生了变化当remix说明汇总子包变更时链接到底层 changelog、release、PR 或其他可持久追踪的细节来源方便读者下钻发布工具已自动为发布的包 tag 添加依赖升级链接因此不要在remixchange file 中手工重建依赖升级列表。命令行验证preview、validate、versionpnpm changes:preview预览scripts/changes-preview.ts 首先调用parseAllChangeFiles做全量解析与校验失败则以红色错误信息退出exit 1成功且存在变更时依次打印有变更的包列表格式为包名: 当前版本 → 下一版本 (bump 类型)每个包对应的 CHANGELOG 渲染预览生成的提交信息后续应执行的pnpm changes:version提示。若所有包都无待发布变更则打印No packages have changes to release.并正常退出。pnpm changes:validate校验scripts/changes-validate.ts 做两件事遍历全部包目录检查是否存在CHANGELOG.md缺失则报错调用parseAllChangeFiles校验所有 change file 的命名、内容格式、bump 规则与预发布配置一致性。任一环节出错都会以 exit code 1 退出适合接入 CI 前置检查。pnpm changes:version落地版本scripts/changes-version.ts 在通过全量校验后按发布列表逐个包执行更新package.json的version字段在CHANGELOG.md中插入新版本条目插入到第一个##版本条目之前无版本条目时追加到末尾删除.changes/下所有待发布 md change file空目录一并移除默认执行git add .并创建提交信息形如Release- 包名: 当前版本 - 下一版本的提交传--no-commit参数时只更新文件不提交并打印供人工审阅与手动git commit的指引。预发布prerelease模式细节预发布相关的配置与校验逻辑集中在 scripts/utils/changes.ts 与 scripts/utils/changes.ts每个包可在.changes/config.json中声明prereleaseChannel非空字符串与可选的prereleaseStart非负整数且要求必须同时声明prereleaseChannel当版本预发布标识与通道不一致如版本是 alpha 但配置为 beta、配置声明了通道但版本是稳定版且无 change file、或版本是预发布但未配置通道且无 change file 时均会报错要求通过添加 change file 完成通道迁移或转正graduation从稳定版进入预发布模式必须包含一个major.前缀的 change filescripts/utils/changes.ts预发布模式下渲染的 changelog 把所有条目归入单一的Pre-release Changes分组而不是按 Major/Minor/Patch 分节scripts/utils/changes.ts 与 scripts/utils/changes.ts。这套机制与 decisions/002-branching-and-releasing.md 描述的发布策略相呼应main分支持续可发布子包破坏性变更在future分支积累并提前发布 major最终合并回main再切remix主版本change file 体系正是这条发布流水线的入口。变更说明的效果CHANGELOG 渲染规则scripts/utils/changes.ts 定义了 changelog 的渲染规则同包多条说明按 bump 类型分组为### Major Changes、### Minor Changes、### Patch Changes三节空节跳过节内排序把破坏性变更置顶其余按文件名slug字母序排列每条说明自动加 bullet单行直接变- 内容多行时首行加 bullet、后续行缩进两格依赖升级产生的条目统一渲染为- Bumped \remix-run/* dependencies: 加带 tag 链接的列表若包已有 patch 变更则并入现有 Patch Changes 节否则单独生成一节。仓库内包的 CHANGELOG.md如 packages/remix/CHANGELOG.md正是这些渲染规则的产物其中预发布版本条目使用### Pre-release Changes分组与生成逻辑完全一致可作为编写 change file 时的参照样例。结束前自检清单规范Before Finishing一节给出了收尾自查项也是每次提交前的最终把关是否先检查了既有的未发布.changes文件避免重复说明是否描述用户可见的变更而不是实现细节是否运行过pnpm changes:preview且渲染出的 changelog 条目符合预期小结make-changes把写发布说明这件看似自由发挥的事固化为一套命名可解析、内容可校验、渲染可预览、落地可自动化的工程流程文件名前缀决定 bump 分类BREAKING CHANGE:前缀与版本段强制绑定内容格式由脚本兜底校验remix伞包与子包各司其职预发布通道由config.json驱动。对仓库维护者与 Agent 而言只要遵循本文梳理的命名、内容与命令三部曲就能为任意remix-run/*包或remix本身稳定地产出高质量、可发布的变更记录。【免费下载链接】remixThe fully-stacked web framework项目地址: https://gitcode.com/GitHub_Trending/re/remix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考