增强现实AR>> automation>> 返回
项目作者： aeon-php

项目描述 ：
⚙️📝 Automatically update project changelog after commit/tag/release/pull request in "keep a changelog" format (or not)
高级语言： PHP
项目地址: git://github.com/aeon-php/automation.git
创建时间： 2020-12-28T21:00:02Z
项目社区：https://github.com/aeon-php/automation
开源协议：MIT License
下载


Automation

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

Table of contents:

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

Pull Request

Into This

Pull Request

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

  1. docker run -t -e AEON_AUTOMATION_GH_TOKEN --rm aeonphp/automation changelog:generate:all aeon-php/calendar --skip-from="dependabot[bot]" --skip-from="aeon-automation"

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

  1. docker run -t -e AEON_AUTOMATION_GH_TOKEN --rm aeonphp/automation changelog:generate:all aeon-php/calendar --github-release-update --github-file-update-path=CHANGELOG.md --skip-from="dependabot[bot]" --skip-from="aeon-automation"

Generate unreleased changes for repository

  1. docker run -t -e AEON_AUTOMATION_GH_TOKEN --rm aeonphp/automation changelog:generate aeon-php/calendar --skip-from="dependabot[bot]" --skip-from="aeon-automation"

Generate changelog for specific tag

  1. docker run -t -e AEON_AUTOMATION_GH_TOKEN --rm aeonphp/automation changelog:generate aeon-php/calendar --tag=0.15.0 --skip-from="dependabot[bot]" --skip-from="aeon-automation"

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:

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

  1. docker pull aeonphp/automation
  2. docker run -t --rm aeonphp/automation --help

Composer

  1. git clone git@github.com:aeon-php/automation.git
  2. cd automation 
  3. composer install
  4. bin/automation --help

Phar

TODO: Coming soon

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

  1. automation changelog:generate organization/name -v

Contributing

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

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

Documentation

Commands

  1. aeon-automation
  3. Usage:
  4.   command [options] [arguments]
  6. Options:
  7.   -h, --help                                         Display help for the given command. When no command is given display help for the list command
  8.   -q, --quiet                                        Do not output any message
  9.   -V, --version                                      Display this application version
  10.       --ansi                                         Force ANSI output
  11.       --no-ansi                                      Disable ANSI output
  12.   -n, --no-interaction                               Do not ask any interactive question
  13.       --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
  14.       --cache-path=CACHE-PATH                        Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  15.       --github-token=GITHUB-TOKEN                    Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  16.       --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  17.   -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  19. Available commands:
  20.   help                            Displays help for a command
  21.   list                            Lists commands
  22.  branch
  23.   branch:list                     List project branches
  24.  cache
  25.   cache:clear                     Clears all or specific caches.
  26.  changelog
  27.   changelog:generate              Generate change log for a release.
  28.   changelog:generate:all          Generate change log for all tags.
  29.   changelog:get                   Get project changelog.
  30.   changelog:release:unreleased    Update changelog file by turning Unreleased section into the next release
  31.  milestone
  32.   milestone:create                Create new milestone for project
  33.   milestone:list                  
  34.  pull-request
  35.   pull-request:description:check  Check if pull request has changes in expected by Automation format.
  36.   pull-request:list               
  37.   pull-request:template:show      Display pull request template required by this tool to properly parse keepachangelog format
  38.  release
  39.   release:list                    List all project releases
  40.  tag
  41.   tag:list                        Display all tags following SemVer convention sorted from the latest to oldest
  42.  workflow
  43.   workflow:job:list               List project Github actions jobs status from the latest workflow run

