cargo-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo Release Protocol

Cargo 发布协议

When to Invoke

触发时机

Invoke this protocol when the user says: "release", "publish", "bump version", "ship", "tag a release", or "cut a version" for any crate in the trusty-tools monorepo.

当用户针对 trusty-tools 单仓中的任意 crate 说出以下指令时，执行本协议："release"、"publish"、"bump version"、"ship"、"tag a release" 或 "cut a version"。

Semver Bump Rules

语义化版本（Semver）升级规则

Determine the version increment from the commit history since the last tag:

Commit type	Bump
`BREAKING CHANGE` footer or `!` suffix (e.g. `feat!:` )	Major (X.0.0)
`feat:` — new capability, no breaking change	Minor (0.X.0)
`fix:` , `chore:` , `refactor:` , `perf:` , `docs:` , `test:`	Patch (0.0.X)

For the

trusty-mpm-*

family, all eight crates share a single workspace version and are bumped together regardless of which crate was touched.

根据上次标签后的提交历史确定版本增量：

提交类型	版本升级类型
`BREAKING CHANGE` 脚注或 `!` 后缀（例如 `feat!:` ）	主版本（X.0.0）
`feat:` — 新增功能，无破坏性变更	次版本（0.X.0）
`fix:` 、 `chore:` 、 `refactor:` 、 `perf:` 、 `docs:` 、 `test:`	补丁版本（0.0.X）

对于

trusty-mpm-*

系列的8个 crate，它们共享同一个工作区版本，无论哪个 crate 有变更，所有版本都会同步升级。

Crate Name vs Directory Name

Crate名称与目录名称

Cargo

-p

flags use the name
field in
Cargo.toml
, not the directory name:

Directory	Cargo flag	Tag prefix
`crates/trusty-git-analytics/`	`-p tga`	`tga-v`
`crates/open-mpm/`	`-p open-mpm`	`open-mpm-v`

