开源项目如何发布版本？

本文目录导读：

1. 明确版本号规范（最重要的一步）
2. 准备工作：冻结代码并更新
3. 正式发布流程（以 Git 操作为例）
4. 发布到包管理器或发布平台
5. 发布后沟通
6. 常见工具推荐

开源项目发布版本是一个标准化的流程,旨在确保代码的稳定性、可追溯性和可维护性，下面是核心步骤和最佳实践：

明确版本号规范（最重要的一步）

绝大多数开源项目遵循 语义化版本控制（Semantic Versioning，简称 SemVer），格式为 主版本号.次版本号.修订号（v1.4.2）。

• 主版本号（Major）：当你做了不兼容的 API 修改。
  • v1.0.0 -> v2.0.0
• 次版本号（Minor）：当你做了向下兼容的功能性新增。
  • v1.0.0 -> v1.1.0
• 修订号（Patch）：当你做了向下兼容的问题修正（Bug Fix）。
  • v1.0.0 -> v1.0.1

贴士：在正式发布前，还可以使用预发布版本标签，如 v2.0.0-alpha.1、v2.0.0-beta.2、v2.0.0-rc.1（Release Candidate）。

准备工作：冻结代码并更新

在标记版本之前,确保 main（或 master）分支处于稳定状态。

• 更新 CHANGELOG.md：使用工具或手动记录本次版本的所有变更，遵循 Keep a Changelog 规范，区分新增（Added）、变更（Changed）、弃用（Deprecated）、移除（Removed）、修复（Fixed）等。
• 更新版本号文件：修改项目中所有写死版本号的地方（package.json、Cargo.toml、__init__.py、VERSION 文件等）。
• 确保 CI/CD 通过：所有自动化测试、lint 检查、构建流程均通过。

正式发布流程（以 Git 操作为例）

这是最关键的“打标签”环节，在完成准备工作后：

1. 提交版本更新：

   git add .
   git commit -m "chore: release v1.2.3"

2. 创建 Git 标签（Tag）： Git 标签是对历史某个提交的永久性标记，使用注解标签（annotated tag）以包含作者和日期信息。

   git tag -a v1.2.3 -m "Release version 1.2.3: Add new API and fix critical bug"

3. 推送代码和标签：

   git push origin main
   git push origin v1.2.3   # 推送单个标签

发布到包管理器或发布平台

根据项目类型,将构建产物上传到对应的平台：

• GitHub/GitLab Releases：
  • 在 GitHub 仓库页面的 “Releases” 板块，基于刚才推送的 Tag 创建一个 Release。
  • 提供下载链接：通常包括源代码（.zip、.tar.gz）和预编译的二进制文件（如果有）。
  • 撰写发布说明：从 CHANGELOG.md 中复制本次版本的概要，重点说明 Breaking Changes 和新功能。
• 包管理器：
  • Python：twine upload dist/* 上传到 PyPI。
  • Node.js：npm publish 上传到 npm registry。
  • Rust：cargo publish 上传到 crates.io。
  • Docker：构建镜像并打上版本标签，推送至 Docker Hub 或 GHCR。
• 文档站点：更新在线文档，确保文档版本与最新发布匹配。

发布后沟通

• 通知社区：在项目的讨论区、邮件列表、Slack/Discord 频道或社交媒体上发布版本公告。
• 记录快照：确保构建的产物可重复（例如锁定依赖版本）。

常见工具推荐

• 自动化发布：
  • GitHub Actions / GitLab CI：在推送 Tag 时自动执行构建、测试和发布脚本。
  • Release-Please（Google）：自动生成 PR 来更新 CHANGELOG 和版本号。
• 版本管理：
  • Bumpversion / Bump2version：自动更新多个文件中的版本号。

通过遵循这个流程,开源项目的使用者可以清晰地了解更新带来的影响，维护者也能保持项目版本的清晰与可追溯。