cargo-release

Cargo リリースプロトコル

実行するタイミング

trusty-tools モノレポ内のいずれかのクレートについて、ユーザーが「リリース」「公開」「バージョンを上げる」「出荷」「リリースにタグを付ける」「バージョンを切る」と言った場合に、このプロトコルを実行します。

Semver のバージョン更新ルール

最後のタグ以降のコミット履歴から、バージョンの増分を判断します。

コミットの種類	更新
BREAKING CHANGE フッター、または ! 接尾辞（例：feat!:）	メジャー（X.0.0）
feat: — 破壊的変更を伴わない新機能	マイナー（0.X.0）
fix:, chore:, refactor:, perf:, docs:, test:	パッチ（0.0.X）

trusty-mpm-* ファミリーでは、8 つすべてのクレートが単一のワークスペースバージョンを共有し、変更されたクレートにかかわらず一括で更新します。

クレート名とディレクトリ名

Cargo の -p フラグでは、ディレクトリ名ではなく Cargo.toml の name フィールドを使用します。

ディレクトリ	Cargo フラグ	タグの接頭辞
crates/trusty-git-analytics/	-p tga	tga-v
crates/open-mpm/	-p open-mpm	open-mpm-v

その他はすべて、ディレクトリ名とクレート名が同じです（例：crates/trusty-search/ → -p trusty-search、タグは trusty-search-v）。

リリースの 10 ステップ

順番どおりに実行してください。失敗した場合は、そこで停止してください。

ステップ 1 — クレートのバージョンを更新する

# crates/<name>/Cargo.toml
[package]
version = "0.5.1"   # was 0.5.0

trusty-mpm-* の場合、バージョンはルートの Cargo.toml にある [workspace.package] で設定されています。バージョンを一度更新すると、すべての trusty-mpm-* クレートに継承されます。

ステップ 2 — ワークスペース内のすべての依存クレートを更新する

他のクレートが更新対象のバージョンを固定している場合（例：trusty-common = "0.4.20"）、すべての該当箇所を新しいバージョンに更新します。grep を使って、固定している箇所をすべて見つけてください。

grep -r '"<old-version>"' crates/ --include="Cargo.toml"

ステップ 2 を完了せずにステップ 1 の変更をコミットしてはいけません。一部だけを更新すると、ワークスペース全体の cargo check が失敗します。

ステップ 3 — 品質ゲート：テスト

cargo test -p <crate>

次の出力が必要です：test result: ok. N passed; 0 failed; ...

ステップ 4 — 品質ゲート：clippy

cargo clippy -p <crate> -- -D warnings

警告が出ないことが必要です。open-mpm の例外については、rust-quality-gate を参照してください。

ステップ 5 — 品質ゲート：フォーマット

cargo fmt --check

出力がないこと（終了コード 0）が必要です。必要に応じて cargo fmt で修正してください。

ステップ 6 — バージョン更新をコミットする

git add crates/<name>/Cargo.toml   # and any updated dependent Cargo.toml files
git commit -m "chore(<crate>): bump to v<version>"

例：chore(trusty-memory): bump to v0.5.1

trusty-mpm-* ファミリーの場合：chore(trusty-mpm): bump to v0.7.0

ステップ 7 — git タグを作成する

タグの形式：<crate-name>-v<version>

git tag trusty-memory-v0.5.1

例：

• trusty-search-v1.2.0
• trusty-memory-v0.5.1
• tga-v0.3.0
• open-mpm-v0.2.1
• trusty-mpm-cli-v0.7.0（trusty-mpm-* クレートごとに 1 つのタグ）

ステップ 8 — タグを GitHub にプッシュする

git push origin trusty-memory-v0.5.1

コミットがまだリモートにない場合は、先にプッシュしてください。

git push origin main   # or the current branch
git push origin trusty-memory-v0.5.1

ステップ 9 — crates.io に公開する

cargo publish -p trusty-memory

クレート間依存関係がある場合の公開順序：利用側より先に依存先を公開します。trusty-common と trusty-search を同時に公開する場合は、まず trusty-common を公開し、インデックスに反映されるまで（約 30 秒）待ってから trusty-search を公開してください。

publish = false のクレート — このステップをスキップ：crates.io に公開されないクレートもあります。クレートの Cargo.toml で次を確認してください。

[package]
publish = false

公開されないことが分かっているクレートには、内部専用のものやモノレポと密接に結合しているものがあります。これらはステップ 9 をスキップし、そのままステップ 10 に進んでください。

ステップ 10 — バイナリをローカルにインストールする（バイナリクレートのみ）

