Download the PHP package aeon-php/automation without Composer

Automation

Command Line Application that can automatically update changelog file of your project after each commit/pull request/tag/release

Table of contents:

• Why?
• When?
• How?
• Installation
• Contributing
• Documentation
• Integrations
  • GitHub Actions
• Integration Request

Why?

There are similar, more popular projects around, why this? Automation is designed to give project owner a bit more flexibility and control over the changelog generation process. If pull requests are properly described Automation will take that description, parse it and extract following types of changes from it:

• added
• changed
• fixed
• removed
• deprecated
• security

Those types are part of keep a changelog notation.

Pull Request Description by definition is easy to update/change, also once commits are merged which makes it really easy to get back to a specific PR when generating a changelog, fix it and get a better changelog output.

What if pull requests does not have expected description? Then Automation will fall back into commit messages but even here it will first try to look for conventional commit notation and if that fail it will look for common prefixes like Fix, Added, Removed.

Still not convinced by keep a changelog theme? No problem, Automation is supporting also more classical approach, just use --theme=classic option.

What if one would still prefer commit messages over pull requests? Don't worry, --only-commits option is here for him, just like --only-pull-requests is for the opposite camp.

Turn This

Into This

When?

Not sure if automated changelog generation is for you?

• Software with stable release cycle, following SemVer
• Continuous Integration and Continuous Delivery (CI/CD)

Thos are two most popular use cases.

Releasing open source project you will probably look into --tag option that will take a all changes between given and previous tag and generate changelog.

When working on a project that is released multiple times every day and does not really have a predictable release cycle you might want to store last deployed commit SHA hash and pass it later through --commit-end option. Automation will be able then to generate changelog since last release for you.

How?

Examples:

Generate full changelog for repository

Generate full changelog for repository ⚠️ update CHANGELOG.md file and all releases ⚠️

Generate unreleased changes for repository

Generate changelog for specific tag

In order to generate a changelog Automation takes 4 steps.

Currently, Automation takes the whole project history directly from GitHub but more sources are coming.

1) Detect Changes Scope

When generating a changelog, Automation is first trying to understand what is the scope of changes. By default, it takes head of the default branch and it looks for the latest tag (from a semantic versioning point of view). Of course, this can be overwritten by telling automation to start from a specific tag using --tag option or even more precisely by providing start and end commit SHA, --commit-start, --commit-end.

There are 2 more options that could help to setup the right scope, --changed-after and --changed-before which also supports relative formats like --changed-after=noon or --changed-after="-1 day"

2) Fetch Project History

When the scope is detected, Automation will fetch the history of changes from source. It all starts from commits, and it works pretty much as git log origin..HEAD command. When commits are fetched, Automation pulls all Pull Requests since they also have valuable data about changes (this can be skipped using --only-commits option). Not all contributions are worth mentioning, sometimes you might want to exclude changes from bots. --skip-from option makes possible to skip changes from given authors.

3) Analyze Project History

Automation follows the Keep a Changelog philosophy and it can recognize following types of changes:

• Added
• Changed
• Deprecated
• Removed
• Fixed
• Security

There are several strategies making this recognition possible:

• HTML Changes Detector
• Conventional Commit Detector
• Prefix Detector
• Default Detector

They are applied in given order until first one parse changes source and properly detect all changes.

4) Format Changelog

When all changes are detected and grouped by types Automation moves to the last step, changelog generation.

Formats

Automation supports following changelog formats:

• markdown
• html

Themes

Automation supports following themes:

• keepachangelog
• classic

All themes are supported by all formats.

keepachangelog

This theme follows Keep a Changelog convention, changes are organized by type.

classic

This theme does not organize changes in any particular way, each change is displayed as a separated line item ordered by change date. Combined with --only-pull-requests option will provide clean and organized classical list of changes taken from pull request titles.

Installation

Before you start, generate your own GitHub personal access token. It can be provided as environment variable AUTOMATION_GH_TOKEN or through CLI option --github-token

If Automation is not working as you expected, increase verbosity to see how it works under the hood. It can be done by providing one of following options:

• -v - normal
• -vv - verbose
• -vvv - debug

Docker

Composer

Phar

TODO: Coming soon

Because Automation is using GitHub API to grab project history you can use it against any popular github projects.

Contributing

Looking for a way to contribute? Awesome ❤️ Below you can find few places to start with:

• Contributing & Development

You are also more than welcome to open an issue if anything about this project bothers you.

Documentation

Commands

changelog:generate

changelog:generate:all

changelog:release:unreleased

changelog:get

tag:list

workflow:timing:list

Integration Request

If you would lik to integrate Automation with your project but not sure how, feel free to Open Integration Request.
We will first test your project and if possible prepare an integration Pull Request.