All others: directory name equals crate name (e.g.

crates/trusty-search/

→

-p trusty-search

, tag

trusty-search-v

Cargo 的

-p

参数使用 Cargo.toml
中的
name
字段，而非目录名称：

目录	Cargo 参数	标签前缀
`crates/trusty-git-analytics/`	`-p tga`	`tga-v`
`crates/open-mpm/`	`-p open-mpm`	`open-mpm-v`

其他所有 crate：目录名称与 crate 名称一致（例如

crates/trusty-search/

→

-p trusty-search

，标签为

trusty-search-v

）。

10-Step Release Sequence

十步发布流程

Execute steps in order. Stop on any failure.

按顺序执行步骤，任何步骤失败立即停止。

Step 1 — Bump the crate version

步骤1 — 升级 crate 版本

toml

undefined

toml

undefined

crates/<name>/Cargo.toml

[package] version = "0.5.1" # was 0.5.0


For `trusty-mpm-*`, the version is set under `[workspace.package]` in the root `Cargo.toml`. Bump it once; all `trusty-mpm-*` crates inherit it.

[package] version = "0.5.1" # 原版本为0.5.0


对于 `trusty-mpm-*` 系列，版本在根目录 `Cargo.toml` 的 `[workspace.package]` 下设置。只需升级一次，所有 `trusty-mpm-*` crate 会自动继承该版本。

Step 2 — Update all dependent crates in the workspace

步骤2 — 更新工作区内所有依赖该 crate 的项目

If other crates pin the version being bumped (e.g.

trusty-common = "0.4.20"

), update every occurrence to the new version. Use

grep

to find all pins:

bash

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

Never commit Step 1 without completing Step 2 — a partial update breaks

cargo check

workspace-wide.

如果其他 crate 固定了当前升级的版本（例如

trusty-common = "0.4.20"

），需将所有引用更新为新版本。使用

grep

查找所有固定版本的位置：

bash

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

绝对不能只提交步骤1的变更而跳过步骤2——部分更新会导致整个工作区的

cargo check

失败。

Step 3 — Quality gate: tests

步骤3 — 质量门禁：测试

bash

cargo test -p <crate>

Must produce:

test result: ok. N passed; 0 failed; ...

bash

cargo test -p <crate>

必须输出：

test result: ok. N passed; 0 failed; ...

Step 4 — Quality gate: clippy

步骤4 — 质量门禁：Clippy 检查

bash

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

Must produce no warnings. See

rust-quality-gate

for the

open-mpm

exception.

bash

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

必须无警告输出。

open-mpm

的例外情况请参考

rust-quality-gate

。

Step 5 — Quality gate: format

步骤5 — 质量门禁：代码格式化检查

bash

cargo fmt --check

Must produce no output (exit 0). Fix with

cargo fmt

if needed.

bash

cargo fmt --check

必须无输出（退出码为0）。如有问题，使用

cargo fmt

修复。

Step 6 — Commit the version bump

步骤6 — 提交版本升级变更

bash

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

Example:

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

For

trusty-mpm-*

family:

chore(trusty-mpm): bump to v0.7.0

bash

git add crates/<name>/Cargo.toml   # 以及所有更新过的依赖项Cargo.toml文件
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

Step 7 — Create the git tag

步骤7 — 创建Git标签

Tag format:

<crate-name>-v<version>

bash

git tag trusty-memory-v0.5.1

Examples:

```
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
```
(one tag per
```
trusty-mpm-*
```
crate)

标签格式：

<crate-name>-v<version>

bash

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-*
```
crate 单独打标签）

Step 8 — Push the tag to GitHub

步骤8 — 将标签推送到GitHub

bash

git push origin trusty-memory-v0.5.1

Push the commit first if not already on the remote:

bash

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

bash

git push origin trusty-memory-v0.5.1

如果提交尚未推送到远程仓库，先推送提交：

bash

git push origin main   # 或当前分支
git push origin trusty-memory-v0.5.1

Step 9 — Publish to crates.io

步骤9 — 发布到crates.io

bash

cargo publish -p trusty-memory

Publishing order for cross-crate deps: publish dependencies before consumers. If

trusty-common

is being published alongside

trusty-search

, publish

trusty-common

first and wait for the index to propagate (~30 seconds) before publishing

trusty-search

publish = false
crates — skip this step: Some crates are not published to crates.io. Check the crate's

Cargo.toml

for:

toml

[package]
publish = false

Known non-published crates include those that are internal-only or tightly coupled to the monorepo. Skip Step 9 for these and proceed directly to Step 10.

bash

cargo publish -p trusty-memory

跨crate依赖的发布顺序：先发布依赖项，再发布消费者。如果

trusty-common

和

trusty-search

同时发布，需先发布

trusty-common

，等待索引同步（约30秒）后再发布

trusty-search

。

publish = false
的crate — 跳过此步骤：部分crate不会发布到crates.io。检查 crate 的

Cargo.toml

：

toml

[package]
publish = false

已知不发布的crate包括内部专用或与单仓强耦合的项目，直接跳过步骤9进入步骤10。

Step 10 — Install binary locally (binary crates only)

步骤10 — 本地安装二进制文件（仅二进制crate）

For crates that produce a binary, install it to PATH after publishing:

bash

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

Examples:

bash

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

对于生成二进制文件的crate，发布后安装到PATH：

bash

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

示例：

bash

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

macOS Codesign Safety Rule (Critical)

macOS代码签名安全规范（关键）

NEVER copy a release binary directly to
~/.cargo/bin/
:

bash

undefined

绝对不要直接将发布二进制文件复制到
~/.cargo/bin/
：

bash

undefined

WRONG — causes EXC_CRASH / CODESIGNING on macOS

错误操作 — 在macOS上会导致EXC_CRASH / CODESIGNING错误

cp target/release/trusty-search ~/.cargo/bin/trusty-search


On macOS, `cargo build` produces "ad-hoc linker-signed" binaries. The kernel's code-signing cache is keyed by `cdhash`. A plain `cp` over an existing on-PATH binary leaves the kernel with a stale cached identity. The next execution is killed with `EXC_CRASH / CODESIGNING — Taskgated Invalid Signature` before any code runs, producing only `zsh: killed` with zero output — indistinguishable from an OOM kill but unrelated.

`cargo install` writes to a temp path and renames atomically, keeping the signing cache consistent. Always use it.

If a manual copy was made by mistake, fix with:
```bash
codesign --force --sign - ~/.cargo/bin/<binary>

cp target/release/trusty-search ~/.cargo/bin/trusty-search


在macOS上，`cargo build` 生成的是“临时链接签名”的二进制文件。内核的代码签名缓存以 `cdhash` 为键。直接复制覆盖PATH中的现有文件会导致内核缓存的签名失效，下次执行时会被 `EXC_CRASH / CODESIGNING — Taskgated Invalid Signature` 终止，仅输出 `zsh: killed`，与内存不足导致的崩溃无法区分，但实际与内存无关。

`cargo install` 会先写入临时路径再原子重命名，确保签名缓存一致。请始终使用此命令。

如果不慎执行了手动复制，使用以下命令修复：
```bash
codesign --force --sign - ~/.cargo/bin/<binary>

trusty-mpm-* Family Release

trusty-mpm-* 系列发布流程

The

trusty-mpm-*

family uses a shared workspace version. Release all eight crates together:

Bump
```
version
```
under
```
[workspace.package]
```
in root
```
Cargo.toml
```
.

Run quality gates across all

trusty-mpm-*

crates:

cargo test -p trusty-mpm-core

cargo test -p trusty-mpm-mcp

, etc.

Commit:
```
chore(trusty-mpm): bump to v<version>
```
.

Tag each crate separately:

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>

Publish publishable crates in dependency order (core → client → mcp/daemon/cli/tui/telegram/gui).

Install binaries:

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

trusty-mpm-*

系列使用共享工作区版本，需同时发布所有8个crate：

升级根目录
```
Cargo.toml
```
中
```
[workspace.package]
```
下的
```
version
```
。

对所有

trusty-mpm-*

crate 执行质量门禁：

cargo test -p trusty-mpm-core

、

cargo test -p trusty-mpm-mcp

等。

提交变更：
```
chore(trusty-mpm): bump to v<version>
```
。

为每个crate单独打标签：

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>

。

按依赖顺序发布可发布的crate（core → client → mcp/daemon/cli/tui/telegram/gui）。

安装二进制文件：

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

。

Cross-Crate Library Release Checklist

跨Crate库发布检查清单

When releasing a shared library (

trusty-common

trusty-mcp-core

trusty-embedder

trusty-symgraph

Bump library version (Step 1).
Update all dependent crates'
```
Cargo.toml
```
version pins (Step 2) — use
```
grep
```
to find every reference.
Run
```
cargo check
```
(workspace-wide) to confirm the workspace compiles with the new version.

Run

cargo test -p <lib>

and

cargo test -p <consumer>

for each dependent.

Commit all Cargo.toml changes together — workspace builds are atomic.
Publish the library first; wait ~30 seconds for index propagation.
Publish consumers in order.

发布共享库（

trusty-common

、

trusty-mcp-core

、

trusty-embedder

、

trusty-symgraph

）时：

升级库版本（步骤1）。
更新所有依赖该库的crate的
```
Cargo.toml
```
版本固定值（步骤2）——使用
```
grep
```
查找所有引用。
执行
```
cargo check
```
（全工作区）确认新版本下工作区可编译。
对库和每个依赖它的消费者分别执行
```
cargo test -p <lib>
```
和
```
cargo test -p <consumer>
```
。
一次性提交所有
```
Cargo.toml
```
变更——工作区构建是原子操作。
先发布库，等待约30秒索引同步。
按顺序发布消费者。

Evidence Required

需提交的完成证明

After completing the release, report:

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

完成发布后，提交以下信息：

已发布：trusty-memory v0.5.1
标签：trusty-memory-v0.5.1（已推送到origin）
发布链接：https://crates.io/crates/trusty-memory/0.5.1
已安装：cargo install --path crates/trusty-memory --locked ✓
测试结果：ok. 87 passed; 0 failed; 5 ignored
Clippy检查：无警告
格式化检查：无问题

Anti-Patterns

反模式

Copying binaries with
```
cp
```
instead of
```
cargo install
```
on macOS — causes
```
zsh: killed
```
/ codesign crash.
Publishing a consumer crate before its newly-bumped library dependency is available on crates.io.
Forgetting to update dependent crates' version pins after bumping a library — breaks workspace compilation.
Tagging before quality gates pass — a bad tag requires a follow-up patch release.
Using
```
cargo install
```
without
```
--locked
```
— may resolve different dependency versions than what was tested.
Skipping Step 2 for
```
trusty-mpm-*
```
— the shared workspace version must be consistent across all eight crates.

在macOS上用
```
cp
```
复制二进制文件而非
```
cargo install
```
——会导致
```
zsh: killed
```
/ 代码签名崩溃。
在依赖的新版本库发布到crates.io之前，先发布消费者crate。
升级库版本后忘记更新依赖crate的版本固定值——导致工作区编译失败。
质量门禁未通过就打标签——错误标签需要后续补丁版本修复。
使用
```
cargo install
```
时不加
```
--locked
```
——可能解析出与测试时不同的依赖版本。
```
trusty-mpm-*
```
系列跳过步骤2——共享工作区版本必须在8个crate中保持一致。