create-manifest

移行マニフェストの作成

前回のリリース以降のコミットを基に、新しいパッチ、ベータ、RC、またはマイナーリリース用の移行マニフェストを作成します。

引数

• $ARGUMENTS - 対象バージョン。例：0.5.15 または 0.6.0-beta.14。省略された場合はユーザーに確認します。

パッケージのリリースモデル

Trellis は現在、同じ git タグから次の 2 つの 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 を使用できます。

Step 1: 最後のリリースを特定する

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

現在のリリース系列で最も新しいリリースタグを選びます。例：v0.5.14 または v0.6.0-beta.13。

Step 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 に記載します。

Step 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 形式で、変更履歴用の一行を作成します。

ユーザーが確認できる内容を実質的に変更しない限り、仕様書のみの編集、機械的なリファクタリング、内部のみのクリーンアップは除外します。

Step 4: 変更履歴の草案を作成する

文体：技術リファレンス文書。簡潔で、明瞭かつ平易にします。物語調や宣伝調にはしません。.trellis/spec/docs-site/docs/style-guide.md の「Changelog / Release Notes Voice」に従います。

次のようにします。

• 各 ### セクションの冒頭に、変更内容を述べる一文を置きます。その後に表、コード、または箇条書きを続けます。それで完了です。
• 見出しには機能名を使います。例：### Joiner onboarding task。
• grep で検索できる識別子を含めます。ファイルパス、関数名、フラグ名、移行エントリーなどです。
• docs-site の変更履歴では、英語と中国語を 1 対 1 で対応させます。同じセクション、同じ表、同じコードブロックを使い、文章のみを翻訳します。

次のことは避けます。

• 「Why」、「Background」、「Rationale」の段落を追加しないでください。
• テストのセクションやテスト件数を追加しないでください。
• ユーザーが動作を確認できる場合を除き、Internal エントリーを追加しないでください。
• 修辞的な質問、感情的な表現、冗長な副詞、マーケティング調を使わないでください。
• 時間が経つと古くなる、または grep で検索できない、結果を表す見出しを使わないでください。

長さの上限：各 ### セクションは約 120 語以内にします。

使用できるトップレベルセクションは、次の順序です。

1. Enhancements
2. Bug Fixes
3. ユーザーが動作を確認できる場合のみ Internal
4. Upgrade

内容のないセクションは省略します。

マニフェストの changelog フィールド：

• 実際の \n 区切りを使った単一の文字列にします。
• 太字の接頭辞でグループ化します：**Enhancements:**、**Bug Fixes:**、**Internal:**。
• trellis update の実行中にターミナルへ表示されるため、MDX の変更履歴より短くします。

ステップ 5：マニフェストのフィールドを決定する

フィールド	判断方法
breaking	API または動作に破壊的変更があるかどうかです。パッチ／プレリリースの修正では、デフォルトは false です。
recommendMigrate	ユーザーが実行すべき名前変更／削除の移行があるかどうかです。パッチ修正では、デフォルトは false です。breaking=true かつ recommendMigrate=true の場合、trellis update は --migrate を指定しないと終了コード 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 を stdin 経由で渡します。

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/ の下で行います。

移行	スクリプト	実行タイミング
新しいベータ版を開始	docs-site/scripts/docs-beta-start.sh	新しいマイナー／メジャーバージョンの最初のベータ版（例：0.6.0-beta.0）の前。
ベータ版から 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. docs-site の 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 の手順を再実行します。問題を埋め合わせるためにローカルから公開しないでください。

実運用テスト

破壊的変更を含むリリースでは、使い捨てディレクトリで移行をエンドツーエンドで実行する必要があります。

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

孤立ファイル、冪等性による不要な差分、バックアップの肥大化に注意します。