更新日志约定

更新日志约定

本页是每个公开 NextPDF 仓库在记录变更并发布版本时遵循的契约。它是约定的参考依据；它并不声明任何包行为。各包、各版本的叙述内容存放在每个仓库自己的 CHANGELOG.md 中。本页定义它们共用的规则，让跨仓库更新日志摘要保持一致，并且不会泄漏信息。

Conventional Commits 1.0.0

每个 commit 的标题都是 type(scope): description。其中 type 是以下类型之一：

类型	含义	使用者可见	版本影响
feat	新增的功能	是	提升次版本号
fix	已修正的行为	是	提升修订版本号
perf	性能改进，且不改变行为	是	提升修订版本号
refactor	内部重构，无可观察的变更	否	无
docs	仅文件	否	无
test	仅测试	否	无
build / ci	仅构建或流水线	否	无
chore	维护、依赖包、工具链	否	无
revert	还原先前的 commit	视情况而定	视情况而定

破坏性变更会通过在类型或范围后添加 ! 来标记（feat(api)!: …），也可以通过 BREAKING CHANGE: 脚注标记。在 Semantic Versioning 下，两者都会提升主版本号。与安全性相关的修正会被记录下来，以便筛选进跨仓库摘要的 Security 栏位。

Semantic Versioning 2.0.0

版本号提升是机械式的。凡是包含任何破坏性变更的版本发布，都属于主版本。否则，凡是包含任何 feat 的版本发布，都属于次版本。否则，凡是包含任何 fix 或 perf 的版本发布，都属于修订版本。依据 SemVer §4，1.0 之前的包可以为破坏性变更提升次版本号。该 commit 仍会带有破坏性标记，从而让摘要保持准确。

Keep a Changelog 分組

每个仓库的 CHANGELOG.md 都遵循 Keep a Changelog 1.1.0：条目会按各个发布版本分组到 Added、Changed、Deprecated、Removed、Fixed 以及 Security 之下。[Unreleased] 区段可以在仓库中保存进行中的记录，但跨仓库摘要只会计入已打标签、已发布的版本。尚未发布的工作绝不会出现在公开索引中。

跨仓库摘要如何推导（并保持不泄漏）

更新日志索引上的摘要表，是通过只读方式读取每个仓库在其最新发布标签处的 Conventional Commits 历史，并统计各类别而生成的。这些推导规则刻意设计得很窄，确保任何内部细节都不会外泄：

1. 只计数量，不含内容。 只会报告每种使用者可见类型的 commit 数量。不会呈现任何 commit 的标题、正文、脚注或哈希值。
2. 仅限使用者可见的类型。 docs、test、ci、chore，以及 refactor 都会被排除——它们不会改变包使用者可观察到的任何内容。
3. 仅限已发布。 commit 只有在成为某个公开包已打标签发布版本的一部分后，才会被计入。
4. 不含识别码。 可能出现在私有 commit 范围中的内部 issue、ticket、cycle、wave 或工作项引用绝不会被披露，因为范围文字本身永远不会被呈现——只会读取类型。
5. 不含自动化署名。 不会读取或显示贡献者自动化的尾注。

这就是为什么公开的更新日志是一份类别摘要，再加上指向各包自身 CHANGELOG.md 的链接，而不是汇总后的 commit 信息流。就构造而言，这份摘要可以证明不含任何内部泄漏。具权威性的叙述内容会保留在拥有它的包之中。

另请参阅

• 更新日志
• 集成示例约定
• Conventional Commits 1.0.0
• Semantic Versioning 2.0.0