Rust发布自动化工具cargo-release的使用：简化版本管理和Crates.io发布流程

cargo release

简化你的crate发布流程

cargo release 扩展了 cargo publish，提供了常见的发布实践，如验证、版本管理、标签和推送。该流程是可定制的，但提供了能够快速上手的默认设置。

功能包括

  • 确保发布前的良好状态：
    • 正确的分支
    • 与远程同步
    • 干净的工作树
  • 支持使用cargo原生标志（如 --workspace、--exclude 和 --package）的工作区
    • 在更改版本时更新工作区中的依赖crate
    • 变更检测以指导哪些crate可能不需要发布
    • 可选择共享提交
  • 处理 cargo publish、标签和推送
  • 预发布搜索和替换自定义版本更新，包括：
    • 更新CHANGELOG
    • 更新Dockerfile中的标签
  • 预发布钩子用于额外定制，包括：
    • CHANGELOG生成

安装

当前版本：0.25.18

$ cargo install cargo-release

使用

$ cargo release [level]
<dry-run output>
$ cargo release [level] --execute
  • 参阅参考文档了解更多关于 level、其他CLI参数和配置文件格式的信息
  • 参阅FAQ获取如何将cargo-release适配到你的工作流程的帮助

前提条件

  • 你的项目应该由git管理

试运行

默认情况下，cargo-release 以试运行模式运行，因此你可以安全地运行它并验证它将执行的操作。

  • 每增加一个 -v 可以提高日志级别以获取更多细节
  • 通过 --no-verify 跳过 cargo-publish 的验证步骤以加速试运行

当你准备好时，传递 --execute 标志。

相关工具

  • release-pr Action
  • cargo-smart-release
  • cargo-set-version
  • cargo-unleash
  • release-plz
  • cargo-workspaces

Semver兼容性

cargo-release的版本跟踪二进制文件的兼容性，而不是API。我们上传到crates.io以分发二进制文件。如果将其用作库，请使用 = 版本需求运算符固定版本。

许可证

根据以下任一许可证授权：

  • Apache License, Version 2.0
  • MIT license

贡献

除非你明确声明，否则任何有意提交用于包含在作品中的贡献，根据Apache-2.0许可证的定义，应按照上述双重许可，不附加任何额外条款或条件。

完整示例

以下是使用cargo-release的完整示例：

# 安装cargo-release
cargo install cargo-release

# 进入你的Rust项目目录
cd your_crate_project

# 首先进行试运行查看将执行的操作
cargo release patch -v

# 确认无误后执行实际发布
cargo release patch --execute

# 如果你想发布主要版本
cargo release major --execute

# 如果你想发布次要版本
cargo release minor --execute

# 如果你想自定义版本号
cargo release 1.2.3 --execute

对于工作区项目，你可以使用cargo的工作区标志：

# 发布整个工作区
cargo release --workspace patch --execute

# 发布特定包
cargo release -p my_crate patch --execute

你还可以在项目根目录创建 .cargo-release.toml 文件来自定义发布行为：

# 示例配置文件
[workspace]
# 共享所有包的提交
shared-version = true

[package]
# 预发布钩子脚本
pre-release-hook = "scripts/pre-release.sh"

[replacements]
# 发布前替换文件中的版本号
files = ["README.md"]
search = "version-{version}"
replace = "version-{next_version}"

1 回复

cargo-release：简化Rust项目的版本管理和发布流程

介绍

cargo-release 是一个Rust工具，用于自动化项目的版本管理和发布到crates.io的流程。它简化了以下操作：

  • 版本号更新
  • 变更日志生成
  • 创建Git标签
  • 发布到crates.io
  • 推送更改到远程仓库

安装

cargo install cargo-release

基本使用

1. 发布补丁版本更新 (0.1.0 → 0.1.1)

cargo release patch

2. 发布小版本更新 (0.1.0 → 0.2.0)

cargo release minor

3. 发布大版本更新 (0.1.0 → 1.0.0)

cargo release major

4. 自定义版本号

cargo release 2.0.0-beta.1

高级功能

预发布版本

# 发布预发布版本 (1.0.0 → 1.0.1-alpha.0)
cargo release --pre-release alpha

只执行部分步骤

# 只更新版本号但不发布
cargo release patch --no-publish

# 只执行到创建标签，不推送到远程
cargo release patch --no-push

自定义变更日志

cargo-release 支持自动更新 CHANGELOG.md 文件。确保项目根目录有该文件，工具会自动将提交信息整理到变更日志中。

配置选项

可以在 Cargo.toml 中添加 [package.metadata.release] 部分进行配置：

[package.metadata.release]
# 发布前运行的命令
pre-release-command = "cargo test"
# 跳过确认提示
no-confirm = true
# 自定义标签名称格式
tag-name = "v{{version}}"
# 推送到的远程分支
push-remote = "origin"

完整发布流程示例

  1. 确保所有更改已提交
  2. 运行发布命令：
cargo release minor
  1. 工具会：
    • 运行测试（如果配置了pre-release-command）
    • 更新Cargo.toml中的版本号
    • 更新CHANGELOG.md
    • 提交这些更改
    • 创建Git标签
    • 发布到crates.io
    • 推送提交和标签到远程仓库

注意事项

  • 确保你有crates.io的发布权限
  • 发布前确保所有测试通过
  • 工具会修改你的Git仓库，建议在干净的工作目录中使用
  • 可以使用--dry-run参数先查看将要执行的操作而不实际执行

cargo-release 大大简化了Rust项目的发布流程，减少了人为错误，确保发布过程的一致性和可重复性。

完整示例demo

下面是一个完整的发布流程示例：

# 1. 安装cargo-release
cargo install cargo-release

# 2. 创建一个新项目（如果还没有）
cargo new my_project
cd my_project

# 3. 初始化git仓库并提交初始代码
git init
git add .
git commit -m "Initial commit"

# 4. 添加一些代码更改并提交
echo "// 示例代码" >> src/main.rs
git add .
git commit -m "Add example code"

# 5. 创建CHANGELOG.md文件
touch CHANGELOG.md

# 6. 配置Cargo.toml（可选）
# 在Cargo.toml中添加：
# [package.metadata.release]
# pre-release-command = "cargo test"
# tag-name = "v{{version}}"

# 7. 执行预发布检查（可选）
cargo test

# 8. 发布小版本更新
cargo release minor

# 或者使用dry-run先查看将要执行的操作
cargo release minor --dry-run

这个示例展示了从项目初始化到使用cargo-release发布一个minor版本更新的完整流程。工具会自动处理版本号更新、变更日志、Git标签创建和crates.io发布等步骤。

回到顶部