Astro 仓库 main→next 合并中的 stale changeset 清理预发布版本一致性维护实战指南【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astroAstro 官方 Monorepo 采用main稳定分支与next预发布分支并行的发布策略其中所有包的版本号与变更记录都由 Changesets 为主体结合.changeset/目录下的真实配置与变更文件、merge技能的整体流水线定义给出这套“识别 → 判定 → 移除 → 校验”的 stale changeset 清理完整流程帮助理解并安全执行 main→next 的版本合并维护工作。这套流程解决什么问题预发布分支的“陈旧 changeset”问题要理解为何需要专门的清理步骤首先要还原 Astro Monorepo 的版本演进模型main是稳定发布分支release 会“消费”掉一批.changeset/*.md文件将其合并为各包的 CHANGELOG 与版本号提升next是预发布分支处于 Changesets 的 pre-release 模式同一分支上的发布生成的是beta/rc这类预发布版本号。问题发生在两者合并时如果next在某个 release 之前就已经从main分叉那么当main被合并进next时那些“已经被main上的 release 消费掉”的 changeset 文件在 git 看来仍然是以新增文件Added形式出现的新内容。若不清理next下一次发布 pre-release 版本时会把这些早已作为稳定版发布过的改动再次计入版本号提升于是出现同一改动先以beta后以更低序的稳定版发布的版本倒挂。这正是文档中给出的冲突实例astrojs/sitemap3.6.1-beta.3被发布在astrojs/sitemap3.7.0之后。预发布版本号反而大于其对应稳定版的下一个 patch 语义破坏了 semver 的预期排序。开始前的前置条件与执行边界文档明确列出两条执行前置条件任何运行此流程的人或 Agent 都应先核对工作目录必须是仓库根目录且已 checkout 在 merge 分支上。因为后续所有git diff、git rm命令都假定你在正确的分支与工作区执行。依赖可能尚未安装——禁止运行任何依赖node_modules的pnpm命令。清理 changeset 本质上是纯 git 文件操作不应触发安装、构建或发布动作。此外文档明确限定执行范围不要派生子任务/子 AgentDo not spawn tasks/sub-agents整个清理过程应当是单个执行者顺序完成的线性流程。理解 .changeset 目录被清理对象与不可动文件在 Astro 仓库根目录[.changeset/](https://link.gitcode.com/i/61df7e245fe9ef5655c242678c64c051)目录集中存放所有 changeset 文件与 Changesets 工具的运行时配置。当前仓库中可以看到.changeset/config.json—— Changesets 的全局配置若干形如better-lines-show.md、great-moons-shine.md、tidy-pumas-attack.md的随机名词命名 changeset 文件由pnpm changeset自动生成文件名.changeset/README.md—— 工具自动生成的说明文件。关于这些文件应建立三条关键认知1.changeset/config.json是发布行为的基准配置绝不能删除。当前仓库的配置内容如下{ $schema: https://unpkg.com/changesets/config2.3.1/schema.json, changelog: [changesets/changelog-github, { repo: withastro/astro }], commit: false, linked: [], access: public, baseBranch: origin/main, updateInternalDependencies: patch, ___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH: { onlyUpdatePeerDependentsWhenOutOfRange: true } }其中baseBranch: origin/main定义了主基准分支changelog使用 GitHub 上withastro/astro的仓库生成 changelog。这套配置意味着稳定分支即发布基准也是判定“某个 bump 是否已被发布”的对照来源。2changeset 文件有严格的 frontmatter 格式。每个 changeset 都是一个 Markdown 文件frontmatter 中声明受影响的包名与 semver bump 类型patch/minor/major正文是面向用户而非代码评审者的 CHANGELOG 描述。仓库中现有的真实示例great-moons-shine.md--- astro: patch --- Updates Astros remaining internal warnings and errors to be written through the configured logger instead of directly to the console, when possibletidy-pumas-attack.md--- astrojs/vercel: patch --- Updates the development image service to forward every argument it receives to Astros Sharp service, including the new logger parameter注意包名必须与对应包的package.jsonname字段完全一致如astro、astrojs/vercel、astrojs/sitemap这正是清理时判定“该 changeset bump 的是哪个包”的解析依据。仓库的merge技能姊妹篇 changeset/SKILL.md 进一步规定每个修改包的 PR 都必须附带 changeset仅examples/*改动豁免核心astro包的major/minorbump 会被 CI 拦截、需要维护者评审——这意味着出现在next上的“新功能/破坏性变更”型 changeset 往往与主分支无关应被保守保留。3.changeset/pre.json只会在 pre-release 模式下存在。它记录预发布状态当前处于 pre 模式的版本前缀、以及 pre 模式下已登记但尚未发布的 changeset 列表。只有当仓库当前处于 pre-release 模式时才存在若存在它很可能在changesets数组中引用若干 changeset 文件名清理时需要同步确认不应再引用被移除的条目。清理时不能删除整个pre.json——它一旦缺失会破坏 pre-release 状态机。完整清理流程六个步骤详解步骤 1用 diff 识别出“相对 next 是新增”的 changeset合并分支准备好后第一步是找出所有相对origin/next属于新增Added的 changeset 文件# 列出 changeset 下、在 next 中尚不存在的 .md 文件 git diff --name-only --diff-filterA origin/next -- .changeset/--diff-filterA把输出限定为“新增文件”正是main合入后会把已发布 changeset 重新带进来的通道路径过滤-- .changeset/把比较范围严格限定在 changeset 目录避免无关文件干扰。步骤 2逐个核对每个新 changeset 是否“已被 main 发布”对步骤 1 输出的每个文件做两层检查读文件内容从 frontmatter 中解析出它 bump 了哪些包、是什么 bump 类型patch/minor/major对照origin/main上这些包当前的package.json版本判断“文件里描述的那次 bump 是否已经被发布过了”。判断依据是版本发布史如果在origin/main上该包的版本号已经推进到包含这次 bump 的程度例如该 bump 的内容已经写进了对应包的 CHANGELOG、版本已经越过它那么这个 changeset 就是 stale已消费但残留应当被清理。以文档中的冲突为例当origin/main上的astrojs/sitemap已是3.7.0、而其 changeset 描述的内容已在 3.7.0 中发布时出现在next上的对应 changeset 就会把next的3.6.1-beta.x序列错误地推到3.6.1-beta.3与已发布的3.7.0产生版本倒挂——这正是必须删除的典型对象。步骤 3同步检查.changeset/pre.json如果.changeset/pre.json存在务必读取它确认它记录的 pre-release 状态与changesets数组不会引用任何将要被移除的 changeset。被移除的 changeset 若仍被pre.json引用后续changesets version阶段会因找不到对应文件而报错或产生悬空引用。所以“删文件”与“改 pre.json 登记表”必须配套处理。步骤 4删除被判定为 stale 的 changeset 文件使用 git 跟踪的删除方式确保删除动作被暂存、能被 merge 提交携带git rm .changeset/stale-file.md用git rm而非普通文件删除是为了让删除操作进入索引方便后续由编排者统一提交。步骤 5校验剩余 changeset 的合法性清理完成后检查剩下的 changeset 文件是否都格式完好frontmatter 中的包名合法、bump 类型属于patch/minor/major三者之一、正文存在。格式良好的 changeset 是后续 CI 校验和 changelog 生成的前提。步骤 6不要提交、不要安装依赖最后一步是明确的工作交接边界不要执行git commit也不要运行pnpm install。提交、安装、构建与发布由编排者orchestrator统一处理——这也与前置条件中“依赖可能尚未安装”呼应清理阶段应保持工作区只包含 changeset 的调整。决策规则什么时候该删什么时候该留stale changeset 清理最需要审慎的是判定边界。文档给出了清晰的红线只删“已被发布”的 changeset唯一可靠的删除依据是“它在main上的那次 bump 已经发布过”。任何缺少这一证据的 changeset 都不能凭猜测删除。绝不删除next专属 changeset那些描述next上正在开发的 major 变更或新特性的 changeset正是预发布版本存在的意义必须原样保留。绝不删除.changeset/config.json它是 Changesets 的全局配置基准含baseBranch: origin/main等删除会导致整个发布配置失效。绝不删除.changeset/pre.json它维护 pre-release 模式状态删除会破坏next的预发布版本推进机制。不确定时保守保留若无法判断一个 changeset 是否 stale宁可保留留给人工评审者后续裁决。过度删除比少量残留风险更高——残留至多造成一次多余的版本号提升而误删则可能丢失真实的变更记录与 CHANGELOG 内容。这一“宁可保守”的原则在仓库的 merge 技能评测用例 中被固化为验收标准合成场景中仅有明确发布证据的 sitemap changeset 被移除并同步从pre.json的changesets数组中剔除而next专属的 major 变更与“发布状态未被证明”的 node changeset 都被保留。执行输出与校验闭环流程结束时需要返回被移除的 changeset 文件清单作为执行结果。这份清单既是 merge 分支改动的摘要也是后续人工复核与pre.json同步的核对依据。整个清理是仓库merge技能流水线的一个环节。父技能 merge/SKILL.md 把 main→next 合并拆成三个阶段依次执行resolve-conflicts.md解决 git 冲突→ 本文的 clean-changesets.md移除 stale changeset→ fix-ci.md修复 CI 暴露的构建、类型与测试问题。三者按step参数分派共享“merge 分支处于仓库根目录、依赖可能未安装、最终由编排者提交/安装”的统一上下文其中 resolve-conflicts 阶段会“先对 conflict 双方均接受”保留 changeset把判定与清理职责专门交给 clean-changesets避免冲突解决与发布语义判断互相干扰。理解这一点就能把本文的六个步骤放到完整的合并工作流中看待它是保证next预发布版本序列不被主分支历史污染、杜绝beta晚于稳定版发布的版本倒挂现象的最后一道关卡。【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考