バイナリを生成するクレートの場合は、公開後に PATH へインストールします。

cargo install --path crates/<dir> --locked

例：

cargo install --path crates/trusty-search --locked
cargo install --path crates/trusty-mpm-cli --locked
cargo install --path crates/trusty-memory --locked

macOS コード署名の安全ルール（重要）

リリースバイナリを ~/.cargo/bin/ に直接コピーしてはいけません：

# WRONG — causes EXC_CRASH / CODESIGNING on macOS
cp target/release/trusty-search ~/.cargo/bin/trusty-search

macOS では、cargo build によって「アドホックリンカー署名」されたバイナリが生成されます。カーネルのコード署名キャッシュは cdhash をキーにしています。既存の PATH 上のバイナリを単純な cp で上書きすると、カーネルに古いキャッシュ済みの ID が残ります。次回の実行時、コードが実行される前に EXC_CRASH / CODESIGNING — Taskgated Invalid Signature で終了し、出力は zsh: killed のみになります。これは OOM による強制終了と見分けがつきませんが、OOM とは無関係です。

cargo install は一時パスに書き込んでからアトミックに名前を変更するため、署名キャッシュの整合性が保たれます。必ずこれを使用してください。

誤って手動でコピーした場合は、次のコマンドで修正してください：

codesign --force --sign - ~/.cargo/bin/<binary>

trusty-mpm-* ファミリーのリリース

trusty-mpm-* ファミリーでは、ワークスペースで共通のバージョンを使用します。8 つすべてのクレートをまとめてリリースしてください：

1. ルートの Cargo.toml にある [workspace.package] の下で version を更新します。
2. すべての trusty-mpm-* クレートで品質ゲートを実行します：cargo test -p trusty-mpm-core、cargo test -p trusty-mpm-mcp など。
3. コミットします：chore(trusty-mpm): bump to v<version>。
4. 各クレートに個別のタグを付けます：trusty-mpm-core-v<version>、trusty-mpm-mcp-v<version>、trusty-mpm-daemon-v<version>、trusty-mpm-client-v<version>、trusty-mpm-cli-v<version>、trusty-mpm-tui-v<version>、trusty-mpm-telegram-v<version>、trusty-mpm-gui-v<version>。
5. 公開可能なクレートを依存関係の順に公開します（core → client → mcp/daemon/cli/tui/telegram/gui）。
6. バイナリをインストールします：cargo install --path crates/trusty-mpm-cli --locked。

クレート間共有ライブラリのリリースチェックリスト

共有ライブラリ（trusty-common、trusty-mcp-core、trusty-embedder、trusty-symgraph）をリリースする場合：

1. ライブラリのバージョンを更新します（Step 1）。
2. 依存するすべてのクレートの Cargo.toml にあるバージョン固定を更新します（Step 2）。grep を使ってすべての参照を確認してください。
3. cargo check（ワークスペース全体）を実行し、新しいバージョンでワークスペースがコンパイルできることを確認します。
4. cargo test -p <lib> と、依存する各クレートに対して cargo test -p <consumer> を実行します。
5. すべての Cargo.toml の変更をまとめてコミットします。ワークスペースのビルドはアトミックです。
6. 先にライブラリを公開し、インデックスへの反映を約 30 秒待ちます。
7. 依存するクレートを順に公開します。

必要な証跡

リリース完了後、次の内容を報告してください：

Released: trusty-memory v0.5.1
Tag: trusty-memory-v0.5.1 (pushed to origin)
Published: https://crates.io/crates/trusty-memory/0.5.1
Installed: cargo install --path crates/trusty-memory --locked ✓
Test result: ok. 87 passed; 0 failed; 5 ignored
Clippy: clean
Fmt: clean

アンチパターン

• macOS で cargo install の代わりに cp でバイナリをコピーすること。zsh: killed やコード署名クラッシュの原因になります。
• 新しくバージョンを上げたライブラリ依存関係が crates.io で利用可能になる前に、依存するクレートを公開すること。
• ライブラリのバージョンを上げた後、依存するクレートのバージョン固定を更新し忘れること。ワークスペースのコンパイルが失敗します。
• 品質ゲートに合格する前にタグを付けること。不適切なタグを付けると、後続のパッチリリースが必要になります。
• --locked を付けずに cargo install を使用すること。テスト時とは異なる依存関係のバージョンが解決される可能性があります。
• trusty-mpm-* の Step 2 を省略すること。共有ワークスペースのバージョンは、8 つすべてのクレートで一致している必要があります。