RFC: Rust Crate RPM Packaging Policy

[yyjeqhc]

RFC: Rust Crate RPM Packaging Policy

1. 目标

本文定义 Rust crate、Rust 应用以及 Rust/Python 插件在 RPM 仓库中的打包规范。

本文只规定打包策略和一致性要求，不规定具体工具实现细节。具体工具可以是 TakoPack、rust-rpm-macros 或其他兼容实现，但生成结果必须满足本文规范。

2. 版本命名与兼容性规则

Rust crate provider 的 RPM 包名和 crate capability 必须按兼容性版本生成。

对于 X.y.z，其中 X >= 1：

crate_name X.y.z -> rust-crate-name-X
capability       -> crate(crate-name-X)

同一 major 版本线下，仓库原则上只应保留一个最高版本 provider。低版本应用应尽量使用同 major 的最高版本 provider。

只有在确认同 major 内部确实存在不可兼容变更，且无法通过补丁或依赖调整解决时，才允许同时保留同 major 下的多个实际版本。此类例外必须在 spec 或提交说明中说明原因。

对于 0.Y.z，其中 Y >= 1：

crate_name 0.Y.z -> rust-crate-name-0.Y
capability       -> crate(crate-name-0.Y)

同一 0.Y 版本线下，仓库原则上只应保留一个最高版本 provider。

对于 0.0.Z：

crate_name 0.0.Z -> rust-crate-name-0.0.Z
capability       -> crate(crate-name-0.0.Z)

0.0.Z 必须按精确版本单独存在。

除非上游包强制要求且无可行替代方案，不建议引入 rc、pre、alpha、beta 等预发布版本 provider。确需引入时，必须说明原因和影响范围。

3. Cargo.toml 与 spec 的一致性

使用 crate provider 构建的包，或者包本身是 Rust crate provider 的，必须在对应 SPECS/<pkg>/ 目录中提供与打包状态一致的 Cargo.toml。

如果需要对源码压缩包中的 Cargo.toml 打补丁，则必须同步修改 SPECS/<pkg>/Cargo.toml。

如果补丁修改会引起以下内容变化：

- crate Provides
- crate Requires
- feature capability
- BuildRequires
- dependency version requirement
- dependency feature set

则必须使用修改后的 Cargo.toml 重新生成 spec 文件。

不得只手工修改 spec 中的 Requires / Provides 来绕过 Cargo.toml 与 spec 不一致的问题。除非是极小且明确的临时 hotfix，否则 provider spec 应从补丁后的 Cargo.toml 重新生成。

4. Rust 应用与插件构建规范

Rust 应用包应使用：

BuildSystem: rust

Rust crate provider 应使用：

BuildSystem: rustcrates

Rust/Python 插件或扩展包通常应继续使用：

BuildSystem: pyproject

使用 crate 构建应用或插件时，应使用 rust-rpm-macros 提供的宏完成 Cargo registry 配置、lock 生成、离线构建和检查流程。

不得在 spec 中手写本地 registry 文件、手写 Cargo source replacement，或复制工具宏已经负责生成的 registry 配置。

Rust 应用默认应执行 cargo check 或宏中定义的等价检查流程。若因包自身原因无法执行，应在 spec 或提交说明中说明原因。

5. crate 或应用升级规则

crate、Rust 应用或 Rust/Python 插件升级时，可能引入新的 crate provider，也可能要求升级已有 crate provider。

升级前必须检查更新后的 crate 环境是否会破坏已有应用包的构建。

检查原则是：对受影响应用的 Cargo.toml 使用 Cargo api 生成最终 lock，并确认该 lock 可以由当前仓库中的 crate provider 满足。

不得仅根据直接依赖列表判断升级是否安全。

工具应能检查以下情况：

- 新增 provider
- 已有 provider 升级
- provider capability 变化
- feature capability 变化
- 应用最终 lock 是否仍可生成
- provider spec Requires 是否仍可满足

6. range dependency 处理规则

Cargo 的范围依赖可能跨越多个 RPM crate capability。

例如：

goblin = ">=0.9,<0.11"

Cargo 可以选择 goblin 0.10.x，但 RPM capability crate(goblin-0.9) 不能由 crate(goblin-0.10) 满足。

因此，当 dependency version requirement 跨越多个 RPM 兼容性 key 时，工具必须报警。

例如以下依赖必须报警：

goblin = ">=0.9,<0.11"
windows = ">=0.61,<0.63"
foo = ">=1,<3"
bar = "*"

推荐处理方式是：根据最终 lock 选中的版本，对 Cargo.toml 打补丁，将范围依赖收敛到实际使用版本，然后使用补丁后的 Cargo.toml 重新生成 spec。

不得在未确认真实需要的情况下，仅因为 OBS 报缺低版本 capability 就新增低版本 provider。

7. 预发布版本规则

不建议引入 rc、pre、alpha、beta 等预发布 crate provider。

如果上游依赖精确要求预发布版本，例如：

aead = "=0.6.0-rc.10"

不得自动替换为 stable 版本，除非已经完成实际构建验证并确认 API 兼容。

可接受处理方式包括：

- 引入对应预发布 provider；
- 打补丁切换到 stable 版本，并完成实际构建验证；
- 暂不支持该包或该版本。

本文只规定 Rust crate RPM 打包中必须保持的一致性语义。