README

此工具允许通过将每个PR中的特殊格式“更改文件”放入changelog目录中，来管理您的项目的更改日志。当您发布版本时，工具可以处理这些文件。

为什么？

在同时进行许多事情的项目中，传统的更改日志文件有一个主要缺点：合并冲突！多个PR可能会在文件中的同一位置插入更改日志条目，因此当其中一个被合并时，其他需要重新合并。不幸的是，GitHub和其他托管平台很少提供支持自定义合并引擎的功能，这可能有助于缓解这个问题。

在目录中使用“更改文件”可以绕过这个问题，因为除非两个人恰好选择了相同的PR文件名，否则文件创建不会冲突。此工具默认根据git分支名称生成文件名，人们通常会选择足够独特的名称。

更改文件的使用还可以让我们包含有关更改的附加元数据，特别是语义版本化的“重要性”。这意味着发布经理不再需要自行确定新版本应该是补丁、次要还是主要更新，因为更改文件本身已经指定了所需的更新类型。

安装

需要使用composer require --dev automattic/jetpack-changelogger。

这将安装changelogger工具到vendor/bin/，您可以将它添加到您的PATH中，或者您可以通过composer exec -- changelogger运行它。

如果您正在使用git，建议在您的仓库中也创建changelog/.gitkeep，以确保目录始终存在。

配置

Changelogger通过composer.json中的条目进行配置，在extra.changelogger下。在大多数情况下，您可以使用composer config extra.changelogger.$setting $value设置配置。

changelog：指定更改日志文件，相对于composer.json。默认为CHANGELOG.md。
changes-dir：指定包含更改文件的目录，相对于composer.json。默认为changelog。
link-template：创建更改日志条目链接的模板。${new}将被替换为新版本号的URL编码，${old}被替换为旧版本。
ordering：指定更改条目的顺序：按类型（'子标题'），'重要性'，'时间戳'和/或'内容'。默认为[ 'subheading', 'content' ]。
types：指定在存储库中使用的更改类型；请参阅类型字段。值是一个JSON对象，键是更改文件中的字段值，值是在合并更改日志文件中使用的子标题文本。可以是空的；默认为使用https://keepachangelog.com/en/1.0.0/#types中列出的类型。
formater：解析和格式化更改日志的插件。默认为keepachangelog。
versioning：用于确定新版本的版本控制插件。默认为semver。

使用方法

添加更改文件

更改日志文件由命名的字段、一个空白行和更改日志条目内容组成。

Significance: major
Type: added
Comment: This is an example.

Initial commit!

changelog目录中的文件名无关紧要，只要它不以点开头。

可以通过使用 changelogger add 命令交互式地创建一个变更日志文件。您也可以通过命令行选项非交互式地指定所有需要的字段；有关详细信息，请参阅 changelogger add --help 命令。

重要性字段

该字段指定了变更的重要性，其风格参考了语义版本控制。有效的值包括：

修补：向后兼容的错误修复。
次要：以向后兼容的方式添加（或弃用）功能。
主要：以某种方式破坏了向后兼容性。

根据 versioning 配置设置，这可能被用来确定将变更文件合并到新的变更日志版本时的版本号。

类型字段

该字段指定了变更的类型，这反过来又被用来在将变更文件合并到新的变更日志版本时将其放置在适当的子标题下。

有效的类型定义在 types 配置设置中。如果该设置为空，则应省略类型字段。

注释字段

该字段包含可能对与其他开发者沟通有用的任意文本。Changelogger 不会使用此字段。

变更日志条目

变更日志条目位于所有字段之后，由空行与它们分隔。这是当将变更文件合并到变更日志版本时包含在变更日志文件中的文本。

当重要性为“修补”时，条目可以留空。当重要性为“次要”或“主要”时，留空是不合法的。

验证变更文件

可以使用 changelogger validate 命令来验证变更文件。默认情况下，它将检查配置的 changes-dir 中所有非点文件，但也可以传递一个特定的文件列表。

遇到错误或警告时，默认情况下将报告文件的完整路径。可以使用 --basedir 来覆盖此行为，这将导致该目录内部的路径相对于该目录报告。

检查版本

要允许更容易地将 changelogger 集成到其他工具中，可以使用 changelogger version 命令打印基于当前版本的当前版本、前一个版本和下一个版本。

当获取下一个版本时，这里接受与 changelogger write 相同的标志来控制版本。

更新变更日志

可以使用 changelogger write 命令将变更文件合并到新的变更日志条目中。请注意，此操作将删除变更文件，因此建议在出现问题时先将其提交到 git 中。

命令行选项允许指定预发布后缀（如 -dev 或 -beta），完全覆盖版本确定，或修改最新的变更日志条目。

插件

插件用于解析变更日志文件并从当前版本确定下一个版本。

插件通过 JSON 字符串或包含以下键之一的对象指定：

name：请参阅下面的说明或插件文档。
class：插件类名称。必须通过自动加载器获取。
filename：从中加载插件类的文件。该文件必须定义一个符合接口的类。

插件可以接受额外的键作为配置。请参阅插件文档以获取详细信息。

如果给出了一个字符串，则假定它是 name。

包含的插件

包含一个格式化插件和两个版本控制插件。

“keepachangelog”格式化插件

此格式化程序解析标记为 markdown 格式的变更日志，具体请参阅 https://keepachangelog.com/en/1.0.0/。

配置选项包括：

bullet：用于标记变更日志条目的字符串。默认值为 -。
dateFormat：用于输出每个版本的戳记的PHP 日期格式化字符串。默认为 Y-m-d。

“semver”版本控制插件

根据变更的重要性以及语义化版本控制确定下一个版本。

“wordpress”版本控制插件

WordPress及其一些插件（如Jetpack）使用正常的十进制版本号，例如9.4，每次发布时增加0.1。从8.9到9.0没有特殊的意义。错误修复“点发行版”会增加后缀如9.4.1。

当此插件在使用中时，版本和写入命令将接受一个--point-release选项，以表示应执行点发行版增量而不是主要版本。

编写插件

格式化插件必须实现Automattic\Jetpack\Changelogger\FormatterPlugin接口。

版本控制插件必须实现Automattic\Jetpack\Changelogger\VersioningPlugin接口。

如果您希望您的插件可以通过一个name来访问，从Automattic\Jetpack\Changelogger\Plugins\{Name}Formatter或Automattic\Jetpack\Changelogger\Plugins\{Name}Versioning创建一个别名，适用于其类型，并确保别名可以通过自动加载器加载。有两种常见的方法可以正确实现这一点

使用PSR-0或PSR-4，将class_alias()放在与目标类相同的文件中，并创建一个具有对目标名称的class_exists()调用的虚拟文件，以触发加载。
在composer.json中使用.autoload.files来加载一个包含必要的class_alias()调用的文件。注意这将加载每个请求上的所有别名类。

automattic / jetpack-changelogger

维护者

详细信息