README

需要维护者

遗憾的是，我没有时间开发readmegen。很高兴看到它被许多人使用！如果这个项目就此结束，那就太遗憾了。也许你可以帮忙？由于社区非常乐于助人，并提供PR，所以没有多少工作要做。

如果你愿意推动readmegen进一步发展，请让我知道。

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

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

注意：该包目前仅支持GIT和*.md输出文件。你能提供对其他VCS或输出格式的支持吗？欢迎帮助：）

安装

全局安装（推荐）

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和Bugfixes，它们将按照这个顺序出现在更改日志中

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:
    - 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
feat(username): Here is more some cool stuffs done by username

更改日志

1.2.0

(2019-02-13)

修复

• 使用symfony yaml 3.2
• 使用 phpspec 版本 ^2.5 （感谢 murrant）

功能

• 处理关键字旁边的用户名（感谢 ingluife）

错误修复

• 使用symfony yaml 3.2
• 使用 phpspec 版本 ^2.5

1.1.3

(2018-08-16)

添加

• 根据https://keepachangelog.com/添加消息组

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