aeon-php/automation

在“keep a changelog”格式（或不是）下，自动更新项目变更日志，在提交/标签/发布/拉取请求后

维护者

详细信息

github.com/aeon-php/automation

源代码

问题

安装: 84

依赖项: 0

建议者: 0

安全: 0

星标: 61

关注者: 3

分支: 3

开放问题: 6

1.0.4 2023-10-03 17:44 UTC

Requires

Requires (Dev)

MIT d5c5862f9893999cd755dd0e59271a5af5c4561f

  • Norbert Orzechowicz <norbert.woop@orzechowicz.pl>

This package is auto-updated.

Last update: 2024-09-23 04:32:41 UTC

README

命令行应用程序，可以在每次提交/拉取请求/标签/发布后自动更新项目的变更日志文件

目录

为什么？

虽然周围有类似且更受欢迎的项目，但为什么选择这个？自动化旨在为项目所有者提供更多关于变更日志生成过程的灵活性和控制。

  • 新增
  • 更改
  • 修复
  • 移除
  • 弃用
  • 安全

这些类型是keep a changelog注记的一部分。

根据定义，拉取请求描述易于更新/更改，一旦提交合并，生成变更日志时，就很容易回到特定的PR，修复它并得到更好的变更日志输出。

如果拉取请求没有预期的描述呢？那么自动化将回退到提交消息，但即使在这里，它也会首先尝试查找conventional commit注记，如果失败，则查找常见的词首如Fix、Added、Removed。

如果您仍然对“keep a changelog”主题持怀疑态度？没问题，自动化还支持更经典的方法，只需使用--theme=classic选项。

如果有人仍然更愿意使用提交消息而不是拉取请求？不用担心，--only-commits选项就是为他准备的，就像--only-pull-requests选项是为另一方准备的。

将这个

Pull Request

变成这个

Pull Request

何时？

不确定自动生成变更日志是否适合您？

  • 具有稳定发布周期、遵循SemVer的软件
  • 持续集成和持续交付（CI/CD）

这些都是两个最流行的用例。

发布开源项目时，您可能需要查看--tag选项，该选项将获取给定标签和之前标签之间的所有更改，并生成变更日志。

当在一个每天发布多次且没有可预测发布周期的项目上工作时，您可能希望存储最后一次部署的提交SHA哈希，稍后通过--commit-end选项传递。自动化可以为您生成自上次发布以来的变更日志。

如何？

示例

为存储库生成完整变更日志

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"

为存储库生成完整变更日志 ⚠️ 更新CHANGELOG.md文件和所有发布 ⚠️

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"

为存储库生成未发布更改

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

为特定标签生成变更日志

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"

为了生成变更日志，自动化需要4个步骤。

目前，自动化直接从GitHub获取整个项目历史，但将添加更多来源。

1) 检测更改范围

在生成变更日志时，自动化首先尝试理解变更的范围。默认情况下，它从默认分支的顶端获取信息，并寻找最新的标签（从语义版本控制的角度来看）。当然，这可以通过使用--tag选项告诉自动化从特定的标签开始，或者更精确地，通过提供起始和结束提交SHA，使用--commit-start和--commit-end。

还有两个选项可以帮助设置正确的范围，--changed-after和--changed-before，它们也支持相对格式，如--changed-after=noon或--changed-after="-1 day"。

2) 获取项目历史

当检测到范围后，自动化将获取从源中更改的历史。这一切都是从提交开始的，并且它与git log origin..HEAD命令非常相似。当获取提交时，自动化会拉取所有Pull Requests，因为它们也包含有关更改的有价值的数据（可以使用--only-commits选项跳过）。并非所有贡献都值得提及，有时你可能想要排除来自机器人的更改。--skip-from选项使可以跳过特定作者的更改。

3) 分析项目历史

自动化遵循Keep a Changelog哲学，并且可以识别以下类型的更改

  • 添加
  • 更改
  • 已弃用
  • 删除
  • 修复
  • 安全

有几个策略使得这种识别成为可能

它们按照给定顺序应用，直到第一个解析更改源并正确检测所有更改。

4) 格式化变更日志

当所有更改都被检测并按类型分组后，自动化进入最后一步，即生成变更日志。

格式

自动化支持以下变更日志格式

  • markdown
  • html

主题

自动化支持以下主题

  • keepachangelog
  • classic

所有主题都支持所有格式。

keepachangelog

此主题遵循Keep a Changelog规范，更改按类型组织。

