README

使用版本控制系统（VCS）提交消息生成您项目的日志。

ReadmeGen 是一个 PHP 包，它扫描版本控制系统的日志以查找具有特定模式的消息。这些消息被提取、分组并附加到更改日志文件（例如 readme.md）的开头。此包可以指示获取特定标签（或提交）之间的消息。这样，每次您标记新的版本时，都可以运行 ReadmeGen 以自动生成更改日志。

注意：该包目前仅支持 GIT 和 *.md 输出文件。您能提供其他版本控制系统或输出格式的支持吗？欢迎帮助：）

安装

全局安装（推荐）

composer global require fojuth/readmegen:@stable

您可以在 Composer 文档 中了解更多关于全局安装的信息。

本地安装

composer require fojuth/readmegen:1.*

Windows 安装

请确保 Windows 的 PATH 变量包含到 composer bin 目录的路径

C:\Users\{USER}\AppData\Roaming\Composer\vendor\bin

重启任何您想使用的 shell 终端，以便更改生效。

用法

此包旨在用作可执行脚本，而不是您要包含在项目中的库。假设您已全局安装 ReadmeGen，要更新您的更改日志文件，只需运行

readmegen --from TAG --to TAG --release RELEASE_NUMBER --break BREAKPOINT

例如

readmegen --from 1.12.0 --to 1.13.0 --release 1.13.0 --break *Changelog*

这告诉脚本生成名为 1.13.0 的更改日志更新，并应该从标签 1.12.0 扫描日志直到 1.13.0。不考虑更早（或更晚）的提交。ReadmeGen 将在 *Changelog* 行之后注入生成的日志。

如果您想从特定的标签（或提交校验和）生成更改日志到最新的提交（HEAD），则只需省略 --to 参数

readmegen --from a04cf99 --release 1.13.0 --break *Changelog*

您还可以在 readmegen.yml 配置文件中指定断点，从而使命令更加简洁

readmegen --from a04cf99 --release 1.13.0

消息格式

ReadmeGen 将搜索以特定关键字开头的信息。这些关键字告诉脚本将提交附加到哪个组。可以重写消息组。

例如 - 默认配置支持四种类型的提交：功能、错误修复、文档和重构。只有当提交以特定单词开头时，才会将其附加到某个组。默认配置允许错误修复有两个关键字：bugfix 和 fix。这意味着，要附加到错误修复组，消息必须以 bugfix: blabla 或 Fix: foo bar（注意冒号 : 符号 - 它必须紧跟关键字）开头。关键字不区分大小写。

所有不符合任何组的提交都将被忽略（我们不想在变更日志中包含合并等东西）。

分组提交

所有符合某个组的提交都将被分组（是的，听起来有点愚蠢）。组将按照它们在配置文件中出现的顺序打印出来，所以如果你有功能和错误修复，这就是它们在变更日志中出现的顺序。

Features
- feature 1
- feature 2

Bugfixes
- fix 1

你可以在自定义配置文件中覆盖这些组（详细信息见下文）。

链接模式

ReadmeGen可以将问题链接到问题跟踪器——所有以#开头的数字都将链接到配置文件中定义的issue_tracker_pattern键下的网站。如果提交消息中有一个字符串#1234，它将被转换为一个指向问题跟踪器的链接。

本地配置

默认配置包含提交组的定义和问题链接模式。它还指定了要使用的VCS和输出文件的类型。你可以通过在项目根目录下创建一个readmegen.yml文件来覆盖这些设置（项目范围）。当ReadmeGen运行时，它会检查该文件是否存在，并相应地合并设置。

默认的readmegen.yml配置如下所示

vcs: git
format: md
issue_tracker_pattern: http://some.issue.tracker.com/\1
break: "## Changelog"
output_file_name: "README.md"
message_groups:
  Features:
    - feature
    - feat
  Bugfixes:
    - fix
    - bugfix
  Documentation:
    - docs
  Refactoring:
    - refactoring

每个message_groups键都是将放入变更日志中的组的名称。组内的值是提交必须以（后面跟着冒号:符号）开头的关键字，以便将其附加到该组。

发布号

ReadmeGen需要一个发布号（--release）来提供。这将作为生成变更日志的标题。

断点

默认情况下，更改将添加到变更日志文件的开始处。但是，你可以指定一个“断点”，在这些更改下面附加。通常，你会在变更日志中有一个“简介”，然后是列出的更改。你不希望脚本将更改推送到文件顶部，而是推送到某个特定的行下面。你可以在readmegen.yml配置文件或使用--break参数指定此行。

例如

readmegen --from 1.12.0 --to 1.13.0 --release 1.3.3 --break *Changelog*

脚本将在包含*Changelog*短语的行下面附加更改。这应该是该行中的唯一短语。如果你使用CLI参数方法（--break），断点不能包含空格。因此，鼓励使用配置方法——你可以在那里使用空格，就像默认配置中显示的那样。

默认情况下，ReadmeGen将搜索## Changelog断点。如果未找到断点短语，输出将添加到变更日志文件的开始处。

示例提交

以下是ReadmeGen（使用默认配置）将抓取的一些示例提交消息

feature: Added some cool stuff (#1234)
fix: #4245, regarding client login bug
docs: Updated the transaction section of the docs
feat: Some more cool stuff

变更日志

1.1.2

(2015-07-12)

功能

• 更改输出文件名（感谢reva2）

错误修复

• 在示例用法消息中添加了缺失的新行字符（感谢reva2）

1.1.1

(2015-01-04)

功能

• 添加了 .travis.yml

1.1.0

(2014-12-30)

功能

• 在 readmegen.yml 默认配置文件中添加了 "break"。它具有默认值，并可本地覆盖。

1.0.2

(2014-12-30)

错误修复

• 发布日期从 --to 提交中提取。