librespot 发布流程全解从版本预备到多 Crate 有序发布到 crates.io【免费下载链接】librespotOpen Source Spotify client library项目地址: https://gitcode.com/GitHub_Trending/li/librespotlibrespot 是一个由 8 个本地 crate 组成的 Rust workspace向 crates.io 发布时存在严格的依赖顺序约束。本文以仓库中的 PUBLISHING.md 为主线结合 prepare-release.yml、release.yml 与 bump-versions.sh 的真实实现完整拆解 librespot 的发布预备、版本升级规则、GitHub Release 创建与 crates 发布自动化帮助读者掌握一套可复用的多 crate 项目发布工作流。一、发布流程总览PUBLISHING.md 将发布过程概括为两个阶段Prepare the release预备发布升级版本号、按 Keep a Changelog 规范更新 CHANGELOG.md、提交并推送变更。项目提供了一个手动触发workflow_dispatch的自动化工作流 prepare-release.yml当然也可以完全手工完成。Creating a GitHub release创建 GitHub Release以vversion命名标签创建 release并作为draft草稿发布草稿的创建动作会触发发布工作流 release.yml自动完成 crates 的有序发布与二进制发布。预备工作流负责的具体事项摘自 PUBLISHING.md按目标发布类型major/minor/patch升级版本号major和minor要求所有crate 版本同步更新patch只升级有代码变更的 crate。按 Keep a Changelog 约定更新 changelogCHANGELOG.md 文件头部声明遵循 Keep a Changelog 1.1.0 与 Semantic Versioning。提交并推送变更到远端。预备工作流是如何执行的prepare-release.yml 是一个workflow_dispatch手动工作流唯一输入是versionBumpchoice 类型取值为major、minor、patch。其执行链条为Checkoutfetch-tags: true拉取完整标签历史供后续git describe/git diff对比上一版本使用Bump versions以环境变量fragment传入升级类型执行 bump-versions.shUpdate Cargo.lock运行cargo update --workspace保证锁文件同步Get binary version从根 Cargo.toml 第一行version字段提取二进制版本Update Changelog使用keep-a-changelog-new-releaseaction以vversion为 tag 把[Unreleased]段落定版为新版本小节Create PR通过peter-evans/create-pull-request把上述变更提交为 PR分支名为prepare-release/vversionPR 正文内附审查清单版本升级是否正确、Cargo.lock是否只更新了自家 crate、changelog 是否准确完整。仓库还附带了一个 prepare-release.event 示例事件文件用于本地用 act 模拟触发该工作流act --job prepare-release --eventpath ./.github/example/prepare-release.event示例内容是一个versionBump: minor的 workflow_dispatch 事件体。版本升级脚本的核心逻辑bump-versions.sh 是“patch 只升有变更的 crate”这一规则的实现载体其逻辑如下脚本维护了一个允许升级的 crate 白名单protocol oauth core discovery audio metadata playback connect当fragment为patch时先git describe --tags --abbrev0找到上一个 tag再用git diff last_tag...统计有变更的文件只保留.rs与.proto源文件且路径落在白名单 crate 目录下的条目得到实际需要升级的 crate 列表否则major/minor则对全部白名单 crate 统一升级“for consistency”保持一致性列表末尾始终追加bin表示根 crate即可执行文件librespot的版本也要升级对每个 crate脚本从其Cargo.toml读取当前版本计算新版本后用sed做三处替换crate 自身Cargo.toml的版本、根 Cargo.toml 中[workspace.dependencies]对应的条目、以及其他引用该 crate 的 crate 的依赖版本。当前仓库中所有 crate含根 crate版本均为0.8.0见根 Cargo.toml 与各子 crate 的Cargo.tomlworkspace 依赖声明在 Cargo.toml[workspace.dependencies] librespot-audio { version 0.8.0, path audio, default-features false } librespot-connect { version 0.8.0, path connect, default-features false } librespot-core { version 0.8.0, path core, default-features false } librespot-discovery { version 0.8.0, path discovery, default-features false } librespot-metadata { version 0.8.0, path metadata, default-features false } librespot-oauth { version 0.8.0, path oauth, default-features false } librespot-playback { version 0.8.0, path playback, default-features false } librespot-protocol { version 0.8.0, path protocol, default-features false }注意 workspace 依赖统一使用default-features false根 crate 再通过自己的 feature 门控如native-tls、rodio-backend、with-libmdns等向下传递能力开关——这正是各子 crate 可独立发布、按需组合的前提。二、创建 GitHub Release以草稿触发发布按照 PUBLISHING.md预备完成后需要创建一个新 release要点标签不会自动存在预备工作流只改版本号和 changelog并不会打 tag因此创建 release 时需要新建标签命名规范tag 与 release 名称均为vversion其中version是待发布的二进制根 cratelibrespot的版本号Release notes直接拷贝 CHANGELOG.md 中对应版本的条目必须创建为 draft草稿 release 的创建事件才会触发发布工作流完成 crate 与二进制的发布工作流成功之后再将该 draft 正式发布publish。三、发布自动化release.yml 做了什么release.yml 监听release.created事件同时也支持workflow_dispatch手动触发核心步骤安装 stable Rust 工具链与 Rust 依赖缓存安装系统依赖libasound2-dev音频后端编译所需Verify先执行cargo publish --workspace --dry-run对整个 workspace 做发布预检Publish携带CARGO_REGISTRY_TOKEN来自仓库 secrets执行cargo publish --workspace一次性按依赖顺序发布全部 crate。工作流中通过if: ${{ !env.ACT }}跳过真实发布步骤使得整个发布过程可以在本地用 act 模拟演练与预备工作流的测试方式一致。四、crates 的发布顺序与 protocol 的特殊性PUBLISHING.md 的 Notes 一节指出了这套发布流程“略显曲折”的根源各包之间存在大量本地包相互依赖实测可行的发布顺序为protocol - core - audio - metadata - playback - connect - librespot即先发布最底层的librespot-protocolSpotify 通信的 protobuf 逻辑再依次向上一层发布最终发布根 cratelibrespot含二进制。发布方式是在各 crate 目录下执行cargo publish。protocol 为什么需要 --no-verifyPUBLISHING.md 特别指出protocol包必须使用cargo publish --no-verify发布原因是其构建脚本会在编译期修改源码。这一点可以从 protocol/Cargo.toml 得到印证[package] name librespot-protocol build build.rs # 声明了构建脚本 [dependencies] protobuf 3 [build-dependencies] protobuf-codegen 3 # 构建期生成 protobuf 代码build.rs借助protobuf-codegen将 protocol/proto 目录下数百个.proto文件在编译期生成 Rust 代码。普通cargo publish会执行完整构建验证包含构建脚本而该脚本的生成/改写行为在发布校验环境中会干扰验证过程因此跳过验证--no-verify是该包发布时的必要处理。依赖顺序与源码结构的对应关系从各 crate 的Cargo.toml描述可确认其职责分层librespot-protocolprotobuf 通信层被上层各 crate 依赖librespot-core核心功能、librespot-audio音频拉取、librespot-metadata元数据、librespot-playback播放、librespot-connectSpotify Connect、librespot-oauthOAuth 登录、librespot-discovery设备发现依次构建根 cratelibrespot在 Cargo.toml 中依赖全部 8 个子 crate 并对外提供统一 feature 门面。发布顺序必须自底向上正是因为上层 crate 的Cargo.toml以精确版本号声明了对下层 crate 的依赖——只有下层新版本已存在于 crates.io上层才能通过cargo publish的校验。五、changelog 与语义化版本预备阶段的“更新 changelog”对应 CHANGELOG.md 顶部的声明格式基于 Keep a Changelog自 v0.2.0 起遵循语义化版本Semantic Versioning。当前 CHANGELOG.md 中[Unreleased]段落按Added/Changed/Fixed分类记录条目且每条以[crate 名]前缀标注所属模块如[connect]、[core]、[playback]对破坏性变更显式标注(breaking)。预备工作流的keep-a-changelog-new-release步骤正是把这一[Unreleased]段落定版为## [新版本号] - 日期小节。这也解释了 patch 模式下“只升有变更的 crate”的设计[crate 名]前缀让变更与 crate 的对应关系一目了然git diff的源码变更检测与之互为印证。六、手工发布备忘如果不使用自动化工作流PUBLISHING.md 描述的等价手工路径是按major/minor/patch规则手工更新各 crate 及根 crate 的版本patch 时只改有变更的 crate并同步根 Cargo.toml 的[workspace.dependencies]与相互依赖的版本号——这正是 bump-versions.sh 自动完成的三处替换按 Keep a Changelog 规范定版 CHANGELOG.md提交推送创建vversion标签的 draft releaserelease notes 抄录 changelog 对应条目若 CI 未触发按protocol - core - audio - metadata - playback - connect - librespot顺序在各 crate 目录手工执行cargo publish其中protocol需加--no-verify工作流或手工发布成功后将 draft release 正式发布。补充一个环境约束从 rust-toolchain.toml 与根 Cargo.toml 可见 workspace 的 MSRV 为 Rust 1.85、edition 2024cross-compile.yml 也以1.85作为最低工具链参与构建矩阵。任何手工操作环境在准备发布前应先确认所用工具链不低于该版本以保证cargo publish --dry-run预检与 CI 行为一致。总结librespot 的发布体系可以归纳为三条主线预备版本号按变更范围精准升级 changelog 定版 PR 审查、触发以 draft release 的创建事件作为发布闸门、发布workspace 级 dry-run 预检后按protocol → core → audio → metadata → playback → connect → librespot的依赖顺序推送 crates并对含代码生成构建脚本的protocol包以--no-verify跳过验证。整套流程的关键文件分布在 PUBLISHING.md、.github/workflows/prepare-release.yml、.github/workflows/release.yml、.github/scripts/bump-versions.sh 与 CHANGELOG.md可作为多 crate Rust 项目发布自动化的参考实现。【免费下载链接】librespotOpen Source Spotify client library项目地址: https://gitcode.com/GitHub_Trending/li/librespot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考