| name | sphinxnotes-changelog |
| description | Write and maintain changelogs for sphinxnotes projects. Covers preparing release changelogs, adding incremental entries, and the ``.. version::`` directive reference. |
SphinxNotes Changelog 编写指南
场景 1：为即将发布的版本编写 changelog
从上次正式发布至今的所有变更整理成 changelog。
步骤
- 确定基线版本：找到
docs/changelog.rst 中最后一个带有 :date: 的稳定版本
- 收集变更：
git log <last-tag>..HEAD
- 分类整理：按类别归纳（新功能、修复、重构、文档等）
- 编写条目：在文件顶部创建
.. version:: 块，不加 :date:（表示尚未发布）
- 发布时：加上
:date:，并按主版本号放入正确的 section
模板
.. version:: 3.0
- Add new feature (:issue:`42`)
- Fix some bug (:pull:`10`)
发布后变为：
.. version:: 3.0
:date: 2025-01-15
- Add new feature (:issue:`42`)
- Fix some bug (:pull:`10`)
场景 2：为正在开发的新功能加一行 changelog
日常开发中，每完成一个值得一提的变更，立即添加条目。
- 打开
docs/changelog.rst，找到顶部未发布版本的 .. version:: 块
- 如果还不存在，先创建一个（见场景 1）
- 在条目列表中添加一行
changelog 文件结构
.. This file is generated from sphinx-notes/cookiecutter.
==========
Change Log
==========
.. hint:: Release strategy reference link
Version 3.x
===========
.. version:: 3.0 ← 当前开发版本（无 :date:）
- New feature in progress
.. version:: 2.5 ← 已发布版本
:date: 2024-08-17
- Released feature
Version 2.x
===========
.. version:: 2.4.0
:date: 2023-08-26
- Older release
条目编写约定
- 祈使句："Add ...", "Fix ...", "Support ...", "Drop ..."
- 一条条目对应一个逻辑变更，粒度适中
- 用
(:issue:\N`) 引用 issue，(:pull:`N`)` 引用 PR
- 用
:confval:\name`` 引用配置项
- 用
**BREAKING**: 标记不兼容变更，并在指令上加 :break:
关联 issue / PR 的查找
为每个变更写条目时，如果存在对应的 issue 或 PR，必须引用。查找途径（按优先级）：
- merge commit 信息：合并 PR 时，merge commit message 通常包含
(#N) 格式的 PR 编号
- commit log：提交信息中可能引用 issue（如
fix #N、closes #N），可运行 git log <last-tag>..HEAD --oneline 查看
- gh CLI：用
gh pr list --state merged 查看已合入的 PR，gh issue list 查看相关 issue
优先级原则：issue > PR。如果一个 PR 修复了某个 issue，引用 issue 而非 PR。例如：
Fix referenceable field with multiple lines form (:issue:\34`)` — 即使通过 PR 实现，也引用 issueAdd new Sphinx Domain classifier (:pull:\27`)` — 纯功能 PR，无对应 issue 时引用 PR
条目风格
简短条目：
- Add new Sphinx Domain classifier (:pull:`27`)
- Fix referenceable field with multiple lines form (:issue:`34`)
带前缀（推荐）：
- feat: Support multiple MIDI outputs (:pull:`45`)
- fix: Convert MIDI track name to utf-8 (:pull:`47`)
- refactor: Builder that supports strike_node does not need to insert itself
- ci: No longer need checkout submodules
- docs: Update installation guide
带子条目的分组：
- Render ability improvements (:issue:`30`)
- **BREAKING**: The ``any_schemas`` confval is replaced
- Add object embedding support (:issue:`28`)
- Support datetime type in field
不兼容变更分组：
- **BREAKING** changes:
- Drop ``:noheader``, ``:nofooter:`` options
- Drop ``:audio:`` option and introduce ``:noaudio:``
.. seealso:: The 3.0 tracking issue: :issue:`15`
.. warning:: This is a BREAKING change to builders that support this role.
分类前缀
| 前缀 | 适用场景 |
|---|
feat: | 新功能 |
fix: | 修复 bug |
refactor: | 代码重构 |
ci: | CI/CD 相关 |
docs: | 文档变更 |
附录：.. version:: 指令参考
changelog 使用 sphinxnotes-project 提供的 .. version:: 指令来结构化记录版本发布。
依赖
在 conf.py 中启用 sphinxnotes.project 扩展：
extensions = ['sphinxnotes.project']
语法
.. version:: <版本号>
:date: <发布日期>
:break:
<变更日志内容>
选项
| 选项 | 类型 | 说明 |
|---|
date | date | 发布日期，格式 YYYY-MM-DD |
break | flag | 标记为不兼容变更 |
示例
已发布版本：
.. version:: 2.5
:date: 2024-08-17
- Add new Sphinx Domain classifier (:pull:`27`)
- Fix referenceable field with multiple lines form (:issue:`34`)
不兼容变更：
.. version:: 3.0
:break:
- **BREAKING**: The ``any_schemas`` confval is replaced
- Add object embedding support (:issue:`28`)
开发中版本（无日期）：
.. version:: 4.0
- Work in progress feature (:issue:`100`)
工作原理
- 版本号作为对象名称，可被
:version: 角色引用
- 提供
date 时显示格式化日期（按年份分组索引），并自动生成 GitHub release tag 链接
- 未提供
date 时显示"仍在开发中"提示
- 设置
break 标志时显示不兼容变更警告
- 内容块直接作为变更日志显示
交叉引用
- LaTeX builder support (Since :version:`1.5`)
- Jianpu support (Since :version:`1.6.0`)
注意事项
date 的值自动按年份分组创建索引tag 角色自动生成 GitHub release 链接（基于版本号）