classic

此主题不按任何特定方式组织更改，每个更改都作为一条单独的行项目显示，并按更改日期排序。与--only-pull-requests选项结合使用将提供干净、有序的经典更改列表，该列表来自pull request标题。

安装

在开始之前，生成您自己的GitHub个人访问令牌。它可以作为环境变量AUTOMATION_GH_TOKEN提供，或通过CLI选项--github-token提供。

如果自动化没有按预期工作，请增加详细程度以查看其内部的工作方式。可以通过提供以下选项之一来实现

  • -v - 正常
  • -vv - 详细
  • -vvv - 调试

Docker

docker pull aeonphp/automation
docker run -t --rm aeonphp/automation --help

Composer

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

Phar

待办：即将推出

由于自动化使用GitHub API获取项目历史，因此您可以将其用于任何流行的GitHub项目。

automation changelog:generate organization/name -v

贡献

在寻找贡献的方式？太棒了 ❤️ 以下是一些可以开始的地方

您也可以随时打开问题，如果这个项目中的任何内容让您感到烦恼。

文档

命令

aeon-automation

Usage:
  command [options] [arguments]

Options:
  -h, --help                                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                        Do not output any message
  -V, --version                                      Display this application version
      --ansi                                         Force ANSI output
      --no-ansi                                      Disable ANSI output
  -n, --no-interaction                               Do not ask any interactive question
      --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help                            Displays help for a command
  list                            Lists commands
 branch
  branch:list                     List project branches
 cache
  cache:clear                     Clears all or specific caches.
 changelog
  changelog:generate              Generate change log for a release.
  changelog:generate:all          Generate change log for all tags.
  changelog:get                   Get project changelog.
  changelog:release:unreleased    Update changelog file by turning Unreleased section into the next release
 milestone
  milestone:create                Create new milestone for project
  milestone:list                  
 pull-request
  pull-request:description:check  Check if pull request has changes in expected by Automation format.
  pull-request:list               
  pull-request:template:show      Display pull request template required by this tool to properly parse keepachangelog format
 release
  release:list                    List all project releases
 tag
  tag:list                        Display all tags following SemVer convention sorted from the latest to oldest
 workflow
  workflow:job:list               List project Github actions jobs status from the latest workflow run

changelog:generate

Description:
  Generate change log for a release.

Usage:
  changelog:generate [options] [--] <project>

Arguments:
  project                                                project name, for example aeon-php/calendar

Options:
      --commit-start=COMMIT-START                        Optional commit sha from which changelog is generated . When not provided, default branch latest commit is taken
      --commit-end=COMMIT-END                            Optional commit sha until which changelog is generated . When not provided, latest tag is taken
      --changed-after=CHANGED-AFTER                      Ignore all changes after given date, relative date formats like "-1 day" are also supported
      --changed-before=CHANGED-BEFORE                    Ignore all changes before given date, relative date formats like "-1 day" are also supported
      --tag=TAG                                          List only changes from given release
      --tag-next=TAG-NEXT                                List only changes until given release
      --tag-only-stable                                  Check SemVer stability of all tags and remove all unstable
      --release-name=RELEASE-NAME                        Name of the release when --tag option is not provided [default: "Unreleased"]
      --only-commits                                     Use only commits to generate changelog
      --only-pull-requests                               Use only pull requests to generate changelog
      --compare-reverse                                  When comparing commits, revers the order and compare start to end, instead end to start.
      --format=FORMAT                                    How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
      --theme=THEME                                      Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
      --skip-from=SKIP-FROM                              Skip changes from given author|authors (multiple values allowed)
      --github-release-update                            Update GitHub release description if you have right permissions and release exists
      --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
      --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.
  -h, --help                                             Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                            Do not output any message
  -V, --version                                          Display this application version
      --ansi                                             Force ANSI output
      --no-ansi                                          Disable ANSI output
  -n, --no-interaction                                   Do not ask any interactive question
      --configuration=CONFIGURATION                      Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL      Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                                   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  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

Description:
  Generate change log for all tags.

Usage:
  changelog:generate:all [options] [--] <project>

Arguments:
  project                                                project name, for example aeon-php/calendar

