README

使用VCS提交消息生成您的项目日志。

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

注意：该包目前仅支持GIT和*.md输出文件。您可以为其他VCS或输出格式提供支持？欢迎帮助：）

安装

全局安装（推荐）

composer global require golars/readmegen

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

本地安装

composer require golars/readmegen

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将搜索以特定关键字开头的信息。这些关键字告诉脚本将提交附加到哪个组。可以覆盖消息组。

例如 - 默认配置支持四种类型的提交：功能、错误修复、文档和重构。只有当提交消息以特定单词开头时，才会将其附加到特定的组。默认配置允许错误修复有两个关键字：[!]和fix。这意味着，为了将消息附加到错误修复组，它必须以[!] bla bla或fix foo bar开头。关键字不区分大小写。

所有不适合任何组的提交都将被忽略（我们不想在更改日志中包含合并之类的操作）。

分组提交

适合于组的每个提交都将分组（是的，听起来很愚蠢）。组将按照它们在配置文件中出现的顺序打印出来，因此如果您有功能和错误修复，这就是更改日志中它们将出现的顺序。

Features
- feature 1
- feature 2

Bugfixes
- fix 1

您可以在自定义配置文件中覆盖组（下面有详细信息）。

链接模式

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

本地配置

默认配置包含提交组定义和问题链接模式。它还指定了要使用的版本控制系统和输出文件的类型。您可以通过在项目的根目录下创建一个 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:
    - "[+]"
    - "add"
  Bugfixes:
    - "[!]"
    - "fix"
  Hotfixes:
    - "[!!]"
  Deleted:
    - "[-]"
    - "delete"
  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
[-] Remove same ...
[+] Some more cool stuff

更改日志

1.2.2

(2016-11-04)

功能

• 将最小 PHP 版本升级到 5.6

热修复

• travis 测试

1.2.1

(2016-11-04)

错误修复

• 多消息组，测试

重构

• php-cs-fixer

1.1.7

(2016-10-02)

功能

• 允许使用 symfony/yaml: ^3.0

1.1.6

(2015-12-11)

功能

• 添加对热修复 [!!] 格式的支持

1.1.5

(2015-12-03)

重构

• 代码格式化，需要 php5.5，省略空白行

1.1.4

(2015-12-03)

功能

• 添加作者：

重构

• 在 composer.json 中重命名项目

1.1.3

(2015-12-03)

删除

• 冒号作为分隔符

功能

• preg_quote 对 message_groups

重构

• 修改当前项目的 message_groups

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 提交中提取的。