Allison is coding...

Notes | How to keep a CHANGELOG

Generated by Gemini.

How to

1. CHANGELOG.md 需要加入 .gitignore 吗？还是一起推送到 GitHub？

答案：绝对不要加入 .gitignore，必须一起推送到 GitHub 仓库。

原因如下：

  • 公开的变更历史：Changelog（变更日志）是给用户、贡献者和其他开发者看的。当他们访问 GitHub 仓库或安装扩展/脚本时，可以通过这个文件一眼看出每个版本新增了什么、修复了什么。
  • 版本发布配套：在 GitHub 上发布 Release（版本）时，通常会直接引用或复制 CHANGELOG.md 中对应版本的内容。
  • 团队协作：团队成员需要知道当前版本的代码究竟改了什么，共享这个文件能保持大家对项目进展的共识。

2. 一般 Changelog 要怎么写？

业界标准格式：Keep a Changelog（遵循语义化版本 2.0.0）。

编写 Changelog 时，通常遵循以下核心原则：

① 核心原则

  • 人是用来看的，不是用来读 Git Commit 历史的：不要直接把 git log 的原始提交记录贴上去。Changelog 应该用通俗易懂、结构化的语言描述对用户/开发者有意义的改动。
  • 最新版本在最上面：新版本放在文件顶部（[Unreleased] 之下），旧版本依次往下排。
  • 标明发布日期：每个版本号后面应附带发布日期（格式一般为 YYYY-MM-DD）。

② 固定的分类标签（Types of changes）

在每个版本内，可将改动细分为以下六个标准类别（没有涉及的类别可以直接不写）：

  1. Added (新增)：用于新添加的功能。
  2. Changed (修改)：用于对现有功能的改动。
  3. Deprecated (废弃)：用于在未来版本中即将删除的特性。
  4. Removed (移除)：用于在此版本中已删除的特性。
  5. Fixed (修复)：用于任何 Bug 的修复。
  6. Security (安全)：用于安全漏洞的修复或依赖升级。

实用编写示例

假设接下来要开发新版本，可以这样在 CHANGELOG.md 中记录：

## [Unreleased]
### Added
- 新增了对 Chrome 侧边栏（Side Panel）的支持。

### Fixed
- 修复了在 Firefox 浏览器下偶尔无法正常下载图片的 bug（#12）。

## [1.14.0] - 2026-07-09
### Added
- 统一了 Chrome、Firefox 和 Tampermonkey 构建的版本号管理。

### Changed
- 将三个平台的目标版本号对齐（此前版本号不一致）。

底部链接更新

在 Changelog 文件的底部，通常会有对比链接（比较两个版本之间的差异）。当发布新版本时，记得更新底部的比较链接。例如：

[Unreleased]:  https://github.com/YOUR_ACCOUNT/repo_name/compare/v1.14.0...HEAD
[1.14.0]:  https://github.com/YOUR_ACCOUNT/repo_name/releases/tag/v1.14.0

总结建议

  1. 保留并提交 CHANGELOG.md 到 GitHub。
  2. 在每次准备发布新版本时，把 [Unreleased] 下面写好的改动打包，新建一个版本号标题（如 ## [1.15.0] - 2026-07-14），并把改动归类到 Added / Changed / Fixed 等分类下。