create-manifest

创建迁移清单

根据自上次发布以来的提交，为新的补丁版、Beta 版、RC 版或次版本创建迁移清单。

参数

• $ARGUMENTS - 目标版本，例如 0.5.15 或 0.6.0-beta.14。如果省略，请询问用户。

软件包发布模式

Trellis 目前使用同一个 git 标签发布两个 npm 软件包：

• @mindfoldhq/trellis
• @mindfoldhq/trellis-core

两个软件包必须始终使用完全相同的版本和 npm dist-tag。源码使用 workspace:*；打包后的 CLI 必须依赖精确的已发布 core 版本。

官方 npm 发布只能通过 CI 进行。切勿使用本地 npm publish 或 pnpm publish 来弥补发布失败或部分成功的情况。本地验证可使用 pnpm pack、release-preflight、测试、lint、typecheck 和 npm view。

步骤 1：确定上次发布版本

git tag --sort=-v:refname | head -5

选择当前发布线中最新的发布标签，例如 v0.5.14 或 v0.6.0-beta.13。

步骤 2：收集变更

git log <last-release-tag>..HEAD --oneline
git log <last-release-tag>..HEAD --oneline -- packages/cli/src/ packages/core/src/
git log <last-release-tag>..HEAD --oneline -- packages/cli/scripts/ .github/workflows/ package.json packages/*/package.json pnpm-lock.yaml

面向用户的变更日志应重点关注 packages/cli/src/ 和 packages/core/src/ 下的源码行为。仅当用户可观察到发布配置、工作流或软件包依赖方面的变更时，才将其列入 Internal，例如安装/更新可靠性或多软件包可用性。

步骤 3：分析每个相关提交

对于每个涉及相关源码或发布行为的提交：

1. 阅读差异：

   git diff <parent>...<commit> -- packages/cli/src/ packages/core/src/ --stat
   git diff <parent>...<commit> -- packages/cli/scripts/ .github/workflows/ package.json packages/*/package.json pnpm-lock.yaml --stat
   

2. 将其归类为 feat、fix、refactor 或 chore。
3. 按照 Conventional Commits 风格编写一行变更日志条目。

除非纯规格修改、机械式重构和仅限内部的清理会实质性改变用户可观察到的内容，否则都应省略。

步骤 4：起草变更日志

语气：技术参考文档。简短、清晰、平实。不要写成故事或宣传文案。遵循 .trellis/spec/docs-site/docs/style-guide.md -> “Changelog / Release Notes Voice”。

应做到：

• 每个 ### 章节先用一句话说明变更内容，然后列出表格、代码或项目符号。即可。
• 使用功能名称作为标题，例如 ### Joiner onboarding task。
• 包含便于 grep 搜索的标识符：文件路径、函数名、标志名称、迁移条目。
• 文档站点中的英文和中文变更日志应一一对应：章节、表格和代码块保持一致；仅翻译文字内容。

不要：

• 添加 “Why”、“Background” 或 “Rationale” 段落。
• 添加测试章节或测试数量。
• 除非用户可观察到相关行为，否则不要添加 Internal 条目。
• 不要使用反问句、煽情措辞、填充性副词或营销语气。
• 不要使用过时后会显得不合适或不便于 grep 搜索的结果导向型标题。

长度上限：每个 ### 章节应控制在约 120 个单词以内。

允许的顶级章节及顺序：

1. Enhancements
2. Bug Fixes
3. 仅在用户可观察到相关行为时添加 Internal
4. Upgrade

跳过空章节。

清单的 changelog 字段：

• 使用一个包含实际 \n 分隔符的字符串。
• 使用加粗前缀分组：**Enhancements:**、**Bug Fixes:**、**Internal:**。
• 内容应短于 MDX 变更日志，因为它会在终端的 trellis update 期间显示。

步骤 5：确定清单字段

字段	判定方法
breaking	是否有破坏性 API 或行为变更。修补版本／预发布版本的修复默认设为 false。
recommendMigrate	是否有用户应执行的重命名／删除迁移。修补版本的修复默认设为 false。当 breaking=true 且 recommendMigrate=true 时，若未指定 --migrate，trellis update 将以状态码 1 退出。
migrations	rename、rename-dir、delete 或 safe-file-delete 操作列表。修补版本的修复通常为 []。
migrationGuide	当 breaking=true 且 recommendMigrate=true 时必填。此人工迁移指南会插入生成的迁移任务 PRD 中。
aiInstructions	强烈建议与 migrationGuide 一起提供。用于指导 AI 辅助迁移的说明。
notes	更新期间显示的简短终端提示。

缺少 migrationGuide 的破坏性版本会导致升级体验出现问题。packages/cli/scripts/create-manifest.js 会对此进行验证。

步骤 5a：单个迁移条目的字段

字段	用途	必填
type	rename、rename-dir、delete 或 safe-file-delete	是
from	相对于项目根目录的源路径	是
to	目标路径	重命名时必填
description	迁移执行的操作，会显示在确认提示中	建议填写
reason	在提示修改文件时提供特定版本的背景信息	可选
allowed_hashes	安全删除时已知的未修改文件 SHA256 哈希值	safe-file-delete 时必填

