Stars: 101
Forks: 8
Pull Requests: 37
Issues: 36
Watchers: 3
Last Updated: 2023-04-24 22:45:59
Generate a markdown changelog document from a GitHub milestone.
License: MIT License
Languages: PHP, Shell
This library will generate a changelog markdown document from a GitHub milestone. It is based off of weierophinney/changelog_generator.
You can install with composer:
$ composer require jwage/changelog-generator
Or you can download the latest changelog-generator.phar
file from the releases pages.
Here is what an example changelog looks like. It was generated from the 0.0.3
milestone in GitHub for this project:
You can also look at the CHANGELOG.md file which is generated by this project.
Generate a change log based on a GitHub milestone with the following command:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0
Write the generated changelog to a file with the --file
option. If you don't provide a value, it will be written
to the current working directory in a file named CHANGELOG.md
:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file
You can pass a value to --file
to specify where the changelog file should be written:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md
By default it will overwrite the file contents but you can pass the --append
option to append the changelog to
the existing contents.
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md --append
If you want to prepend the changelog to an existing file, use the --prepend
option:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --file=changelog.md --prepend
To make the changelog easier to read, we try to connect pull requests to issues by looking for #{ISSUE_NUMBER}
in the body
of the pull request. When the user of the issue and pull request are different github users, the changelog line will look like the following:
You can filter the changelog by label names using the --label
option:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --label=Enhancement --label=Bug
It can be convenient when preparing release notes for an upcoming release to include open issues and pull requests. For
this you can use the --include-open
option:
$ ./vendor/bin/changelog-generator generate --user=doctrine --repository=migrations --milestone=2.0 --include-open
You can provide a PHP configuration file to the changelog generator if you don't want to provide the data manually each time.
Put the following contents in a file named 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())
// ...
,
];
Then you can use the configuration file like the following:
$ ./vendor/bin/changelog-generator generate --config=config.php
By default it will generate a changelog for the first changelog config in the array returned by the file. You can use the
--project
option if you want to generate a changelog for a specific project in the config file:
$ ./vendor/bin/changelog-generator generate --config=config.php --project=another-project
By default if you name your config file changelog-generator-config.php
, the changelog generator will look for that file
if no --config
option is passed.
$ ./vendor/bin/changelog-generator generate
You can override options provided by the ChangelogConfig
object from the command line by passing options to the
generate
command:
$ ./vendor/bin/changelog-generator generate --include-open=0
You can configure the URL of your GitHub instance by using the rootGitHubUrl
option. In your config.php
you can
pass a 5th argument to ChangelogConfig
that contains an array of options:
<?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')
,
];
By default it is not required to authenticate with GitHub to use this tool. But if you want higher rate limits or want to use it with private repositories then you will need to authenticate.
You can authenticate with your username
and password
or a personal access token
instead of your password using the ChangelogGenerator\GitHubUsernamePassword
class:
<?php
declare(strict_types=1);
use ChangelogGenerator\ChangelogConfig;
use ChangelogGenerator\GitHubUsernamePassword;
return [
'changelog-generator' => (new ChangelogConfig())
// ...
->setGitHubCredentials(new GitHubUsernamePassword('username', 'passwordOrToken'))
,
];
You can authenticate with an OAuth token as well using the ChangelogGenerator\GitHubOAuthToken
class:
<?php
declare(strict_types=1);
use ChangelogGenerator\ChangelogConfig;
use ChangelogGenerator\GitHubOAuthToken;
return [
'changelog-generator' => (new ChangelogConfig())
// ...
->setGitHubCredentials(new GitHubOAuthToken('the oauth token'))
,
];