开源项目的版本发布前检查清单有哪些

本文目录导读：

1. 第一阶段：代码与功能完善 (Code & Feature)
2. 第二阶段：自动化测试与持续集成 (Testing & CI)
3. 第三阶段：文档与元数据 (Documentation & Metadata)
4. 第四阶段：版本控制与发布工程 (Versioning & Build)
5. 第五阶段：最终验证 (Final Verification)
6. 第六阶段：发布执行与沟通 (Release & Communication)
7. 一段关键提醒
8. 附录：常见错误及应对

开源项目发布前的检查清单是确保版本质量、稳定性和用户友好度的关键步骤，虽然不同项目（如库、工具、应用）侧重点不同，但以下是一份通用的核心发布检查清单，你可以根据项目类型进行增删：

第一阶段：代码与功能完善 (Code & Feature)

1. 功能冻结：确认所有计划内的新功能已合并，并明确告知贡献者不再接受新功能 PR（拉取请求），只接受 Bug 修复。
2. API（应用程序接口）稳定性：
   • 如果项目是一个库,确保公共 API 没有意外破坏性变更。
   • 如果有破坏性变更,必须在变更日志（CHANGELOG）和版本号（如主版本号增加）中明确声明。
3. 过时代码处理：检查所有已标记为@deprecated的接口，确定是否可在此版本中移除（需符合预定的弃用周期）。
4. 重大问题修复：确认已关闭目标里程碑（Milestone）中的所有阻塞问题（Blocker/Critical）。

第二阶段：自动化测试与持续集成 (Testing & CI)

5. 所有测试通过：
   • 单元测试：100% 通过。
   • 集成测试：针对不同环境或依赖版本通过。
   • 端到端测试（如有）：通过。
6. 代码覆盖率：确认覆盖率未显著下降（建议制定一个可接受的下限，如下降不超过 1%）。
7. 持续集成（CI）绿标：在目标发布分支上，所有 CI 流水线（如 GitHub Actions、GitLab CI）均显示为绿色通过。

第三阶段：文档与元数据 (Documentation & Metadata)

8. 变更日志（CHANGELOG）：
   • 使用规范格式（如 [Keep a Changelog]()）。
   • 拆分为 Added、Changed、Fixed、Removed 等模块。
   • 清晰标注本次版本的发布日期。
9. 安装与升级指南：确保 README.md、INSTALL.md 等文件中的安装命令和系统要求与当前版本一致，并包含从旧版本升级的步骤（如有）。
10. README 徽章：更新版本徽章、CI 状态徽章等为正确链接。
11. 版权与许可证：确认所有文件头部均包含正确的版权声明和许可证信息。
12. 作者/贡献者名单：确认文件（如 AUTHORS 或 CONTRIBUTORS）已更新，并感谢本次贡献者。

第四阶段：版本控制与发布工程 (Versioning & Build)

13. 版本号确定：遵循[语义化版本控制]()（SemVer），确认版本号（v2.1.0）正确反映了变更范围。
14. 分支管理：
    • 从主干分支（如 main）或 release/ 分支创建发布分支。
    • 确认不会有未发布的代码被意外包含。
15. 构建与打包测试：
    • 本地构建：从零开始构建一次，确保无依赖缺失。
    • 发布到注册表：模拟发布到 PyPI、npm、Docker Hub 等目标注册表（如使用 --dry-run 或在测试仓库中试验）。
    • 签名与哈希：生成安全签名（如 GPG 签名）和文件校验和（如 sha256sum）。
16. 依赖审计：运行类似 npm audit、pip audit 或 cargo audit 等工具，确保无已知严重安全漏洞的依赖项。

第五阶段：最终验证 (Final Verification)

17. 使用全新环境安装：在一个干净的虚拟机、Docker 容器或新的虚拟环境中，按照文档重新安装并运行一个基础示例，确保开箱即用。
18. 发布候选版本（RC）：经验丰富的团队会先打上 -rc1、-rc2 等标签发布候选版，邀请社区在正式版前测试 24-72 小时。
19. 安全审查：快速扫描合并的代码中是否有硬编码的密钥、令牌或私人链接。

第六阶段：发布执行与沟通 (Release & Communication)

20. 创建 Git 标签：在最终提交上创建并推送带签名的标签（如 git tag -s v2.1.0）。
21. 发布发布说明：
    • 在 GitHub/GitLab Releases 页面撰写发布说明，内容与 CHANGELOG 类似，但可包含升级注意事项（Breaking Changes）。
    • 如果适用,附上二进制文件下载链接和校验和。
22. 发送公告：
    • 通过邮件列表（mailing list）。
    • 在项目的讨论组、论坛或 Slack/Discord 频道发布消息。
    • 简短发一条 X（推特）/Mastodon（长毛象）等社交媒体动态。

一段关键提醒

发布后立即向前看： 在完成发布的同时，建议立即在开发分支上执行 bump version 操作，将版本号标记为下一个开发迭代版本（如 v2.2.0-dev），避免后续提交的版本号混淆。

附录：常见错误及应对

• 忘记更新 CHANGELOG → 发布前最后一步必须检查。
• CI 在发布标签后突然失败 → 发布前应在 RC 阶段彻底解决。
• 依赖意外不兼容 → 为 CI 添加-nightly或在不同 Python/node 版本上的测试矩阵。
• Git 标签未推送 → 养成在本地创建标签并git push --tags的习惯。

希望这份清单能帮助你的项目顺利完成版本发布。