用途:为 Remix 仓库撰写符合 .changes 约定的简洁发布说明,适用于新建变更文件或编辑既有未发布条目,也可在用户索要发布说明、变更记录、缺失的 changelog 条目或预发布说明时使用。
主要能力:先读取包的 package.json、已有 .changes/ 目录及相关 PR diff 或提交范围;参考 origin/main 上近期已发布的 changelog 条目把握语气与详略;检查是否已存在同一工作的未发布变更文件,若有则原地更新而非重复创建;按影响选择提升类型(0.x 包新功能与破坏性变更用 minor、修复用 patch,明确禁止对 0.x 使用 major,1.x+ 用标准 semver);可在需要时创建 packages/<package>/.changes/ 目录。
使用方式:文件命名与放置遵循 packages/<package>/.changes/[major|minor|patch].short-description.md,slug 保持简短、具体、稳定;全新包发布优先用 minor.initial-release.md;Remix 导出变更更新 packages/remix/.changes/minor.remix.update-exports.md;remix 镜像再导出包的变更命名为 [major|minor|patch].<package>.short-description.md(<package> 省略 @remix-run/ 前缀)。撰写后运行 pnpm changes:preview 并审查受影响的完整 changelog 段落;如改动涉及代码、包元数据、文档或发布工具,再运行 lint 或更广泛校验。
内容规范:每条变更文件按最终 changelog 文案对待,聚焦用户可见行为、公共 API、导出、迁移或升级工作,不写内部重构;每条自包含,先讲用户可见结果或必需迁移,再引入 API 名称;破坏性变更按“发生了什么、实际影响、如何迁移”顺序写;要求读者改代码时给出带上下文的 diff;修复需描述用户可见症状;弃用需提及替代 API。多处相关跨包变更应合并为少量成组条目。
限制:不要手改 packages/remix/src/* 生成文件;除非明确要求,不编辑历史 CHANGELOG.md;不手工硬换行;不为仅通过依赖更新观察到变更的包递归添加手动变更文件;资料未提供该技能的具体安装方式、收费或平台支持信息。