UniFFI-RS 项目发布流程详解

UniFFI-RS 项目发布流程详解

uniffi-rs a multi-language bindings generator for rust 项目地址: https://gitcode.com/gh_mirrors/un/uniffi-rs

前言

UniFFI-RS 是一个用于创建跨语言绑定的 Rust 框架，它允许开发者用 Rust 编写代码并自动生成多种语言的绑定接口。本文将深入解析 UniFFI-RS 项目的发布流程，帮助开发者理解如何正确地进行版本发布。

发布工具与版本策略

UniFFI-RS 使用 cargo-release 工具来简化发布流程，这个工具能够自动处理版本号更新、提交变更等任务。需要注意的是，必须安装 v0.22 或更高版本，因为它支持工作区功能。

项目采用了一种独特的版本控制策略：

1. uniffi 主包：作为前端接口，对外提供主要功能，版本变更相对保守
2. uniffi_ 系列包*：主要用于内部或绑定生成器使用，版本变更较为频繁

这种分离的版本策略有助于减少对下游项目的影响，特别是当只有内部实现发生变化时。

发布前准备

在开始发布流程前，必须完成以下准备工作：

1. 更新变更日志：

   • 确保 CHANGELOG.md 中的"unreleased"部分包含了所有相关变更
   • 特别注意记录影响 UniFFI 使用者的任何变更

2. 确定版本号：

   • 对于 uniffi 主包：当前处于 1.0 之前，若有破坏性变更则增加次版本号，否则增加修订号
   • 对于 uniffi_* 系列包：保持所有包的版本号同步

发布分支管理

UniFFI-RS 采用分支策略来管理发布：

1. 分支命名：采用 release-v{主版本}.{次版本}.x 格式
2. 首次发布：
   • 创建新分支
   • 推送到远程仓库
3. 补丁发布：
   • 检出已有发布分支
   • 合并主分支的变更

这种策略确保了每个主要版本系列有自己的维护分支，便于后续的补丁发布。

发布流程详解

1. 发布后端包

首先发布除 uniffi 外的所有包：

cargo release-backend-crates {主版本}.{次版本}.{修订号}

这个命令会自动：

• 更新所有相关包的版本号
• 创建发布提交

2. 发布 uniffi 主包

重要：必须在前一步完成后执行，因为它依赖已发布的后端包。

cargo release-uniffi {主版本}.{次版本}.{修订号}

此命令会：

• 更新 uniffi 的版本号
• 创建版本标签

3. 代码审查与合并

创建合并请求，将发布分支的变更合并回发布分支本身。审查通过后，使用"merge commit"选项合并。

4. 正式发布

执行发布脚本：

./tools/publish-release.sh

5. 推送标签

将版本标签推送到远程仓库：

git push origin tag v{主版本}.{次版本}.{修订号}

6. 合并回主分支

创建新分支将发布变更合并回主分支：

1. 从主分支创建新分支
2. 合并版本标签
3. 推送并创建合并请求
4. 审查后使用"merge commit"选项合并

文档发布

新版本发布后，需要更新文档：

1. 安装文档工具依赖
2. 使用 mike 工具部署文档
3. 验证文档更新是否成功

版本策略背后的思考

UniFFI-RS 采用这种版本策略主要是为了解决依赖关系复杂性问题。在类似 Firefox 这样的复杂项目中：

• 主应用依赖多个使用 UniFFI 的库
• 这些库又依赖 UniFFI

传统的版本策略会导致即使是不相关的 UniFFI 变更也需要级联更新所有依赖库。通过分离 uniffi 主包和内部包的版本控制，可以：

1. 减少不必要的版本升级
2. 降低维护成本
3. 提高向后兼容性

特别是对于那些只影响绑定生成器而不影响普通使用者的变更，这种策略可以避免不必要的"发布舞蹈"。

最佳实践建议

1. 版本规划：提前规划版本变更类型，明确是破坏性变更还是非破坏性变更
2. 变更记录：每次提交都应及时更新变更日志，避免发布时遗漏
3. 测试验证：在正式发布前，充分测试新版本与现有项目的兼容性
4. 文档同步：确保文档与代码发布保持同步

通过遵循这套发布流程，UniFFI-RS 项目能够保持版本控制的稳定性和可维护性，同时为使用者提供清晰的升级路径。

uniffi-rs a multi-language bindings generator for rust 项目地址: https://gitcode.com/gh_mirrors/un/uniffi-rs