changelog:generate

  1. Description:
  2.   Generate change log for a release.
  4. Usage:
  5.   changelog:generate [options] [--] <project>
  7. Arguments:
  8.   project                                                project name, for example aeon-php/calendar
  10. Options:
  11.       --commit-start=COMMIT-START                        Optional commit sha from which changelog is generated . When not provided, default branch latest commit is taken
  12.       --commit-end=COMMIT-END                            Optional commit sha until which changelog is generated . When not provided, latest tag is taken
  13.       --changed-after=CHANGED-AFTER                      Ignore all changes after given date, relative date formats like "-1 day" are also supported
  14.       --changed-before=CHANGED-BEFORE                    Ignore all changes before given date, relative date formats like "-1 day" are also supported
  15.       --tag=TAG                                          List only changes from given release
  16.       --tag-next=TAG-NEXT                                List only changes until given release
  17.       --tag-only-stable                                  Check SemVer stability of all tags and remove all unstable
  18.       --release-name=RELEASE-NAME                        Name of the release when --tag option is not provided [default: "Unreleased"]
  19.       --only-commits                                     Use only commits to generate changelog
  20.       --only-pull-requests                               Use only pull requests to generate changelog
  21.       --compare-reverse                                  When comparing commits, revers the order and compare start to end, instead end to start.
  22.       --format=FORMAT                                    How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
  23.       --theme=THEME                                      Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
  24.       --skip-from=SKIP-FROM                              Skip changes from given author|authors (multiple values allowed)
  25.       --github-release-update                            Update GitHub release description if you have right permissions and release exists
  26.       --github-file-update-path=GITHUB-FILE-UPDATE-PATH  Update changelog file directly at GitHub by reading existing file content and changing related release section. For example: --github-file-update-path=CHANGELOG.md
  27.       --github-file-update-ref=GITHUB-FILE-UPDATE-REF    The name of the commit/branch/tag from which to take file for --github-file-update-path=CHANGELOG.md option. Default: the repository’s default branch.
  28.   -h, --help                                             Display help for the given command. When no command is given display help for the list command
  29.   -q, --quiet                                            Do not output any message
  30.   -V, --version                                          Display this application version
  31.       --ansi                                             Force ANSI output
  32.       --no-ansi                                          Disable ANSI output
  33.   -n, --no-interaction                                   Do not ask any interactive question
  34.       --configuration=CONFIGURATION                      Custom path to the automation.xml configuration file.
  35.       --cache-path=CACHE-PATH                            Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  36.       --github-token=GITHUB-TOKEN                        Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  37.       --github-enterprise-url=GITHUB-ENTERPRISE-URL      Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  38.   -v|vv|vvv, --verbose                                   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  40. Help:
  41.   When no parameters are provided, this command will generate Unreleased change log. Please be careful when using --github-release-update and --github-file-update-path since those options will do changes in project repository.

changelog:generate:all

  1. Description:
  2.   Generate change log for all tags.
  4. Usage:
  5.   changelog:generate:all [options] [--] <project>
  7. Arguments:
  8.   project                                                project name, for example aeon-php/calendar
  10. Options:
  11.       --tag-start=TAG-START                              Generate changelog from given tag, if not provided it starts from the earliest tag
  12.       --tag-end=TAG-END                                  Generate changelog until given tag, if not provided it ends at the last tag
  13.       --tag-skip=TAG-SKIP                                Skip specific tags (multiple values allowed)
  14.       --tag-only-stable                                  Check SemVer stability of all tags and remove all unstable
  15.       --skip-from=SKIP-FROM                              Skip changes from given author|authors (multiple values allowed)
  16.       --only-commits                                     Use only commits to generate changelog
  17.       --only-pull-requests                               Use only pull requests to generate changelog
  18.       --compare-reverse                                  When comparing commits, revers the order and compare start to end, instead end to start.
  19.       --format=FORMAT                                    How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
  20.       --theme=THEME                                      Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
  21.       --github-release-update                            Update GitHub release description if you have right permissions and release exists
  22.       --github-file-update-path=GITHUB-FILE-UPDATE-PATH  Update changelog file directly at GitHub by reading existing file content and changing related release section. For example: --github-file-update-path=CHANGELOG.md
  23.       --github-file-update-ref=GITHUB-FILE-UPDATE-REF    The name of the commit/branch/tag from which to take file for --github-file-update-path=CHANGELOG.md option. Default: the repository’s default branch.
  24.   -h, --help                                             Display help for the given command. When no command is given display help for the list command
  25.   -q, --quiet                                            Do not output any message
  26.   -V, --version                                          Display this application version
  27.       --ansi                                             Force ANSI output
  28.       --no-ansi                                          Disable ANSI output
  29.   -n, --no-interaction                                   Do not ask any interactive question
  30.       --configuration=CONFIGURATION                      Custom path to the automation.xml configuration file.
  31.       --cache-path=CACHE-PATH                            Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  32.       --github-token=GITHUB-TOKEN                        Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  33.       --github-enterprise-url=GITHUB-ENTERPRISE-URL      Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  34.   -v|vv|vvv, --verbose                                   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  36. Help:
  37.   When no parameters are provided, this command will generate changelog for each commit that follows semver semantic.

