Git篇：开源项目的维护更新日志规范学习

起因

维护工程项目模块的时候，有时候会进行新功能的开发，有些时候会进行代码优化，对于分支的开发可以使用类似feat_xxx形式，修复分支类似hotfix_xxx形式来根据特定的号来进行记录。

还是缺少一部分的比如特定版本的功能更新维护，以及有一张比较清晰的更新清单。

例如如下，下面是github的一个tag记录列表：

一、更新日志编写规范

1.1、权威参考

语义化版本规范：semver.org/lang/zh-CN/

完整定义了 X.Y.Z 的递增规则
预发布版本和构建元数据的格式说明

Keep a Changelog：keepachangelog.com/zh-CN/

更新日志的编写规范
与语义化版本配合的最佳实践

1.2、核心编写规范

标准步骤：

文件名和位置：在项目根目录下创建 CHANGELOG.md 文件。
时间倒序：最新的版本永远放在最上面。
版本与日期：每个版本号旁都应附带发布日期，格式如 [v1.0.0] - 2023-10-27。
分类整理：将每个版本的改动按类型分组，常见类型如下表：

类型	说明
Added	新增的功能。
Changed	对现有功能的变更。
Deprecated	即将移除的功能，建议不再使用。
Removed	已移除的功能。
Fixed	修复的 bug。
Security	修复了安全漏洞。

1.3、标准模板示范

CHANGELOG.md内容：

# Changelog

所有对本项目的重要更改都将记录在此文件中。

本日志格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
并且项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]
### Added
- 新功能说明（待发布）
### Changed
- 功能变更说明（待发布）
### Fixed
- Bug修复说明（待发布）

## [v1.0.0] - 2023-10-27
### Added
- 项目的初始版本功能
- 用户认证系统
- API 文档

### Fixed
- 修复了数据加载时的内存泄漏问题

## [v0.1.0] - 2023-01-01
- 项目测试版本

注意点

为"人"写日志：更新日志是给人看的，不是机器的提交记录。避免直接粘贴 Git commit 信息，要用清晰的语言说明改动的影响和意义，而不是技术细节。

