尧图网站建设 
fd 发布工程全流程解析从版本号升级到多平台产物发布的 Release Checklist【免费下载链接】fdA simple, fast and user-friendly alternative to find项目地址: https://gitcode.com/GitHub_Trending/fd/fd本文以 fdA simple, fast and user-friendly alternative tofind仓库中的 发布检查清单 为主体完整还原一个 Rust CLI 项目从“改版本号”到“发布多平台二进制产物与 crates.io 包”的标准化发布流程并结合 版本升级脚本、帮助文本更新脚本、Debian 打包脚本 与 CICD 工作流 的源码实现说明每一步检查项背后的自动化支撑。读完后你将掌握如何为 fd 这类项目执行一次完整、可复核的版本发布以及如何设计自己的项目发布清单。一、检查清单的定位既可照做也可粘贴进 PRdoc/release-checklist.md 开篇即说明它的两种用法This file can be used as-is, or copied into the GitHub PR description which includes necessary changes for the upcoming release.即既可以作为本地操作手册逐步勾选也可以把整份清单复制进承载本次发布变更的 PR 描述中让评审者对照逐项检查。整个清单分为四个阶段Version bump版本升级→ Pre-release checks and updates发布前检查→ Release正式发布→ Post-release发布后收尾。下面按原文档的章节顺序逐一展开并在每节补充仓库中可验证的脚本与 CI 实现。二、Version bump版本号升级的五项检查2.1 清单原文的五项内容原文档规定版本升级阶段包含以下检查项可整体由scripts/version-bump.sh完成为本次发布所需的全部变更创建一个新分支更新 Cargo.toml 中的版本号并运行cargo build同步更新Cargo.lock注意把Cargo.lock的变更一并git add通过grep rust-version Cargo.toml查出当前最低支持的 Rust 版本MSRV更新README.md中fd的版本号与最低 Rust 版本说明更新 CHANGELOG.md把Upcoming release章节的标题改为本次发布的版本号。2.2 自动化实现scripts/version-bump.shscripts/version-bump.sh 是清单 “Version bump” 一节的一键实现脚本头部注释即写明# This script automates the Version bump section。逐行拆解其逻辑version$1 # 新版本号作为第一个参数传入缺失则报错退出 git switch -C release-$version # 创建并切换到 release-X.Y.Z 分支对应检查项 1 sed -i -e 0,/^\[badges/{s/^version .*/version \$version\/} Cargo.toml # 仅替换 [badges] 段落之前即 [package] 段内的 version 行 # 避免误伤文件中其他位置的同名行 msrv$(grep -F rust-version Cargo.toml | sed -e s/^rust-version \(.*\)/\1/) # 从 Cargo.toml 提取 MSRV对应检查项 3 的 grep 步骤 sed -i -e s/Note that rust version \*[0-9.]\* or later/Note that rust version *$msrv* or later/ README.md # 同步 README 中的最低 Rust 版本说明对应检查项 4 sed -i -e s/^# Upcoming release/# $version/ CHANGELOG.md # 把 CHANGELOG 的 # Upcoming release 标题改为 # X.Y.Z对应检查项 5两个实现细节值得注意对Cargo.toml的替换使用了0,/^\[badges/限定“从文件头到[badges]段之间”的范围确保只改[package]段的version字段。当前仓库 Cargo.toml 中该字段为version 10.5.0同时声明了rust-version 1.90.0与edition 2024脚本只负责改版本号并不执行cargo build所以清单中“运行cargo build更新Cargo.lock并git add”仍需人工执行——Cargo.lock中fd-find包的版本条目当前为version 10.5.0必须与Cargo.toml一致否则后续 CI 的--locked构建会直接失败。三、Pre-release checks and updates发布前检查3.1 清单原文的六项检查安装最新版并验证运行cargo install --locked -f --path .确认fd --version输出新版本号且在PATH中可用。--locked保证按Cargo.lock精确依赖构建-f允许覆盖同名旧二进制人工审阅帮助与手册检查-h、--help的输出以及 man 页源文件为 doc/fd.1同步 README 命令行选项运行fd -h并将其输出复制进 README.md 的Command-line options章节可直接执行gawk -i inplace -f scripts/update-help.awk README.md推送变更并等待 CI 通过明确提示CI 绿了才能进入下一阶段可选项按 CHANGELOG.md 的说明手动测试新特性与新命令行选项干跑发布运行cargo publish --dry-run提前暴露 crates.io 发布问题文档在仓库中不完整、license 文件缺失等。3.2 update-help.awkREADME 帮助块的自动再生scripts/update-help.awk 是一个gawk脚本核心状态机只有两个标志位/Command-line options/命中后inSection1表示已定位到 README 的### Command-line options章节进入该章节后遇到第一个围栏时inBlock1、inSection0再遇到围栏时即代码块结尾执行cargo run --release --quiet -- -h丢弃输出中Usage行之前的所有内容把从Usage: fd [OPTIONS] [pattern [path]...]开始的真实帮助文本逐行写入替换原代码块内容任何命令执行失败都会向 stderr 打印failed to generate help output并以状态码 1 退出避免生成残缺文档。配合gawk -i inplaceGNU awk 的原地修改模式即可做到“README 中的选项列表永远与二进制实际输出一致”。对照当前 README.mdCommand-line options章节正是以 “This is the output offd -h” 开头随后跟着一段Usage: fd [OPTIONS] ...的帮助文本代码块——与 awk 脚本的生成/替换逻辑一一对应。3.3 “等待 CI 成功”到底在等什么.github/workflows/CICD.yml 定义了清单第 4 项所依赖的全部 CI 检查ensure_cargo_fmtcargo fmt -- --check校验格式仓库根目录有 rustfmt.toml 配置lint_checkcargo clippy --all-targets --all-features -- -Dwarnings警告即失败min_version安装crate_metadatajob 从Cargo.toml提取的 MSRV 工具链当前为 1.90.0在最低 Rust 版本上运行 clippy 与cargo test --locked防止使用新版本才有的 APIbuild13 个 target 的构建矩阵Linux gnu/musl 的 x86_64/i686/aarch64/arm、macOS 双架构、Windows msvc/gnu 双架构等Linux 目标通过cross容器交叉编译各 target 均执行--locked --release构建与测试。发布分支推上去后以上检查全部通过才满足清单中 “wait for CI to succeed (before continuing with the next section)” 的前置条件。四、Release标签触发 GitHub Release crates.io4.1 清单原文的四步操作合并发布分支明确要求应为 fast-forward merge发布分支基于 master 创建、期间 master 无新提交时打标签并推送git tag vX.Y.Z; git push origin tag vX.Y.Z这会触发基于 tag 的部署流程清单特别提醒——如果你的origin是 fork要改推到upstream在仓库的 Releases 页面创建 Release选择新标签、以标签名作为标题Release notes 直接复制 CHANGELOG.md 对应版本的小节并可追加面向包维护者的补充说明然后发布验证二进制部署产物归档archive与 Debian 包应出现在针对 Git tag 的那次 CI 运行结束后生成的 Release 附件中发布到 crates.io在干净的仓库中运行cargo publish例如重新 clone 一份再执行保证打包内容不受本地工作区污染。4.2 标签如何驱动产物发布.github/workflows/CICD.yml 的触发条件包含tags: *因此推送vX.Y.Z标签会再次运行整个矩阵。与 PR/分支运行相比tag 运行的差异点在于每个 build job 末尾的Check for release步骤用正则^refs/tags/v[0-9].*判定本次是否为 tag 触发是则置IS_RELEASEtrue仅当IS_RELEASEtrue时actions/attest对 tarball 与 deb 产物做供应链溯源证明attestation随后softprops/action-gh-release把PKG_PATH如fd-v10.5.0-x86_64-unknown-linux-gnu.tar.gz与DPKG_PATH上传为 Release 附件另有一个wingetjob仅在refs/tags/v前缀时运行用installers-regex: -pc-windows-msvc\.zip$挑选 MSVC 版 Windows 压缩包提交到 Winget。产物命名来自 build job 的Create tarball步骤PKG_BASENAME${name}-v${version}-${target}Linux 为.tar.gz、Windows 为.zip归档内容包含二进制、README、两份 LICENSE、CHANGELOG、man 页doc/fd.1与补全文件目录。Cargo.toml 中的[package.metadata.binstall]段pkg-url { repo }/releases/download/v{ version }/{ name}-v{ version }-{ target }.{ archive-format }恰好描述了这套产物在 GitHub Release 中的固定 URL 结构cargo binstall正是按此模式下载发布包。4.3 Debian 包scripts/create-deb.sh 的产物细节清单中“archives and Debian packages should appear” 的 deb 包由 CI 调用 scripts/create-deb.sh 生成仅 Ubuntu runner 上的 Linux target。脚本的关键行为musl 与普通变体区分target 含musl时包名为fd-musl且Conflicts: fd, fd-find普通 glibc 包名fdConflicts: fd-musl, fd-find避免与 musl 静态包互相覆盖架构映射x86_64→amd64、i686→i386 系、aarch64→arm64、arm-hf→armhf其余 target 直接报错终止DPKG_ARCHnotset包内容二进制装入usr/bin/fddoc/fd.1 压缩为usr/share/man/man1/fd.1.gz安装 bash/fish/zsh 三类补全附带 README、双许可证与 gzip 压缩的 changelog并创建usr/bin/fdfind符号链接及fdfind补全保证 Debian 包用户可用fdfind别名与 Cargo.toml 中包名fd-find保持一致规避与发行版已有fd包冲突版本号默认取cargo metadata输出的包版本最终用fakeroot dpkg-deb --build构建若检测到GITHUB_OUTPUT则把DPKG_NAME/DPKG_PATH写回 step outputs 供 CI 上传。4.4 为什么 crates.io 要在“干净仓库”里发布清单特意强调 clean repository原因是cargo publish会把工作区文件打进 crate 包本地构建产物target/、未提交改动、编辑器临时文件都会被裹入。重新 clone 一份再执行等价于验证“发布物 标签源码”与 tag 触发的 CI 构建形成交叉校验。第 3 节的cargo publish --dry-run则是把这类问题提前到合并前暴露。五、Post-release为下一个版本铺路发布完成后清单要求立刻在 CHANGELOG.md 顶部重建Upcoming release骨架模板固定为四个小节# Upcoming release ## Features ## Bugfixes ## Changes ## Other对照当前 CHANGELOG.md 的实际内容可以验证这一约定文件以# Upcoming Release开头且 Features/Bugfixes 下仅有占位符-其下依次是# 10.5.0、# 10.4.2、# 10.4.1… 各版本小节。值得注意的是scripts/version-bump.sh的 sed 规则s/^# Upcoming release/# $version/与这里要求的首行标题存在大小写差异releasevsRelease实操中若沿用带大写 R 的标题该行的版本化需要人工补一刀——这正是把清单放进 PR 描述、由评审者人工复核的价值所在。六、流程总览一次 fd 发布的完整链路把四个阶段串起来fd 的一次发布在仓库层面表现为release-X.Y.Z分支scripts/version-bump.sh X.Y.Z改Cargo.toml/README.md/CHANGELOG.md人工cargo build同步Cargo.lock并暂存本地验证cargo install --locked -f --path .→fd --version、审阅fd --help与 doc/fd.1 →gawk -i inplace -f scripts/update-help.awk README.md→ 推送并等待 CICD 矩阵全绿 →cargo publish --dry-run合并fast-forward→ 推送vX.Y.Z标签 → 在 Releases 页面以 CHANGELOG 小节为 notes 创建 Release → 确认 tag 运行产出的 archives/deb 附件与 attestation干净 clone 中cargo publish上 crates.io在 CHANGELOG.md 顶部重置# Upcoming release四段骨架迎接下一个开发周期。这套清单体现了 Rust CLI 项目的典型发布工程实践版本元数据单点化一切版本号以Cargo.toml为源CI 的crate_metadatajob 直接从中提取 version/msrv、文档即产物README 帮助块由脚本从二进制输出再生man 页随包分发、发布即回归tag 触发全矩阵 CI 重新验证后才挂载附件以及清单即协作界面复制进 PR 让每次发布可逐项复核。对于其他 Rust CLI 项目这四类做法都可以直接参照 doc/release-checklist.md 的骨架移植。【免费下载链接】fdA simple, fast and user-friendly alternative to find项目地址: https://gitcode.com/GitHub_Trending/fd/fd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 fd 发布工程全流程解析：从版本号升级到多平台产物发布的 Release Checklist
fd 发布工程全流程解析从版本号升级到多平台产物发布的 Release Checklist【免费下载链接】fdA simple, fast and user-friendly alternative to find项目地址: https://gitcode.com/GitHub_Trending/fd/fd本文以 fdA simple, fast and user-friendly alternative tofind仓库中的 发布检查清单 为主体完整还原一个 Rust CLI 项目从“改版本号”到“发布多平台二进制产物与 crates.io 包”的标准化发布流程并结合 版本升级脚本、帮助文本更新脚本、Debian 打包脚本 与 CICD 工作流 的源码实现说明每一步检查项背后的自动化支撑。读完后你将掌握如何为 fd 这类项目执行一次完整、可复核的版本发布以及如何设计自己的项目发布清单。一、检查清单的定位既可照做也可粘贴进 PRdoc/release-checklist.md 开篇即说明它的两种用法This file can be used as-is, or copied into the GitHub PR description which includes necessary changes for the upcoming release.即既可以作为本地操作手册逐步勾选也可以把整份清单复制进承载本次发布变更的 PR 描述中让评审者对照逐项检查。整个清单分为四个阶段Version bump版本升级→ Pre-release checks and updates发布前检查→ Release正式发布→ Post-release发布后收尾。下面按原文档的章节顺序逐一展开并在每节补充仓库中可验证的脚本与 CI 实现。二、Version bump版本号升级的五项检查2.1 清单原文的五项内容原文档规定版本升级阶段包含以下检查项可整体由scripts/version-bump.sh完成为本次发布所需的全部变更创建一个新分支更新 Cargo.toml 中的版本号并运行cargo build同步更新Cargo.lock注意把Cargo.lock的变更一并git add通过grep rust-version Cargo.toml查出当前最低支持的 Rust 版本MSRV更新README.md中fd的版本号与最低 Rust 版本说明更新 CHANGELOG.md把Upcoming release章节的标题改为本次发布的版本号。2.2 自动化实现scripts/version-bump.shscripts/version-bump.sh 是清单 “Version bump” 一节的一键实现脚本头部注释即写明# This script automates the Version bump section。逐行拆解其逻辑version$1 # 新版本号作为第一个参数传入缺失则报错退出 git switch -C release-$version # 创建并切换到 release-X.Y.Z 分支对应检查项 1 sed -i -e 0,/^\[badges/{s/^version .*/version \$version\/} Cargo.toml # 仅替换 [badges] 段落之前即 [package] 段内的 version 行 # 避免误伤文件中其他位置的同名行 msrv$(grep -F rust-version Cargo.toml | sed -e s/^rust-version \(.*\)/\1/) # 从 Cargo.toml 提取 MSRV对应检查项 3 的 grep 步骤 sed -i -e s/Note that rust version \*[0-9.]\* or later/Note that rust version *$msrv* or later/ README.md # 同步 README 中的最低 Rust 版本说明对应检查项 4 sed -i -e s/^# Upcoming release/# $version/ CHANGELOG.md # 把 CHANGELOG 的 # Upcoming release 标题改为 # X.Y.Z对应检查项 5两个实现细节值得注意对Cargo.toml的替换使用了0,/^\[badges/限定“从文件头到[badges]段之间”的范围确保只改[package]段的version字段。当前仓库 Cargo.toml 中该字段为version 10.5.0同时声明了rust-version 1.90.0与edition 2024脚本只负责改版本号并不执行cargo build所以清单中“运行cargo build更新Cargo.lock并git add”仍需人工执行——Cargo.lock中fd-find包的版本条目当前为version 10.5.0必须与Cargo.toml一致否则后续 CI 的--locked构建会直接失败。三、Pre-release checks and updates发布前检查3.1 清单原文的六项检查安装最新版并验证运行cargo install --locked -f --path .确认fd --version输出新版本号且在PATH中可用。--locked保证按Cargo.lock精确依赖构建-f允许覆盖同名旧二进制人工审阅帮助与手册检查-h、--help的输出以及 man 页源文件为 doc/fd.1同步 README 命令行选项运行fd -h并将其输出复制进 README.md 的Command-line options章节可直接执行gawk -i inplace -f scripts/update-help.awk README.md推送变更并等待 CI 通过明确提示CI 绿了才能进入下一阶段可选项按 CHANGELOG.md 的说明手动测试新特性与新命令行选项干跑发布运行cargo publish --dry-run提前暴露 crates.io 发布问题文档在仓库中不完整、license 文件缺失等。3.2 update-help.awkREADME 帮助块的自动再生scripts/update-help.awk 是一个gawk脚本核心状态机只有两个标志位/Command-line options/命中后inSection1表示已定位到 README 的### Command-line options章节进入该章节后遇到第一个围栏时inBlock1、inSection0再遇到围栏时即代码块结尾执行cargo run --release --quiet -- -h丢弃输出中Usage行之前的所有内容把从Usage: fd [OPTIONS] [pattern [path]...]开始的真实帮助文本逐行写入替换原代码块内容任何命令执行失败都会向 stderr 打印failed to generate help output并以状态码 1 退出避免生成残缺文档。配合gawk -i inplaceGNU awk 的原地修改模式即可做到“README 中的选项列表永远与二进制实际输出一致”。对照当前 README.mdCommand-line options章节正是以 “This is the output offd -h” 开头随后跟着一段Usage: fd [OPTIONS] ...的帮助文本代码块——与 awk 脚本的生成/替换逻辑一一对应。3.3 “等待 CI 成功”到底在等什么.github/workflows/CICD.yml 定义了清单第 4 项所依赖的全部 CI 检查ensure_cargo_fmtcargo fmt -- --check校验格式仓库根目录有 rustfmt.toml 配置lint_checkcargo clippy --all-targets --all-features -- -Dwarnings警告即失败min_version安装crate_metadatajob 从Cargo.toml提取的 MSRV 工具链当前为 1.90.0在最低 Rust 版本上运行 clippy 与cargo test --locked防止使用新版本才有的 APIbuild13 个 target 的构建矩阵Linux gnu/musl 的 x86_64/i686/aarch64/arm、macOS 双架构、Windows msvc/gnu 双架构等Linux 目标通过cross容器交叉编译各 target 均执行--locked --release构建与测试。发布分支推上去后以上检查全部通过才满足清单中 “wait for CI to succeed (before continuing with the next section)” 的前置条件。四、Release标签触发 GitHub Release crates.io4.1 清单原文的四步操作合并发布分支明确要求应为 fast-forward merge发布分支基于 master 创建、期间 master 无新提交时打标签并推送git tag vX.Y.Z; git push origin tag vX.Y.Z这会触发基于 tag 的部署流程清单特别提醒——如果你的origin是 fork要改推到upstream在仓库的 Releases 页面创建 Release选择新标签、以标签名作为标题Release notes 直接复制 CHANGELOG.md 对应版本的小节并可追加面向包维护者的补充说明然后发布验证二进制部署产物归档archive与 Debian 包应出现在针对 Git tag 的那次 CI 运行结束后生成的 Release 附件中发布到 crates.io在干净的仓库中运行cargo publish例如重新 clone 一份再执行保证打包内容不受本地工作区污染。4.2 标签如何驱动产物发布.github/workflows/CICD.yml 的触发条件包含tags: *因此推送vX.Y.Z标签会再次运行整个矩阵。与 PR/分支运行相比tag 运行的差异点在于每个 build job 末尾的Check for release步骤用正则^refs/tags/v[0-9].*判定本次是否为 tag 触发是则置IS_RELEASEtrue仅当IS_RELEASEtrue时actions/attest对 tarball 与 deb 产物做供应链溯源证明attestation随后softprops/action-gh-release把PKG_PATH如fd-v10.5.0-x86_64-unknown-linux-gnu.tar.gz与DPKG_PATH上传为 Release 附件另有一个wingetjob仅在refs/tags/v前缀时运行用installers-regex: -pc-windows-msvc\.zip$挑选 MSVC 版 Windows 压缩包提交到 Winget。产物命名来自 build job 的Create tarball步骤PKG_BASENAME${name}-v${version}-${target}Linux 为.tar.gz、Windows 为.zip归档内容包含二进制、README、两份 LICENSE、CHANGELOG、man 页doc/fd.1与补全文件目录。Cargo.toml 中的[package.metadata.binstall]段pkg-url { repo }/releases/download/v{ version }/{ name}-v{ version }-{ target }.{ archive-format }恰好描述了这套产物在 GitHub Release 中的固定 URL 结构cargo binstall正是按此模式下载发布包。4.3 Debian 包scripts/create-deb.sh 的产物细节清单中“archives and Debian packages should appear” 的 deb 包由 CI 调用 scripts/create-deb.sh 生成仅 Ubuntu runner 上的 Linux target。脚本的关键行为musl 与普通变体区分target 含musl时包名为fd-musl且Conflicts: fd, fd-find普通 glibc 包名fdConflicts: fd-musl, fd-find避免与 musl 静态包互相覆盖架构映射x86_64→amd64、i686→i386 系、aarch64→arm64、arm-hf→armhf其余 target 直接报错终止DPKG_ARCHnotset包内容二进制装入usr/bin/fddoc/fd.1 压缩为usr/share/man/man1/fd.1.gz安装 bash/fish/zsh 三类补全附带 README、双许可证与 gzip 压缩的 changelog并创建usr/bin/fdfind符号链接及fdfind补全保证 Debian 包用户可用fdfind别名与 Cargo.toml 中包名fd-find保持一致规避与发行版已有fd包冲突版本号默认取cargo metadata输出的包版本最终用fakeroot dpkg-deb --build构建若检测到GITHUB_OUTPUT则把DPKG_NAME/DPKG_PATH写回 step outputs 供 CI 上传。4.4 为什么 crates.io 要在“干净仓库”里发布清单特意强调 clean repository原因是cargo publish会把工作区文件打进 crate 包本地构建产物target/、未提交改动、编辑器临时文件都会被裹入。重新 clone 一份再执行等价于验证“发布物 标签源码”与 tag 触发的 CI 构建形成交叉校验。第 3 节的cargo publish --dry-run则是把这类问题提前到合并前暴露。五、Post-release为下一个版本铺路发布完成后清单要求立刻在 CHANGELOG.md 顶部重建Upcoming release骨架模板固定为四个小节# Upcoming release ## Features ## Bugfixes ## Changes ## Other对照当前 CHANGELOG.md 的实际内容可以验证这一约定文件以# Upcoming Release开头且 Features/Bugfixes 下仅有占位符-其下依次是# 10.5.0、# 10.4.2、# 10.4.1… 各版本小节。值得注意的是scripts/version-bump.sh的 sed 规则s/^# Upcoming release/# $version/与这里要求的首行标题存在大小写差异releasevsRelease实操中若沿用带大写 R 的标题该行的版本化需要人工补一刀——这正是把清单放进 PR 描述、由评审者人工复核的价值所在。六、流程总览一次 fd 发布的完整链路把四个阶段串起来fd 的一次发布在仓库层面表现为release-X.Y.Z分支scripts/version-bump.sh X.Y.Z改Cargo.toml/README.md/CHANGELOG.md人工cargo build同步Cargo.lock并暂存本地验证cargo install --locked -f --path .→fd --version、审阅fd --help与 doc/fd.1 →gawk -i inplace -f scripts/update-help.awk README.md→ 推送并等待 CICD 矩阵全绿 →cargo publish --dry-run合并fast-forward→ 推送vX.Y.Z标签 → 在 Releases 页面以 CHANGELOG 小节为 notes 创建 Release → 确认 tag 运行产出的 archives/deb 附件与 attestation干净 clone 中cargo publish上 crates.io在 CHANGELOG.md 顶部重置# Upcoming release四段骨架迎接下一个开发周期。这套清单体现了 Rust CLI 项目的典型发布工程实践版本元数据单点化一切版本号以Cargo.toml为源CI 的crate_metadatajob 直接从中提取 version/msrv、文档即产物README 帮助块由脚本从二进制输出再生man 页随包分发、发布即回归tag 触发全矩阵 CI 重新验证后才挂载附件以及清单即协作界面复制进 PR 让每次发布可逐项复核。对于其他 Rust CLI 项目这四类做法都可以直接参照 doc/release-checklist.md 的骨架移植。【免费下载链接】fdA simple, fast and user-friendly alternative to find项目地址: https://gitcode.com/GitHub_Trending/fd/fd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考