Automatically add the changes from each PR to the release notes in a file.
Install this GitHub action by creating a file in your repo at .github/workflows/latest-changes.yml
.
A minimal example could be:
name: Latest Changes
on:
pull_request_target:
branches:
- main
# Or use the branch "master" if that's your main branch:
# - master
types:
- closed
# For manually triggering it
workflow_dispatch:
inputs:
number:
description: PR number
required: true
jobs:
latest-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: docker://tiangolo/latest-changes:0.0.3
with:
token: ${{ secrets.GITHUB_TOKEN }}
Note: you can also use the GitHub action directly intead of with Docker, but that would take an extra minute:
# - uses: docker://tiangolo/latest-changes:0.0.3
# This is slower but also works
- uses: tiangolo/latest-changes:0.0.3
In this minimal example, it uses all the default configurations.
After merging a PR to the main branch, it will:
- Find a file
README.md
- Inside of that file, find a "header" with the text:
### Latest Changes
...including the two breaking lines.
- Right after that, it will add a new list item with the changes:
- Using the title from the PR.
- Tip: make sure the PR has the title you want before merging it.
- Including the PR number, with a link to the PR itself.
- Including the PR author, with a link as well.
- Using the title from the PR.
It will look something like:
You can see an example of how it works in this same file, at the bottom, in Latest Changes - Latest Changes π€·.
- Then it will commit the changes, and push them to your repo. π
As the changes are simply written to a file in your repo, you can later tweak them however you want. You can add links, extend the information, remove irrelevant changes, etc. β¨
For this GitHub Action to work automatically, the workflow file has to be in the repository before the PR is created, so that the PR also includes it. That's just how GitHub Actions work.
Nevertheless, if you have some PRs that were open before adding this GitHub Action to your project and you still want to use it, you can create workflows manually. It will take the PR number, and then it will do the rest automatically.
You can "dispatch" a workflow/run from the "Actions" tab:
- Select this GitHub Action with the name you used, e.g. "Latest Changes".
- Click on "Run Workflow".
- It will ask you for the PR number and do all the rest.
So, in those cases, it won't do everything automatically, you will have to manually start it and set the PR number. But it can still save you from most of the work, and from a bunch of human errors. π€ π
You can configure:
latest_changes_file
: The file to modify with the latest changes. For example:./docs/latest-changes.rst
.latest_changes_header
: The header to look for before adding a new message. for example:# CHANGELOG \n\n
.template_file
: A custom Jinja2 template file to use to generate the message, you could use this to generate a different message or to use a different format, for example, HTML instead of the default Markdown.debug_logs
: Set to'true'
to show logs with the current settings.
A full example, using all the configurations, could be as follows.
You could have a custom Jinja2 template with the message to write at ./.github/workflows/release-notes.jinja2
containing:
This changed: {{pr.title}}. Done by [the GitHub user {{pr.user.login}}]({{pr.user.html_url}}). Check the [Pull Request {{pr.number}} with the changes and stuff]({{pr.html_url}}). now back to code. π€
Note: you can use any location in your repository for the Jinja2 template.
Tip: The pr
object is a PyGitHub PullRequest
object, you can extract any other information you need from it.
Notice that the Jinja2 template has 2 trailing newlines. Jinja2 we need one so that the next message shows below, instead of the same line, and Jinja2 eats one π€·, so we put 2.
Then you could have a workflow like:
name: Latest Changes
on:
pull_request_target:
branches:
- master
types:
- closed
workflow_dispatch:
inputs:
number:
description: PR number
required: true
jobs:
latest-changes:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: tiangolo/latest-changes:0.0.3
with:
token: ${{ secrets.GITHUB_TOKEN }}
latest_changes_file: docs/release-notes.md
latest_changes_header: '# Release Notes\n\n'
template_file: ./.github/workflows/release-notes.jinja2
debug_logs: true
In this custom config:
- The main branch is
master
instead ofmain
. - It uses the GitHub action directly:
tiangolo/latest-changes:0.0.3
instead of with Docker:
docker://tiangolo/latest-changes:0.0.3
Note: that would make every run about 1 min slower, but you can do that if you prefer it π€·.
- It modifies the file
docs/release-notes.md
instead of the defaultREADME.md
. - It looks for a header in that file with:
# Release Notes
Note: The latest_changes_header
is a regular expression. In this case it has two newlines, and the mesage will be added right after that (without adding an extra newline).
So it will generate messages like:
# Release Notes
* This changed: β¨ Add support for Jinja2 templates for changes notes. Done by [the GitHub user tiangolo](https://github.com/tiangolo). Check the [Pull Request 23 with the changes and stuff](https://github.com/tiangolo/latest-changes/pull/23). now back to code. π€
And that Markdown will be shown like:
- This changed: β¨ Add support for Jinja2 templates for changes notes. Done by the GitHub user tiangolo. Check the Pull Request 23 with the changes and stuff. now back to code. π€
Note: if you use the default of ### Latest Changes\n\n
, or add one like the one in this example with two newlines, this GitHub action will expect the two newlines to exist. But if your release notes are empty and the file only contains:
# Release Notes
then this action won't be able to add the first message. So, make sure the latest changes file has the format expected, for example with the two newlines:
# Release Notes
- Lastly, it will show a lot of debugging information.
- π Update Python module name to latest_changes to avoid conflicts with any repo directory "app". PR #37 by @tiangolo.
- π Fix default Jinja2 path in Action yaml. PR #38 by @tiangolo.
- β¨ Check if the latest changes message was already added before adding it. PR #35 by @tiangolo.
- π Add docs for running manually, with a workflow dispatch. PR #34 by @tiangolo.
- β¨ Refactor and add support for triggering with workflow dispatch events. PR #32 by @tiangolo.
- π Fix basic example in README, include checkout step. PR #31 by @tiangolo.
- π Add note about updating the PR title. PR #30 by @tiangolo.
- π Fix internal latest changes, use a custom header so it doesn't break the examples. PR #29 by @tiangolo.
- π Fix default action config for template file. PR #28 by @tiangolo.
- β¨ Add support for Jinja2 templates for changes notes. PR #23 by @tiangolo.
- π₯ Remove unnecessary note from release notes. PR #22 by @tiangolo.
- π₯ Remove unnecessary note from latest changes. PR #21 by @tiangolo.
- π§ Update tmate config keys. PR #20 by @tiangolo.
- π Update tmate config for keys. PR #19 by @tiangolo.
- βοΈ Fix incorrect URL. PR #18 by @tiangolo.
- π Try to secure tmate. PR #17 by @tiangolo.
- π Update release notes URLs. PR #16 by @tiangolo.
This project is licensed under the terms of the MIT license.