EmDash Changeset 编写与评审指南：从补丁记录到面向读者的发布文档

EmDash Changeset 编写与评审指南从补丁记录到面向读者的发布文档【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址: https://gitcode.com/gh_mirrors/emdas/emdashEmDash 是一个基于 Astro 的全栈 TypeScript CMS采用 Changesets 工具链管理多包仓库的版本发布与 CHANGELOG 生成。本指南基于仓库根目录下.changeset/README.md的完整规范结合仓库内config.json配置与真实 changeset 案例系统讲解何时添加 changeset、如何撰写面向读者的变更描述、如何选择 bump 类型以及如何像评审文档一样评审 changeset。读完本文你将掌握为 EmDash 及其子包如emdash、emdash-cms/admin、emdash-cms/cloudflare提交高质量变更记录的全部实操方法。Changeset 是什么为什么它如此重要在 Changesets 工作流中一个 changeset 决定了两件事版本号如何提升它声明被影响的包和 bump 类型patch/minor/major发布时据此计算新版本号CHANGELOG 的正文来源它的描述会作为该包 CHANGELOG 中的公开文档条目被读者在决定“要不要升级、怎么升级”时反复阅读。因此.changeset/README.md开篇给出的核心写作准则非常关键Write and review it for someone who runs the package, not someone who has read the pull request or diff.即为“运行这个包的人”而写而不是为“看过 PR 或 diff 的人”而写。读者没有你的 PR 上下文他们只能从这段描述判断这次发布是否与自己相关、升级后需要做什么。仓库的每个变更记录都以 Markdown 文件形式存放在 .changeset/ 目录下文件名通常是无意义的随机短语如fuzzy-lions-check.md、quiet-workers-start.md真正的信息都在文件 frontmatter 与描述正文里。例如--- emdash: minor --- Adds GET /_emdash/api/health so external tools can confirm an EmDash site is reachable and whether its plugin registry is enabled.frontmatter 声明了受影响的包与 bump 类型正文则描述用户可感知的新能力。何时需要添加 Changeset必须添加的场景任何对已发布包行为或 API 的改动都需要 changeset包括 bug 修复、新特性以及改变行为的重构。文档中特别强调没有 changeset 的改动不会触发发布Without one, the change will not trigger a release。多包场景的规则如下场景规则改动涉及多个包只需一个 changeset在 frontmatter 中列出所有受影响包一个 PR 包含多个独立改动可以每个改动一个 changeset各自成为独立的 CHANGELOG 条目多个 PR 共同构建同一特性如互相依赖的 PR 栈只写一个描述完整用户可见能力的 changeset放在栈中某一个 PR 里而不是记录实现顺序独立可发布的 PR除非发布协调能保证所有 PR 同时发布否则每个 PR 需要各自的 changeset不需要添加的场景仅涉及文档、测试、CI/工具链、demo 和模板的改动不需要 changeset。原因是这些改动不改变已发布包对外的行为。这一规则在 .changeset/config.json 中有直接体现——ignore数组明确列出了从发布流程中排除的包包括各类 demoemdash-cms/demo-cloudflare、emdash-cms/playground、模板emdash-cms/template-blog、emdash-cms/template-marketing等、测试用插件emdash-cms/plugin-api-test以及docs包。这些包不参与版本发布自然也不需要 changeset。创建 Changeset 的命令在仓库根目录执行pnpm changeset随后编辑生成的 Markdown 文件在 frontmatter 中由 PR 作者选择受影响的包和 bump 类型。从.changeset/config.json可以看到该仓库的 Changesets 配置细节changelog使用changesets/changelog-github插件仓库为emdash-cms/emdash生成的 CHANGELOG 会关联 GitHub PR/issuefixed数组将emdash、emdash-cms/admin、emdash-cms/auth、emdash-cms/blocks、emdash-cms/cloudflare、emdash-cms/gutenberg-to-portable-text、emdash-cms/x402、create-emdash绑定为同一版本组——这意味着这些包在发布时会一起提升版本因此涉及它们的变更通常要写进同一个 changesetcommit: false表示不会自动把 changeset 提交到版本控制baseBranch为main。选择 Bump 类型patch、minor 与 major在 changeset frontmatter 中需要选择版本提升类型规则如下patch用于 bug 修复和小改进minor用于新的向后兼容特性majorEmDash 在 1.0 之前不接受majorbumpEmDash does not currently acceptmajorbumps while it is pre-1.0。破坏性变更或重大默认值变更需要事先获得维护者批准并且要使用与维护者商定的包与 bump 策略。这一点在规范中反复出现不要自行决定破坏性变更的发布方案。仓库中的真实案例印证了这套规则。例如 .changeset/quiet-workers-start.md 是一个典型的patch它修复了 Cloudflare Worker 的启动性能问题懒加载依赖、降低启动 CPU不改变外部行为因此使用patch并同时列出emdash-cms/cloudflare与emdash两个受影响包。而 .changeset/editor-link-search.md 是新增的向后兼容能力富文本编辑器链接输入框按标题搜索已有内容因此声明为minor。以发布行为开头第一句话就要说清“发生了什么”规范要求 changeset 描述以现在时动词开头如Fixes、Adds、Updates、Removes、Deprecates。开篇句子需要做到当读者能识别时点名用户可见的 API、选项、命令、组件或行为说明谁受影响、他们现在能做什么或描述被修复的可观察问题描述发布后的行为而不是文件名、私有函数、重构细节、查询或实现选择。细节的多少要与影响成正比一个patch通常一句具体的话就足够一个重要的minor特性通常需要包含能力说明、基本用法、默认值与兼容性、受影响环境以及读者需要采取的任何行动最重要的能力要放在最前面不要埋没在附带修复或实现细节之下。破坏性变更与默认值变更必须“不容误解”规范强调Breaking changes and default changes must be unmistakable。必须说明谁受影响之前的行为和当前的行为迁移所需采取的行动在可能的情况下如何恢复之前的行为。优先提供最小配置示例或 before-and-after 示例而不是笼统的警告。在维护者批准包的发布策略之前不要提交破坏性变更。三个完整的撰写示例解析规范给出了三个可以直接套用的完整示例下面逐一解析其结构。示例一patch 条目——点名命令与可观察问题--- emdash: patch --- Fixes emdash migrate --json so progress messages go to stderr, allowing scripts to parse stdout as JSON.要点点名了受影响的命令emdash migrate --json并描述了脚本作者能观察到的具体问题进度消息污染了 stdout导致无法把 stdout 当作纯 JSON 解析。这正是“为运行包的人而写”的典范——脚本作者读完立刻知道这个修复对自己意味着什么。示例二minor 特性——能力、用法与退出码契约--- emdash: minor --- Adds --check to emdash migrate so deployment pipelines can detect pending or unknown migration records without changing the database. Run the check after deploying the application artifact that produced the migration manifest: sh pnpm exec emdash migrate --check The command exits with 0 when the database matches the build, 2 when known migrations are pending, and 3 when the database contains migration records unknown to the build. It works with every database adapter supported by the migration manifest.要点先说明新能力与它的价值让部署流水线在不修改数据库的情况下检测迁移状态再给出最小可用命令然后完整定义退出码契约0一致、2有已知迁移待执行、3存在构建未知的迁移记录最后说明适用范围迁移清单支持的所有数据库适配器。这类“退出码契约”信息对部署流水线的维护者是关键决策依据。示例三经批准的默认值变更——影响与回退路径显式化--- emdash: minor --- Updates memoryCache() to use a five-minute default TTL instead of one hour, so sites using the in-memory object cache refresh cached pages more frequently after an upgrade. Sites that depend on the previous one-hour lifetime can keep it explicitly: ts objectCache: memoryCache({ defaultTtl: 3600 }); #### What should I do? Set defaultTtl: 3600 before upgrading if the shorter cache lifetime would add unacceptable load to your site.要点默认值变更被提升为minor已获批准。描述包含前后行为对比五分钟 vs 一小时、受影响用户使用内存对象缓存的站点、迁移动作显式设置defaultTtl: 3600、以及恢复旧行为的方法。文档中还示范了较长条目使用 Markdown 标题的规范——从 h4####开始因为 changeset 会被嵌入到生成的 CHANGELOG 标题之下使用 h2/h3 会破坏文档层级结构。破坏性变更的同等要求规范明确指出破坏性变更需要同样级别的细节第一句话点名被移除或改变的 surface然后给出最小可行的迁移方案。在维护者批准其包与发布策略之前不得提交破坏性变更。好与坏的描述对比把“技术相关”变成“发布文档”规范给出了三组 diff 对比直观展示两类描述的区别- Fixes a bug in media handling. Fixes R2 media uploads larger than 10 MB failing before the upload begins.- Refactors hydrateEntryBylines to chunk SQL IN clauses. Fixes D1 errors when loading an entry with more bylines than the database bind-parameter limit.- Updates migration status handling and exit codes. Adds emdash migrate --check so deployment pipelines can detect pending or unknown migrations without changing the database.左侧是“技术相关的散文”描述了内部机制重构、chunk SQL IN 子句、处理迁移状态右侧是“有用的发布文档”描述用户能观察到的行为变化R2 上传大于 10 MB 失败、D1 绑定参数超限错误、新增的检查命令。这正是评审 changeset 时要做的核心判断。仓库中的真实条目同样遵循这一风格。例如 .changeset/forms-webhook-deferred.md 描述表单 webhook 静默失效的根因与修复fetch只在传输层错误时 reject因此 4xx、5xx 以及认证端点重定向后的登录页都被当作“成功”处理、不留痕迹修复后通过after()注册到 host 保证执行完成并通过比较最终 URL而非Response.redirected因为插件 HTTP 访问自行跟随重定向、总是报告redirected: false识别重定向场景。而 .changeset/calm-datetimes-normalize.md 则示范了修复类条目如何同时说明迁移行为所有内容 datetime 以固定毫秒的 UTC ISO 字符串存储管理端按站点时区转换API/MCP/CLI 写入要求Z或显式 UTC 偏移迁移在修改前报告非规范值遇到夏令时重复/跳过的时段会停止写入并报告需要显式偏移的行。不要只把解释写在 changeset 里规范有一条容易被忽略但很重要的要求Do not keep useful explanations or examples only in a changeset or PR description. Add them to the canonical feature or upgrade documentation too; the CHANGELOG is usually read once, while the docs remain the reference.即不要把有用的解释或示例只留在 changeset 或 PR 描述里。CHANGELOG 通常只被读一次而官方文档是长期参考。因此重要的特性或升级说明必须同步写入正式的功能文档或升级文档。像评审文档一样评审 Changeset评审 changeset 时frontmatter 的有效性和技术准确性是必要但不充分的条件Frontmatter validity and technical accuracy are necessary but not sufficient。遇到以下情况应要求重写描述含糊不清只描述内部机制读起来像 commit message把重要能力埋在附带细节之下无助于读者判断“这次发布对我是否重要”。正确的做法是把描述当作文档来评审与 bump 类型和包列表一并审查。实践建议把规范落到 EmDash 日常贡献中结合上述规范与仓库实际情况提交 EmDash 变更时建议按以下流程操作在仓库根目录运行pnpm changeset生成新的变更文件在 frontmatter 中列出所有受影响包若涉及fixed版本组中的包注意它们会一起发布bug 修复用patch向后兼容新特性用minor1.0 之前不使用major破坏性变更先与维护者确认策略正文以Fixes / Adds / Updates / Removes / Deprecates开头点名用户可见的命令、API 或行为描述发布后的行为而非实现细节需要时补充最小可用示例与默认值/退出码等契约信息默认值变更与破坏性变更必须写明前后行为、迁移动作与恢复方法超过一段的条目用####及以上标题组织避免破坏生成的 CHANGELOG 层级把重要的用法说明同步补充到正式文档而不是只留在 changeset 中。对于不发布版本的包见 .changeset/config.json 的ignore列表以及纯文档、测试、CI/工具链、demo 和模板改动则无需创建 changeset。遵循这套规范EmDash 的每个 CHANGELOG 条目都会成为一份独立可读、信息完整、面向升级决策者的发布文档——这正是.changeset/README.md以及整个 Changesets 工作流想要达成的目标。关于 Changesets CLI 与配置的更多行为细节可参阅 Changesets 官方文档仓库内.changeset/config.json即其配置的落地实例。【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址: https://gitcode.com/gh_mirrors/emdas/emdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考