release-notes-assistant

Release notes assistant

Create or update release notes from the pull requests and store them in a file or a milestone. A preview can be added to an open pull request.

The unit of change is the pull request: each of them is mentioned in the release notes. By default the title of the pull request is used. If a longer line is needed, it can be added to the release-notes/<PR>.md file.

Anatomy of the release notes

Each line in the release notes is included in a category and starts with a link to the pull request and a link to the original in case of a backport. The Forgejo v7.0.6 milestone is a complete example and includes:

• User Interface features
  • PR (backported): Replace vue-bar-graph with chart.js
  • PR: Update of translations from Weblate

Release note lines

From file

If a release-notes/<PR>.md file is found in the development branch (as specified by the --branch-development option), each line it contains will be included in the release notes, with a link to the pull request by the same number. This is convenient for instance when upgrading a dependency that contains multiple indpendent changes.

From the pull request title

If no release-notes/<PR>.md file is found, the title of the pull request is used as a release note line.

Storage

File

This is the default --storage-location /tmp/release-notes-7.0.6.md.

Milestone

Use a milestone designated by name:

release-notes-assistant \
   --forgejo-url https://codeberg.org \
   --repository forgejo/forgejo \
   --token $RNA_TOKEN \
   --storage milestone --storage-location 'Forgejo v7.0.6' \
   release v7.0.6

The content of the milestone is preserved.

Pull request

Use a pull request designated by its number.

release-notes-assistant \
   --forgejo-url https://codeberg.org \
   --repository forgejo/forgejo \
   --token $RNA_TOKEN \
   --storage pr --storage-location 4612 \
   preview 4612

The content of the pull request description is preserved and the release notes added to the end. If it is changed, a comment is added to notify the users watching the pull request about the change.

Category

Conventional commits

Category of each line is loosely based on convention commits.

• feat!: features including breaking changes
• bug!: bug fixes including breaking changes
• feat: features
• bug: bug fixes
• everything else: other

Custom

The --categorize option is a script to figure out the category of one release note line. The stdin is a JSON file and the output is expected to be a single line that starts with a rank followed by a category name. For instance the following is the Breaking bug fix category with rank 01:

01 Breaking bug fix

Manual editing

release-notes-assistant reads the existing release notes from a previous run, if any. If a line has been manually edited, it will be preserved. That is only the content that shows between the <!--description--> HTML comments.

<!--description TmFtZSBjb25hbiByZW1vdGUgZm9yZ2Vqbw==-->the line manually edited<!--description-->

Everything else, between <!--start release-notes-assistant--> and <!--end release-notes-assistant-->, will be replaced on each run.

Backports

The commits of a selected pull request are examined for messages that contain the (cherry picked from commit XYZ) pattern. If any is found and the commit it contains belongs to a known pull request, it is considered to be a backport from that pull request.

Selecting pull requests

The pull requests of the repository are listed, most recently created first. It is selected if it has been merged and the closest tag to the merged SHA (either squashed or merged) is the tag of the release.

However, a pull request that has been backported is not going to be selected because it was included in the release to which it was backported instead.

Configuration file

A number of options are the same for a given repository and can be stored in a configuration file because they do not need to be changed each time release-notes-assistant is called. For instance the options relevant to Forgejo are in the .release-notes-assistant.yaml file.

categorize: './release-notes-assistant.sh'
branch-development: 'forgejo'
branch-pattern: 'v*/forgejo'
branch-find-version: 'v(?P<version>\d+\.\d+)/forgejo'
branch-to-version: '${version}.0'
branch-from-version: 'v%[1]d.%[2]d/forgejo'
tag-from-version: 'v%[1]d.%[2]d.%[3]d'
branch-known:
  - 'v7.0/forgejo'
cleanup-line: 'sed -Ee "s/.*?:\s*//g" -e "s;\[(UI|BUG|FEAT|v.*?/forgejo)\]\s*;;g"'
render-header: |

  ## Draft release notes
comment: |
  <details>
  <summary>Where does that come from?</summary>
  The following is a preview of the release notes...
  </details>

  %[1]s

And it can be used with release-notes-assistant --config .release-notes-assistant.yaml ....

Token

The advised scope is:

• issues: read & write
• repository: read & write
• if used in a team, pull requests: read & write

Alternatives

• git-cliff - is based on commit messages which are immutable and does not support backports.

Hacking

git clone --recurse https://code.forgejo.org/forgejo/release-notes-assistant
cd release-notes-assistant
./tests.sh rna_start
./tests.sh rna_fixture
xgd-open https://0.0.0.0:3000 # user root password admin1234
TEST_OPTIONS='-v -run=TestForgejo' ./tests.sh rna_check
./tests.sh rna_stop

To debug a problem without reloading everything on each run, the --workdir option can be used to cache the clone of the repository and the list of pull requests.