release-tool 0.3.0

Configuration-driven release lifecycle for computed-parameter repositories
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# Cargo registry consumption

## Interface

adopter 通过 Cargo registry 获取 released `release-tool` crate，不安装 global binary：

```text
adopter repository
├── release.toml
├── Cargo.lock                    # exact crate version + registry checksum
├── tooling/release-tool-runner/
│   ├── Cargo.toml
│   └── src/main.rs
└── justfile
```

```toml
# tooling/release-tool-runner/Cargo.toml

[package]
name = "release-tool-runner"
version = "0.0.0"
edition = "2024"
publish = false

[dependencies]
# Cargo compatibility range: >=0.2.0, <0.3.0
release-tool = "0.2"
```

```rust
// tooling/release-tool-runner/src/main.rs

fn main() -> std::process::ExitCode {
    release_tool::cli::entrypoint()
}
```

```just
publish *args:
    cargo run --release --locked \
        -p release-tool-runner -- publish {{ args }}
```

publish 入口不使用 `--quiet`。首次 fetch/compile 可能需要时间，Cargo progress 是运行状态与
toolchain/network/dependency 故障的必要诊断信息。

## Acquisition contract

```text
first run
  Cargo reads the committed lock
  -> fetch exact released crate + checksum from registry
  -> compile release-tool + runner
  -> cache source/build output
  -> execute CLI lifecycle

later runs
  reuse the same locked implementation and build cache
  -> execute CLI lifecycle
```

`release-tool` 不自行下载或替换自己。Cargo registry 是 acquisition adapter，`Cargo.lock` 是
resolved-version seam。GitHub Release binary、mutable Git branch 和 raw `rev` 都不属于 adopter
interface。

## Version identities

```text
Cargo.toml requirement: release-tool = "0.2"
  声明 compatible implementation line（>=0.2.0, <0.3.0）

Cargo.lock
  记录本次实际执行的 exact crate version、registry source 与 checksum

release.toml.required_version
  声明当前 config shape 需要的 minimum release-tool capability

ReleasePlan.tool_version
  记录本次实际执行的 crate version
```

这三个约束不能合并：compatibility range 不是 resolved version，minimum config capability 也不是
dependency selector。

target dependencies 与 OCI image publication capability 从 `0.3.0` 开始；该 adopter 显式选择
新的 compatibility line：

```toml
[dependencies]
# >=0.3.0, <0.4.0；具体版本仍由 committed Cargo.lock 决定
release-tool = "0.3"
```

这不是 GitHub repository tag/revision pin。Cargo registry requirement、committed lock 与
`required_version = "0.3.0"` 继续承担三个独立职责。

## Compatibility policy

```text
0.2.z
  backward-compatible fixes / additive behavior
  adopter Cargo.toml 不变

0.3.0
  breaking Rust interface、config semantics 或 lifecycle contract
  adopter 必须显式迁移 dependency range

1.x（interface 稳定后）
  normal SemVer minor/patch compatibility
```

## Upgrade

不在 `publish` 运行时解析 `latest`。否则同一 project commit 的两次 recovery 可能使用不同
implementation，SemVer compatibility 也不保证 artifact bytes 相同。

upgrade 是一个自动生成、可 review 的 lockfile change：

```text
release-tool publishes compatible 0.2.z
  -> dependency bot runs cargo update -p release-tool
  -> PR contains Cargo.lock change
  -> adopter CI verifies release integration
  -> compatible update may auto-merge
```

```bash
cargo update -p release-tool
cargo test --locked -p release-tool-runner
```

`--locked` 是 publish interface 的一部分；发布命令不会隐式升级工具。breaking `0.3.0` 必须同时
修改 runner manifest、Cargo.lock 和需要变化的 `release.toml`。