changelog:release:unreleased

  1. Description:
  2.   Update changelog file by turning Unreleased section into the next release
  4. Usage:
  5.   changelog:release:unreleased [options] [--] <project> <changelog-file-path> <release-name>
  7. Arguments:
  8.   project                                              project name, for example aeon-php/calendar
  9.   changelog-file-path                                  Path to the changelog file from repository root. For example: CHANGELOG.md
  10.   release-name                                         Name of the next release.
  12. Options:
  13.       --format=FORMAT                                  How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
  14.       --theme=THEME                                    Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
  15.       --github-release-update                          Update GitHub release description if you have right permissions and release exists
  16.       --github-file-changelog-update                   Update changelog file by pushing commit to GitHub directly
  17.       --github-file-update-ref=GITHUB-FILE-UPDATE-REF  The name of the commit/branch/tag from which to take file for changelog-file-path argument. Default: the repository’s default branch.
  18.   -h, --help                                           Display help for the given command. When no command is given display help for the list command
  19.   -q, --quiet                                          Do not output any message
  20.   -V, --version                                        Display this application version
  21.       --ansi                                           Force ANSI output
  22.       --no-ansi                                        Disable ANSI output
  23.   -n, --no-interaction                                 Do not ask any interactive question
  24.       --configuration=CONFIGURATION                    Custom path to the automation.xml configuration file.
  25.       --cache-path=CACHE-PATH                          Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  26.       --github-token=GITHUB-TOKEN                      Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  27.       --github-enterprise-url=GITHUB-ENTERPRISE-URL    Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  28.   -v|vv|vvv, --verbose                                 Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  30. Help:
  31.   This command only manipulates the changelog file, it does not create new releases.

changelog:get

  1. Description:
  2.   Get project changelog.
  4. Usage:
  5.   changelog:get [options] [--] <project>
  7. Arguments:
  8.   project                                            project name, for example aeon-php/calendar
  10. Options:
  11.       --github-file-path=GITHUB-FILE-PATH            changelog file path [default: "CHANGELOG.md"]
  12.       --github-file-ref=GITHUB-FILE-REF              The name of the commit/branch/tag from which to take file for --github-file-path=CHANGELOG.md option. Default: the repository’s default branch.
  13.       --sha1-hash                                    Optional display only sha1 hash of the changelog file instead of file content
  14.   -h, --help                                         Display help for the given command. When no command is given display help for the list command
  15.   -q, --quiet                                        Do not output any message
  16.   -V, --version                                      Display this application version
  17.       --ansi                                         Force ANSI output
  18.       --no-ansi                                      Disable ANSI output
  19.   -n, --no-interaction                               Do not ask any interactive question
  20.       --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
  21.       --cache-path=CACHE-PATH                        Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  22.       --github-token=GITHUB-TOKEN                    Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  23.       --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  24.   -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  26. Help:
  27.   When no parameters are provided, this command will generate Unreleased change log. Please be careful when using --github-release-update and --github-file-update-path since those options will do changes in project repository.

tag:list

  1. Description:
  2.   Display all tags following SemVer convention sorted from the latest to oldest
  4. Usage:
  5.   tag:list [options] [--] <project>
  7. Arguments:
  8.   project                                            project name
  10. Options:
  11.       --with-date                                    display date when tag was committed
  12.       --with-commit                                  display commit SHA of tag
  13.       --limit=LIMIT                                  Maximum number of tags to get
  14.   -h, --help                                         Display help for the given command. When no command is given display help for the list command
  15.   -q, --quiet                                        Do not output any message
  16.   -V, --version                                      Display this application version
  17.       --ansi                                         Force ANSI output
  18.       --no-ansi                                      Disable ANSI output
  19.   -n, --no-interaction                               Do not ask any interactive question
  20.       --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
  21.       --cache-path=CACHE-PATH                        Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  22.       --github-token=GITHUB-TOKEN                    Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  23.       --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  24.   -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

workflow:timing:list

  1. Description:
  2.   List project Github actions workflows billable minutes usage in current billing cycle
  4. Usage:
  5.   workflow:timing:list [options] [--] <project>
  7. Arguments:
  8.   project                                            project name
  10. Options:
  11.       --os=OS                                        Show billable minutes for operating systems [default: ["ubuntu","macos","windows"]] (multiple values allowed)
  12.   -h, --help                                         Display help for the given command. When no command is given display help for the list command
  13.   -q, --quiet                                        Do not output any message
  14.   -V, --version                                      Display this application version
  15.       --ansi                                         Force ANSI output
  16.       --no-ansi                                      Disable ANSI output
  17.   -n, --no-interaction                               Do not ask any interactive question
  18.       --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
  19.       --cache-path=CACHE-PATH                        Path to root cache directory, taken from sys_get_tmp_dir() function or AEON_AUTOMATION_CACHE_DIR env variable [default: "/Users/norzechowicz/.automation"]
  20.       --github-token=GITHUB-TOKEN                    Github personal access token, generated here: https://github.com/settings/tokens By default taken from AEON_AUTOMATION_GH_TOKEN env variable
  21.       --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  22.   -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
  24. Help:
  25.   Billable minutes only apply to workflows in private repositories that use GitHub-hosted runners.

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.