Options:
      --tag-start=TAG-START                              Generate changelog from given tag, if not provided it starts from the earliest tag
      --tag-end=TAG-END                                  Generate changelog until given tag, if not provided it ends at the last tag
      --tag-skip=TAG-SKIP                                Skip specific tags (multiple values allowed)
      --tag-only-stable                                  Check SemVer stability of all tags and remove all unstable
      --skip-from=SKIP-FROM                              Skip changes from given author|authors (multiple values allowed)
      --only-commits                                     Use only commits to generate changelog
      --only-pull-requests                               Use only pull requests to generate changelog
      --compare-reverse                                  When comparing commits, revers the order and compare start to end, instead end to start.
      --format=FORMAT                                    How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
      --theme=THEME                                      Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
      --github-release-update                            Update GitHub release description if you have right permissions and release exists
      --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
      --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.
  -h, --help                                             Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                            Do not output any message
  -V, --version                                          Display this application version
      --ansi                                             Force ANSI output
      --no-ansi                                          Disable ANSI output
  -n, --no-interaction                                   Do not ask any interactive question
      --configuration=CONFIGURATION                      Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL      Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                                   Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  When no parameters are provided, this command will generate changelog for each commit that follows semver semantic.

changelog:release:unreleased

Description:
  Update changelog file by turning Unreleased section into the next release

Usage:
  changelog:release:unreleased [options] [--] <project> <changelog-file-path> <release-name>

Arguments:
  project                                              project name, for example aeon-php/calendar
  changelog-file-path                                  Path to the changelog file from repository root. For example: CHANGELOG.md
  release-name                                         Name of the next release.

Options:
      --format=FORMAT                                  How to format generated changelog, available formatters: "markdown", "html" [default: "markdown"]
      --theme=THEME                                    Theme of generated changelog: "keepachangelog", "classic" [default: "keepachangelog"]
      --github-release-update                          Update GitHub release description if you have right permissions and release exists
      --github-file-changelog-update                   Update changelog file by pushing commit to GitHub directly
      --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.
  -h, --help                                           Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                          Do not output any message
  -V, --version                                        Display this application version
      --ansi                                           Force ANSI output
      --no-ansi                                        Disable ANSI output
  -n, --no-interaction                                 Do not ask any interactive question
      --configuration=CONFIGURATION                    Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL    Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                                 Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  This command only manipulates the changelog file, it does not create new releases.

changelog:get

Description:
  Get project changelog.

Usage:
  changelog:get [options] [--] <project>

Arguments:
  project                                            project name, for example aeon-php/calendar

Options:
      --github-file-path=GITHUB-FILE-PATH            changelog file path [default: "CHANGELOG.md"]
      --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.
      --sha1-hash                                    Optional display only sha1 hash of the changelog file instead of file content
  -h, --help                                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                        Do not output any message
  -V, --version                                      Display this application version
      --ansi                                         Force ANSI output
      --no-ansi                                      Disable ANSI output
  -n, --no-interaction                               Do not ask any interactive question
      --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  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

Description:
  Display all tags following SemVer convention sorted from the latest to oldest

Usage:
  tag:list [options] [--] <project>

Arguments:
  project                                            project name

Options:
      --with-date                                    display date when tag was committed
      --with-commit                                  display commit SHA of tag
      --limit=LIMIT                                  Maximum number of tags to get
  -h, --help                                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                        Do not output any message
  -V, --version                                      Display this application version
      --ansi                                         Force ANSI output
      --no-ansi                                      Disable ANSI output
  -n, --no-interaction                               Do not ask any interactive question
      --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -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

Description:
  List project Github actions workflows billable minutes usage in current billing cycle

Usage:
  workflow:timing:list [options] [--] <project>

Arguments:
  project                                            project name

Options:
      --os=OS                                        Show billable minutes for operating systems [default: ["ubuntu","macos","windows"]] (multiple values allowed)
  -h, --help                                         Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                        Do not output any message
  -V, --version                                      Display this application version
      --ansi                                         Force ANSI output
      --no-ansi                                      Disable ANSI output
  -n, --no-interaction                               Do not ask any interactive question
      --configuration=CONFIGURATION                  Custom path to the automation.xml configuration file.
      --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"]
      --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
      --github-enterprise-url=GITHUB-ENTERPRISE-URL  Github enterprise URL, by default taken from AEON_AUTOMATION_GH_ENTERPRISE_URL env variable
  -v|vv|vvv, --verbose                               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  Billable minutes only apply to workflows in private repositories that use GitHub-hosted runners.

集成请求

如果您想将自动化集成到您的项目中，但不确定如何操作，请随时打开集成请求。
我们将首先测试您的项目，如果可能，准备一个集成Pull Request。