关联 Issue：在条目后附上相关的 Issue 编号或 PR 链接，方便追溯讨论过程，例如 - 修复了登录超时问题 [#123]。

记录"未发布"改动：在 [Unreleased] 标题下记录已合并但尚未正式发布的改动。当你发布新版本时，只需将 [Unreleased] 改为新版本号和日期，再创建一个新的空的 [Unreleased] 部分即可

二、自动化工具

对于大型项目，手动维护可能比较繁琐，可以考虑使用自动化工具来辅助：

GitLab CI / GitHub Actions：可以配置CI，根据提交信息自动生成更新日志。

三、创建Tags标签

3.1、介绍下Tag版本号

vx.x.x 这样的版本号，必须通过创建对应的 Git 标签（Tag）并推送到远程仓库，才算是一个完整的、可被他人使用的正式版本。

简单来说，版本号是给人看的“名字”，而 Git 标签就是给这个“名字”在代码历史中做一个永久的标记。只有把标签推送到 GitHub、GitLab 这样的远程仓库，协作者或用户才能看到、下载和使用你的这个特定版本。

**使用场景：**在公司内部通常给客户进行出包的时候，就会进行出一个tag，依次逐步递增，后续进行追溯以及看bug问题，我们会直接去切换对应的tag来进行定位以及后续排查，针对特定客户出现异常问题，临时修复，我们会直接基于这个tag来进行出一个hotfix_vx.x.x_xxx的来进行构建。

3.2、如何进行创建并推送标签？

整个过程分为两步，推荐使用能记录元数据的附注标签。

第1步：在本地创建标签

使用 -a 参数创建附注标签，并用 -m 附上说明信息：

# 为当前最新的提交创建附注标签
git tag -a v1.0.0 -m "Release version 1.0.0: 新增用户认证功能"

如果你需要为历史某次提交打标签，只需在命令末尾加上对应的 Commit ID 即可。

第2步：推送标签到远程仓库

标签创建后只存在于你的本地上，必须显式推送到远程仓库：

# 推送单个标签到远程（最常用）
git push origin v1.0.0

# 或者一次性推送所有本地还未推送的标签
git push origin --tags

特别建议：为了确保流程的严谨和可追溯，最佳实践是先更新 CHANGELOG.md 并提交，然后再创建和推送标签。

3.3、避坑指南

切勿在标签上再提交代码：标签一旦创建，就应该指向一个固定的、不可变的提交。不要在创建标签后，又向这个标签指向的代码提交修改。

删除标签要谨慎：

删除本地标签：git tag -d v1.0.0
删除远程标签：先执行上述命令删除本地标签，再执行 git push origin --delete v1.0.0

标签 vs. Release：标签是 Git 的概念，而 Release（发布）是 GitHub/GitLab 等平台在标签之上的一个增强功能，可以附带更详细的说明、二进制文件等。如果你想让版本信息更丰富，可以基于标签创建一个 Release。

四、一个完整的Tag过程版本

要素	建议
Tag 格式	`v1.2.3` 或 `项目名-1.2.3`
预发布版本	`v1.2.3-alpha.1`、`v1.2.3-beta.2`、`v1.2.3-rc.1`
Tag 类型	使用附注标签（`git tag -a`）记录元信息
配套文档	每个 Release 需要 CHANGELOG.md 说明变更
自动化	可考虑 CI 自动生成 major/minor 别名标签

对于上面所说的预发布版本：这三个都是预发布版本的标签，用于在正式版发布前进行不同阶段的测试。它们的核心区别在于软件的稳定性和完成度，从低到高依次是：alpha < beta < rc。

类型	稳定性	主要用途	适用对象	预期风险
alpha (内测版)	最低，不稳定	核心功能验证，内部测试	核心开发者、早期测试者	存在较多Bug，功能不完整，可能崩溃
beta (公测版)	中等，相对稳定	广泛测试，收集反馈	所有愿意测试的社区用户	可能存在Bug，但核心功能应基本可用
rc (候选版)	很高，几乎等同于正式版	最终验证，修复最后时刻的关键Bug	需要提前适配的开发者或用户	非常接近稳定，理论上不再有重大Bug

一个典型的版本会经历以下阶段，最终发布正式版：

v1.2.0-alpha.1   ->   v1.2.0-alpha.2   ->   v1.2.0-beta.1   ->   v1.2.0-rc.1   ->   v1.2.0-rc.2   ->   v1.2.0

示范知名开源项目 React 为例：

Alpha：18.0.0-alpha-...
Beta：18.0.0-beta-...
RC：18.0.0-rc.0、18.0.0-rc.1
正式版：18.0.0

命名体系：

Alpha：内部尝鲜，核心功能测试。高风险。
Beta：公开测试，收集反馈。中风险。
RC (Release Candidate)：最终验证，准备上线。低风险。

核心总结

细节：

标签格式 vX.Y.Z + 附注标签

CHANGELOG倒序 + 6个分类标题

先改日志 → 再打标签 → 最后推送标签

1、版本号tag

格式：vX.Y.Z（主版本.次版本.补丁）
预发布：alpha < beta < rc（例：v1.2.0-beta.1）
打标签：必须用附注标签 git tag -a v1.0.0 -m "说明"
推送：git push origin v1.0.0（标签≠版本号，必须推送）

2、更新日志（CHANGELOG.md）铁律

位置：项目根目录
顺序：最新版本在最上面
标题：[v1.0.0] - 2023-10-27
分类：只用这6个标题
- Added - 新功能
- Changed - 变更
- Deprecated - 即将移除
- Removed - 已移除
- Fixed - Bug修复
- Security - 安全修复

3、完整发布流程

# 1. 更新CHANGELOG.md（写清楚本次改动）
# 2. 提交
git add CHANGELOG.md
git commit -m "docs: 更新v1.0.0变更日志"

# 3. 打附注标签
git tag -a v1.0.0 -m "Release v1.0.0: 新增用户认证"

# 4. 推送代码和标签
git push origin master
git push origin v1.0.0

4、重点注意

❌ 不要在标签指向的提交上继续改代码（标签不可变）
❌ 不要在CHANGELOG里粘贴Git commit原文（给人看，不是给机器看）
❌ 不要忘记推标签（git push origin --tags）

参考学习

[1]. Keeping a changelog：https://docs.viktor.ai/docs/create-apps/development-tools-and-tips/keep-a-changelog/#__docusaurus_skipToContent_fallback

起因