README

此库可以从GitHub里程碑生成变更日志Markdown文档。它基于weierophinney/changelog_generator。

功能

安装

您可以使用composer安装

$ composer require jwage/changelog-generator

或者您可以从发布页面下载最新的changelog-generator.phar文件。

示例

以下是一个示例变更日志的样子。它是由该项目在GitHub中的0.0.3里程碑生成的

0.0.3

解决的总问题数： 7
解决的总拉取请求数： 7
总贡献者数： 1

增强

15: 默认查找changelog-generator-config.php文件，如果没有提供--confi… 感谢 @jwage
13: 允许通过PHP配置文件提供变更日志配置。感谢 @jwage
12: 允许通过标签名称过滤变更日志。感谢 @jwage
11: 将总贡献者添加到变更日志中。感谢 @jwage
9: 改进变更日志总数，按问题和拉取请求分开。感谢 @jwage
7: 链接拉取请求和问题以改进变更日志格式。感谢 @jwage
6: 允许将变更日志写入文件。感谢 @jwage

您还可以查看由本项目生成的CHANGELOG.md文件。

基本用法

使用以下命令根据GitHub里程碑生成变更日志

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0

写入文件

使用--file选项将生成的变更日志写入文件。如果不提供值，它将被写入当前工作目录中名为CHANGELOG.md的文件

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file

您可以为--file传递一个值以指定变更日志文件应写入的位置

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md

默认情况下，它将覆盖文件内容，但您可以通过传递--append选项将变更日志附加到现有内容。

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md --append

如果您想将变更日志添加到现有文件的开头，请使用--prepend选项

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md --prepend

连接问题 & 拉取请求

为了使变更日志更容易阅读，我们尝试通过在拉取请求的正文中查找#{ISSUE_NUMBER}来将拉取请求连接到问题。当问题用户和拉取请求用户是不同的GitHub用户时，变更日志行将如下所示

634: 修复 bin/doctrine-migrations.php 中的命名空间，感谢 @Majkl578 和 @jwage

按标签过滤

您可以使用 --label 选项按标签名称过滤变更日志

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --label=Enhancement --label=Bug

包含开放问题和拉取请求

在准备即将发布的版本说明时，包含开放问题和拉取请求可能会很方便。为此，您可以使用 --include-open 选项

$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --include-open

配置文件

如果您不想每次都手动提供数据，可以为变更日志生成器提供一个 PHP 配置文件。将以下内容放入名为 config.php 的文件中

<?php

declare(strict_types=1);

use ChangelogGenerator\ChangelogConfig;

return [
    'changelog-generator' => (new ChangelogConfig())
        ->setUser('jwage')
        ->setRepository('changelog-generator')
        ->setMilestone('0.0.4')
        ->setLabels(['Enhancement', 'Bug'])
        ->setIncludeOpen(true)
    ,
    'another-project' => (new ChangelogConfig())
        // ...
    ,
];

然后您可以使用配置文件，如下所示

$ ./vendor/bin/changelog-generator generate --config=config.php

默认情况下，它将为文件返回的数组中的第一个变更日志配置生成变更日志。如果您想为配置文件中的特定项目生成变更日志，可以使用 --project 选项

$ ./vendor/bin/changelog-generator generate --config=config.php --project=another-project

默认情况下，如果您将配置文件命名为 changelog-generator-config.php，变更日志生成器将在未传递 --config 选项的情况下查找该文件。

$ ./vendor/bin/changelog-generator generate

您可以通过向 generate 命令传递选项来覆盖 ChangelogConfig 对象提供的选项

$ ./vendor/bin/changelog-generator generate --include-open=0

支持GitHub Enterprise

您可以使用 rootGitHubUrl 选项配置您的 GitHub 实例的 URL。在您的 config.php 中，您可以向 ChangelogConfig 传递一个包含选项的数组作为第五个参数

<?php

declare(strict_types=1);

use ChangelogGenerator\ChangelogConfig;

return [
    'changelog-generator' => (new ChangelogConfig())
        ->setUser('jwage')
        ->setRepository('changelog-generator')
        ->setMilestone('0.0.3')
        ->setLabels(['Enhancement', 'Bug'],)
        ->setOption('rootGitHubUrl', 'https://git.mycompany.com/api/v3')
    ,
];

GitHub 认证

默认情况下，使用此工具不需要通过 GitHub 进行认证。但如果您想获得更高的速率限制或想使用私有仓库，则需要认证。

个人凭据

您可以使用 username 和 password 或个人访问令牌进行认证，而不是使用密码，使用 ChangelogGenerator\GitHubUsernamePassword 类

<?php

declare(strict_types=1);

use ChangelogGenerator\ChangelogConfig;
use ChangelogGenerator\GitHubUsernamePassword;

return [
    'changelog-generator' => (new ChangelogConfig())
        // ...
        ->setGitHubCredentials(new GitHubUsernamePassword('username', 'passwordOrToken'))
    ,
];

OAuth 令牌

您还可以使用 ChangelogGenerator\GitHubOAuthToken 类使用 OAuth 令牌进行认证

<?php

declare(strict_types=1);

use ChangelogGenerator\ChangelogConfig;
use ChangelogGenerator\GitHubOAuthToken;

return [
    'changelog-generator' => (new ChangelogConfig())
        // ...
        ->setGitHubCredentials(new GitHubOAuthToken('the oauth token'))
    ,
];

jwage / changelog-generator

维护者

详情