Changelog Generator

This library will generate a changelog markdown document from a GitHub milestone. It is based off of weierophinney/changelog_generator.

Features

Installation

You can install with composer:

$ composer require jwage/changelog-generator

Or you can download the latest changelog-generator.phar file from the releases pages.

Example

Here is what an example changelog looks like. It was generated from the 0.0.3 milestone in GitHub for this project:

0.0.3

Total issues resolved: 7
Total pull requests resolved: 7
Total contributors: 1

Enhancement

15: Look for changelog-generator-config.php file by default if no --confi… thanks to @jwage
13: Allow changelog configurations to be provided via a php config file. thanks to @jwage
12: Allow changelog to be filtered by label names. thanks to @jwage
11: Add total contributors to changelog. thanks to @jwage
9: Improve changelog totals to be split by issue and pull requests. thanks to @jwage
7: Link pull requests and issues together to improve the changelog format. thanks to @jwage
6: Allow changelog to be written to a file. thanks to @jwage

You can also look at the CHANGELOG.md file which is generated by this project.

Basic Usage

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 to File

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

Connecting Issues & Pull Requests

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:

634: Fix namespace in bin/doctrine-migrations.php thanks to @Majkl578 and @jwage

Filtering by Labels

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

Configuration File

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'])
    ,
    '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

GitHub Enterprise Support

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')
    ,
];

majkl578 / changelog-generator Goto Github PK