本文目录导读：
开源项目发布版本是一个标准化的流程,旨在确保代码的稳定性、可追溯性和可维护性，下面是核心步骤和最佳实践：
明确版本号规范（最重要的一步）
绝大多数开源项目遵循 语义化版本控制（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 操作为例）
这是最关键的“打标签”环节，在完成准备工作后：
-
提交版本更新：
git add . git commit -m "chore: release v1.2.3"
-
创建 Git 标签（Tag）： Git 标签是对历史某个提交的永久性标记，使用注解标签（annotated tag）以包含作者和日期信息。
git tag -a v1.2.3 -m "Release version 1.2.3: Add new API and fix critical bug"
-
推送代码和标签：
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。
- Python：
- 文档站点：更新在线文档，确保文档版本与最新发布匹配。
发布后沟通
- 通知社区：在项目的讨论区、邮件列表、Slack/Discord 频道或社交媒体上发布版本公告。
- 记录快照：确保构建的产物可重复（例如锁定依赖版本）。
常见工具推荐
- 自动化发布：
- GitHub Actions / GitLab CI：在推送 Tag 时自动执行构建、测试和发布脚本。
- Release-Please（Google）：自动生成 PR 来更新 CHANGELOG 和版本号。
- 版本管理：
- Bumpversion / Bump2version：自动更新多个文件中的版本号。
| 步骤 | 要点 |
|---|---|
| 版本号 | 严格遵循 SemVer，避免随意改动 API 兼容性。 |
| 文档 | CHANGELOG 必须更新，且面向用户，而非只有内部 Commit 记录。 |
| 标记 | 必须使用 Git Tag，这是代码历史的里程碑。 |
| 自动化 | 利用 CI/CD 自动构建、测试、上传，减少人为错误。 |
| 可重复 | 发布后不可删除或替换同一版本（尤其是 npm/PyPI），如有严重问题，应发布 v1.2.4 紧急修复版。 |
通过遵循这个流程,开源项目的使用者可以清晰地了解更新带来的影响，维护者也能保持项目版本的清晰与可追溯。
