Kubo 版本发布清单详解从 RC 到 FINAL 的完整发布流程指南【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo导读KuboGo 实现的 IPFS 节点以大约六周为一个迭代周期持续发布新版本每一次 RCRelease Candidate候选版本与 FINAL正式版本发布都涉及分支管理、GPG 签名打标签、多平台制品发布与社区推广等一整套严谨流程。本文以仓库内的 docs/RELEASE_CHECKLIST.md 为骨架逐阶段拆解 Kubo 发布负责人Lead Maintainer执行发布的标准操作清单并结合 version.go、bin/mkreleaselog、docs/releases.md 等仓库内文件解释每一步背后的工程动机与实现细节。读完本文你将掌握 Kubo 发布从分支准备、打标签、发布制品到发布后收尾的完整可执行方案以及每个环节的注意事项与不可逆操作点。一、发布类型与前置条件1.1 三种发布类型Kubo 的版本号遵循vX.Y.Z(-rcN)格式按发布性质分为三类类型含义典型场景RCRelease Candidate候选版本正式发布前的预览供早期测试者验证如v0.40.0-rc1FINAL正式发布版本经过多阶段测试后面向全网用户的稳定版本如v0.40.0PATCH补丁版本仅修复严重 bug不引入新功能如v0.40.1三类发布在分支策略、制品发布范围与发布后任务上存在显著差异清单中以RC only、FINAL only、non-PATCH等标注逐一区分执行时需严格对照。1.2 环境前置条件开始发布前发布负责人需要确认以下环境就绪GPG 签名本机 git 与 GitHub 账号均需配置 GPG 密钥。Kubo 要求发布相关的 merge commit 与 git tag 全部带发布者的 GPG 签名这是后续安全审计与合并历史可追溯的基础。Dockertag 推送会自动触发 Docker 镜像构建本地需要 Docker 以便验证与排查。npmKubo 以 npm 包形式发布需要 Node.js 工具链。本地克隆 Kubo 仓库所有分支操作与 cherry-pick 都在本地完成。非 PATCH 版本额外要求将 CI 中使用的 Go 版本升级到 go.dev 中声明的go-version即是 CI 编译基准。事实依据当前仓库 version.go 中CurrentVersionNumber 0.44.0-dev这正是主分支master在完成上一轮发布后进入下一开发周期时的典型状态详见下一节。二、阶段一准备发布分支2.1 分支基线策略发布分支的基线选择取决于补丁号 Z新 minor/majorZ0从master创建release-vX.Y.Z分支PATCHZ0从长期维护的release分支创建release-vX.Y.Z。首先拉取最新远端状态git fetch origin master release git checkout -b release-vX.Y.Z # 按上述规则从 master 或 release 切出2.2 RC1 特例为下一个开发周期做准备仅在首个 RC 发布时需要回到master分支完成两件事更新版本号将 version.go 中的CurrentVersionNumber改为vX.Y1.0-dev例如发布 v0.40.0 后master 更新为0.41.0-dev⚠️ 需仔细确认 Y1 计算正确。创建新 changelog 占位新建./docs/changelogs/vX.Y1.md并在 CHANGELOG.md 中登记链接。当前仓库的 CHANGELOG.md 即采用这种每个版本一个 changelog 文件的索引结构。这样做的目的master 分支始终保持下一个版本的开发状态而release-vX.Y.Z分支则锁定本次发布的精确内容。从源码看version.go 中的taggedRelease变量由 Makefile 通过 ldflag 在从带版本 tag 的干净提交构建时注入会使得版本号构建时省略 commit hash因为版本号已经精确标识源码——这正是版本号必须准确无误这一要求的实现支撑。2.3 更新发布分支版本号切回release-vX.Y.Z分支将版本号更新为vX.Y.Z(-rcN)并创建从release-vX.Y.Z到release的草稿 PR。2.4 Cherry-pick 与合并规范若本次发布需要携带 master 上的修复提交使用git cherry-pick -x commit⚠️-x标志是硬性要求它会在新提交中记录原始提交的 SHA保证追溯链完整、合并历史清晰。对 PR 的 CI 检查须全部通过。随后根据发布类型执行不同操作FINAL 专属使用./bin/mkreleaselog的输出仅 stdout切勿复制 stderr替换 PR 中的Changelog与Contributors两节内容FINAL 专属合并 PRrelease-vX.Y.Z→release时必须使用Create a merge commit禁止Squash and merge或Rebase and merge——只有 merge commit 才能保留发布者的 GPG 签名不要删除release-vX.Y.Z分支后续 PATCH 版本与 git 历史追溯都依赖它。2.5 深入bin/mkreleaselog发布日志生成器清单中反复引用的 bin/mkreleaselog 是一个 Bash 脚本负责在FIRST_REF..LAST_REF提交区间内生成带贡献者统计的发布说明其核心机制包括模块范围过滤通过INCLUDE_MODULESgithub.com/ipfs/、github.com/ipld/、github.com/libp2p/、github.com/multiformats/等官方 org以及whyrusleeping、jbenet等核心贡献者的个人模块与EXCLUDE_MODULES如github.com/marten-seemann/qtls两层正则只统计与 Kubo 直接相关的依赖变更。忽略文件go.mod、go.sum、.github、*.pb.go、cbor_gen.go等生成文件与元数据不进入统计。GitHub handle 解析三级策略优先从 GitHub noreply 邮箱userusers.noreply.github.com提取其次从 merge commit 消息Merge pull request #N from user/branch提取最后通过ghCLI 查询 GitHub APIgh pr view/gh api repos/.../commits。结果缓存在~/.cache/mkreleaselog/github-handles.json并过滤掉[bot]账号。依赖变更对比通过go list -json -m all导出新旧依赖集合并做 join 对比输出每个依赖模块的版本变化Path Old → New及对应提交日志。脚本最终输出### Changelog与### ‍‍‍ Contributors两个章节前者按模块归类的提交列表后者生成按代码行数排序的贡献者表格——这与 docs/changelogs/v0.43.md、docs/changelogs/v0.44.md 中Overview / Highlights / Changelog / Contributors的结构完全对应。三、阶段二打标签与发布制品3.1 创建签名标签⚠️ 不可逆点这是整个流程中的 POINT OF NO RETURN不可返回点tag 一旦推送会自动触发 Docker/NPM 的自动发布且无法撤销。首次发布时建议结对编程pair programming并由 release reviewer 逐条核对命令。# RC在 release-vX.Y.Z 分支上 git tag -s vX.Y.Z-rcN -m Prerelease X.Y.Z-rcN # FINALPR 合并后在 release 分支上 git tag -s vX.Y.Z -m Release X.Y.Z-s表示使用 GPG 签名。打标签后必须验证git show vX.Y.Z(-rcN) # 验证 tag 已签名且内容正确 git push origin vX.Y.Z(-rcN)⚠️禁止使用git push --tags——它会推送所有本地 tag污染远端仓库。推送后需停下等待 Docker 构建完成再继续。3.2 制品发布的依赖关系清单用依赖图明确了各制品的先后关系tag 推送 ├──→ Docker 镜像构建独立可与 dist 并行 └──→ dist.ipfs.tech 发布独立可与 Docker 并行 ├──→ NPM 包发布依赖 dist 完成 └──→ GitHub Release依赖 dist 完成Docker确认 docker-image CI 通过镜像在 Docker Hub 的ipfs/kubotags 下可见。dist.ipfs.tech检出ipfs/distributions仓库创建分支release-kubo-X.Y.Z(-rcN)核对.tool-versions中的 golang 版本与 Kubo CI 的go-version一致然后执行./dist.sh add-version kubo vX.Y.Z(-rcN)合并 PR 会更新dists/kubo/versionsFINAL 同时更新dists/kubo/current随后等待 CI 工作流完成并在 dist.ipfs.tech 上核验发布结果。NPM如未自动触发手动调度npm-kubo仓库的Release to npm工作流并在 npm 的kubo包版本列表中确认。GitHub Release使用 tagvX.Y.Z(-rcN)创建 Release链接到本次发布 issueRC链接 changelog勾选This is a pre-releaseFINAL粘贴 changelog 正文不含头部不勾选 pre-release。随后运行 sync-release-assets 工作流依赖 dist.ipfs.tech 产物并核验资产已附加到 GitHub Release。四、阶段三发布后任务4.1 技术收尾FINAL 专属合并release→master。规范流程是从release创建merge-release-vX.Y.Z分支先将master合并进该分支解决 version.go 中的冲突——保留 master 的-dev版本号丢弃 release 的版本号对应清单中keep the -dev version from master的要求从merge-release-vX.Y.Z到master创建并合并 PR仍须使用Create a merge commit——只有这样才能保留提交历史与何时何地合并了什么的审计轨迹。基础设施升级更新ipshipyard/waterworks-infra仓库——RC 时在 Kubo 预发布环境对当前 RC 做回归测试FINAL 时在全部节点升级到最新发布版并同步升级 collab cluster 节点与 libp2p bootstrappers。下游项目联动ipfs-desktop创建 PR 更新package.json与package-lock.json中的 kubo 版本配合 IPFS Companion 浏览器扩展做冒烟测试FINAL 后合并并发布新版本docs.ipfs.techFINAL 专属运行ipfs-docs仓库的update-on-new-ipfs-tag.yml工作流并合并 PR让官方文档与最新版本保持同步。4.2 社区宣传Promotion发布完成后需要在社区渠道同步信息在 IPFS Discourse 创建话题标题为Kubo vX.Y.Z(-rcN) is out!tag 为kubo正文用标题作为##一级标题并包含GitHub Release 链接、IPNS 二进制、docker pull 命令与发布说明最后将话题全局置顶无 banner 时创建 banner确认 bot 在 Discord#ipfs-chatter或 Matrix#ipfs-chatter:ipfs.io发布了通知RC 专属在发布 issue 中评论并 早期测试者对应仓库中的 docs/EARLY_TESTERS.md 早期测试者计划FINAL 专属在发布 issue 中评论链接并在 blog.ipfs.tech 创建博客条目non-PATCH 版本可选在社交媒体发布公告。4.3 依赖更新与收尾FINAL non-PATCH 专属创建依赖更新 PR审查根目录 go.mod 的直接依赖——⚠️禁止运行go get -u因为它会连带升级间接依赖可能引入隐患运行make mod_tidy整理模块创建仅含go.mod/ go.sum 更新的 PR并加入下一个发布版本的 milestone。最后FINAL non-PATCH创建下一个版本的发布 issue基于 docs/RELEASE_ISSUE_TEMPLATE.md 模板FINAL关闭当前发布 issue。五、发布 issue 模板与发布节奏5.1 发布 issue 的启动按照 docs/RELEASE_ISSUE_TEMPLATE.md创建发布 issue 时需完成填写 Meta 部分、指派发布负责人与 reviewer、命名 issue 为 Release vX.Y.Z、设定 X.Y.Z 的具体值并置顶 issue。Meta 区记录发布负责人、reviewer、预期 RC 日期、最终发布日期、发布 PR 链接与 changelog 地址。模板强调每个 pre-release 与 final release 都应将 docs/RELEASE_CHECKLIST.md 复制为一条新评论并把标题替换为正确版本号每个 RC / FINAL 对应独立评论从而清晰记录各阶段已完成步骤。5.2 六周发布节奏与五阶段流程docs/releases.md 补充了清单背后的节奏设计发布哲学约每六周发布一次期间经历 4 个测试阶段——Stage 0 自动化测试unit/interop/integration 全部通过、Stage 1 内部测试部署到自建基础设施并配合 IPFS Desktop/WebUI 等应用验证、Stage 2 社区开发环境测试邀请 beta 测试者、Stage 3 社区生产测试早期测试者在生产环境部署、Stage 4 正式发布。发布周期完整流程约 3 周每个阶段约 1 周每 6 周启动新一轮除非上一轮仍在进行。PATCH 发布压缩周期 2-3 天自动化与内部测试压缩到数小时跳过 Stage 2社区生产测试缩短为 1-2 天可选测试。安全修复策略除非漏洞正在被野外利用否则安全修复不会在发布说明中特别标注FINAL 发布后约 2 周才会公布已修复的安全问题安全修复一般不回移植到旧版本因此始终建议尽快升级到最新版。这与清单中 RC/FINAL/PATCH 的差异化操作一一呼应例如 PATCH 不需要升级 CI Go 版本、不需要创建下个 changelog 占位等。六、常见陷阱与最佳实践汇总综合清单与源码发布执行中最容易出错、需要格外小心的点包括环节硬性要求违反后果cherry-pick必须加-x丢失原始提交 SHA追溯链断裂合并 release PR仅Create a merge commit丢失 GPG 签名审计历史不完整推送 tag仅推送单个 tag禁--tags污染远端 tag 列表触发意外发布保留发布分支不删除release-vX.Y.Z无法进行后续 PATCH 发布version.go 冲突保留 master 的-dev版本主分支版本号错误污染下一周期依赖更新禁go get -u用make mod_tidy间接依赖失控升级mkreleaselog只取 stdoutstderr 中的进度信息污染 changelog结语Kubo 的发布流程是一套将分支策略、签名验证、CI/CD 自动化与社区协作紧密结合的成熟工程实践。清单 docs/RELEASE_CHECKLIST.md 表面上是逐项打勾的操作列表实则编码了 Kubo 团队对发布质量与审计可追溯性的全部要求bin/mkreleaselog 这样的自动化工具进一步降低了人为误差。对于希望复刻类似发布流程的 Go 项目这份清单在版本分支模型、GPG 签名合并、多制品发布编排与发布后依赖治理方面都是极具参考价值的范本。【免费下载链接】kuboIPFS implementation in Go: a daemon that stores and serves content-addressed data, with a CLI, HTTP Gateway, and RPC API项目地址: https://gitcode.com/GitHub_Trending/ku/kubo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考