rename 使用项目本地的 .trellis/.template-hashes.json；它不使用清单中的 allowed_hashes。

使用：

• 文件移至其他位置且有替代路径时，使用 rename。
• 文件已移除且没有替代文件时，使用 safe-file-delete。
• 已移除的文件功能并入其他命令时，使用 safe-file-delete 并添加 notes。

步骤 6：创建清单

通过标准输入传入 JSON：

cat <<'EOF' | node packages/cli/scripts/create-manifest.js
{
  "version": "<version>",
  "description": "<short description>",
  "breaking": false,
  "recommendMigrate": false,
  "changelog": "<changelog text with real newlines>",
  "notes": "<notes>",
  "migrations": []
}
EOF

对于包含多个重命名条目的破坏性版本，可用一个小型临时 Node 脚本生成条目，再将最终 JSON 通过管道传给 create-manifest.js。

步骤 7：创建文档站点更新日志

此步骤对每个版本都是必需的。

创建以下两个文件：

1. docs-site/changelog/v<version>.mdx
2. docs-site/zh/changelog/v<version>.mdx

使用近期更新日志文件中的格式。英文和中文的结构必须完全对应。

更新 docs-site/docs.json：

• 在顶部的英文更新日志页面列表中添加 "changelog/v<version>"。
• 在顶部的中文更新日志页面列表中添加 "zh/changelog/v<version>"。
• 将导航栏中的更新日志链接更新为新版本。

当 <Note> 或 <Warning> 块包含 Markdown 列表时，结束标签必须从第 0 列开始：

<Note>
- bullet
</Note>

步骤 8：文档生命周期

文档站点根路径保持稳定。开发周期内容位于 beta/ 或 rc/ 下。

转换	脚本	时间
开始新的 beta 阶段	docs-site/scripts/docs-beta-start.sh	新次要／主要版本的第一个 beta 版本发布前，例如 0.6.0-beta.0。
Beta 阶段转为 RC 阶段	docs-site/scripts/docs-beta-to-rc.sh	第一个 rc 版本发布前，例如 0.6.0-rc.0。
RC 阶段转为 GA 阶段	docs-site/scripts/docs-promote.sh	执行 pnpm release:promote 前。

单个修补版本（-beta.1、-rc.1、0.5.1）不运行生命周期脚本。编写更新日志 MDX、更新 docs.json、提交并推送 docs-site，然后更新主仓库的子模块指针。

完整参考：.trellis/spec/docs-site/docs/release-lifecycle.md。

步骤 9：发布前检查

仅运行本地验证；不要在本地发布。

node packages/cli/scripts/check-docs-changelog.js --type <beta|rc|promote>
node packages/cli/scripts/release-preflight.js check-versions
node packages/cli/scripts/release-preflight.js verify-packed-cli
node packages/cli/scripts/release-preflight.js publish-plan
pnpm lint
pnpm typecheck
pnpm test

只有在发布类型不要求运行 check-docs-changelog 的稳定修补版本中，才跳过此检查。

步骤 10：审查并确认

验证：

1. packages/cli/src/migrations/manifests/<version>.json 存在且包含有效的 JSON。
2. 清单中的 changelog 会渲染为实际换行。
3. 文档站点的两个 changelog MDX 文件都存在且内容完全一致。
4. 所有子模块提交都已推送，然后再提交主仓库指针（当前为 docs-site/ + marketplace/）。使用以下命令验证：git submodule foreach 'sha=$(git rev-parse HEAD); git ls-remote origin $sha | grep -q $sha && echo "ok $name" || echo "FAIL $name $sha"'。由标签触发的 CI 会运行 git submodule update --init --recursive，并在遇到第一个未推送的指针时失败，报错 fatal: remote error: upload-pack: not our ref <SHA>。
5. @mindfoldhq/trellis 和 @mindfoldhq/trellis-core 的版本仍然一致。

步骤 11：通过 CI 发布

使用项目发布脚本，让标签触发 CI：

pnpm release
pnpm release:beta
pnpm release:rc
pnpm release:promote

CI 成功后，验证 npm 上的公开包：

npm view @mindfoldhq/trellis@<version> version dist-tags --json --registry=https://registry.npmjs.org/
npm view @mindfoldhq/trellis-core@<version> version dist-tags --json --registry=https://registry.npmjs.org/

如果 CI 失败或 npm 可见性不正确，请修复工作流或脚本，然后重新运行 CI 流程。不要通过本地发布来弥补。

Dogfooding

破坏性发布必须在临时目录中端到端运行迁移：

mkdir /tmp/migrate-test && cd /tmp/migrate-test && git init -q .
npx -y @mindfoldhq/trellis@<last-ga> init -y -u test --claude --cursor --<platforms>
node <repo>/packages/cli/dist/cli/index.js update --migrate --dry-run
yes | node <repo>/packages/cli/dist/cli/index.js update --migrate --force
yes | node <repo>/packages/cli/dist/cli/index.js update

留意孤立文件、幂等性变更和备份膨胀。