zenstruck / changelog
Generate pretty release changelogs using the commit log and Github API.
Fund package maintenance!
kbond
Requires
- php: >=8.0
- composer/semver: ^3.3
- laravel-zero/phar-updater: ^1.1.1
- symfony/cache: ^5.4
- symfony/console: ^5.4
- symfony/filesystem: ^5.4
- symfony/http-client: ^5.4
- symfony/polyfill-php80: ^1.16
Requires (Dev)
- phpunit/phpunit: ^9.5
- symfony/phpunit-bridge: ^6.2
- symfony/var-dumper: ^5.4
- zenstruck/console-test: ^1.0
README
Generate pretty release changelogs using the commit log and Github API. Changelog entries are in the following format:
{short hash} {summary} (#{PR number}) by {author}, {co-author 1}, {co-author n}...
Some notes about the format:
- Currently, this format is hard-coded and can't be customized
- Merge commits are excluded
- PR number is only added if not already in the summary (and a PR exists for the commit)
- Author/Co-Author's are converted to GitHub username links if possible to take advantage of GitHub Release Avatar List
See an example of a release generated using this package.
Installation
To avoid dependency conflicts with this tool, it is recommended to install as an executable PHAR or install in your project (or globally) using the composer bin plugin.
PHAR
wget https://github.com/zenstruck/changelog/releases/latest/download/changelog.phar -O changelog && chmod +x changelog mv changelog ~/bin # assumes ~/bin is in your PATH
Composer Bin Plugin
Requires the bamarni/composer-bin-plugin.
# locally in your project composer bin changelog require zenstruck/changelog # globally composer global bin changelog require zenstruck/changelog
Configuration
The changelog
binary should be executable either globally or via vendor/bin/changelog
. For the remainder of this
documentation, it is assumed this is available as changelog
.
This tool requires a GitHub Personal Access Token to access the GitHub API. You can configure this in two ways:
GITHUB_API_TOKEN
environment variable (ie prefixchangelog
commands withGITHUB_API_TOKEN=your-token
)- Configure the token globally:
changelog configure
and follow the instructions to generate/save your token
Usage
Note: Commands that detect the repository from your current directory use the
upstream
origin if available.
Changelog Preview
Generate a changelog preview in your console:
# "interactive", detects repository from current directory, from=last release on GitHub, to=default branch changelog generate # equivalent to above, "generate" is the "default command" changelog # outputs changelog for "your/repository" from tag "v1.0.0" to branch "main" changelog generate --repository=your/repository --from=v1.0.0 --to=main
Run changelog generate --help
to see full command documentation.
Create Changelog File
Create a CHANGELOG.md
file for the current repository based on existing releases. This
file is created in the current working directory. It is up to you to add/commit to the repository.
# create a CHANGELOG.md bin/changelog file:create # customize the filename bin/changelog file:create --filename=changes.md # exclude releases marked as "pre-release" bin/changelog file:create --exclude-pre-releases
Create Release
Create (and optionally push) a release changelog (exclude --push
to preview what the release will look like):
# "interactive" - detects repository from current directory, suggests next version changelog release # generates changelog from v1.0.0 to main and creates v1.1.0 release on GitHub that has the changelog as the body changelog release v1.1.0 --repository=your/repository --from=v1.0.0 --target=main --push # detects repository from current directory, from=last release on GitHub, target=default branch changelog release v1.1.0 --push
You can use semantic versioning keywords as the next version. The following example assumes your last release was v1.0.0.
changelog release bug --push # creates v1.0.1 release changelog release feature --push # creates v1.1.0 release changelog release major --push # creates v2.0.0 release
Run changelog release --help
to see full command documentation.
Release Status Dashboard
Generate a simple dashboard for a GitHub organization showing package release statuses.
changelog dashboard my-org # will ask for organization and give option to save as default. # if saved, subsequent calls to the command will not require the organization argument changelog dashboard
If you have repositories that have workflows disabled due to inactivity, you
can use the --enable-workflows
option to enable them.