Kura Release notes generation

Kura Release notes generation

Our Kura release notes are automatically generated by a Github Action which relies on the git-changelog-lib project. This tools can generate release notes documents by parsing the commit history leveraging the Conventional Commit specification.

Here you'll find the instructions on how to generate the Release Notes using the above mentioned Github Action.

Commit not following the Conventional Commit specification will not be rendered correctly in the release notes. You will find them in the Changelog section without the correct description and you’ll need to manually add them to their respective section.

First commit of a new release

Rule: “The first commit of a new release corresponds to the commit following the branching of the previous release.”

Note: This rule will result in duplicated commits between the previous release and the new one due to how we manage backports, i.e. commits backported to the previous release will appear in the changelog of both the new and previous release. We decided to accept this because:

1. This allows us to adopt a simple and straightforward rule for selecting the first commit of a new release and avoid the need to manually check for which commit was backported or not.
2. Since we squash backported commits the commit hash is different and thus we (technically) don’t have duplicated commits in the release notes.

Example:

We can programmatically retrieve the commit by issuing the following command (only supported for bash and zsh, sh doesn’t support the <() operator):

diff -u <(git rev-list --first-parent develop)  \  
    <(git rev-list --first-parent release-7.1.0) | \ 
    sed -ne 's/^ //p' | head -1

More details on the subject can be found here

Instructions

Requirements:

• The release branch is already upticked and ready for release (no -SNAPSHOT qualifier).

Go in the "Actions" menu of the repo for which you'd like to generate the release notes.

Select the "Release Notes automation" workflow

Click on "Run workflow" and you'll be greeted by a small form

The workflow needs three parameters:

• Use workflow from: the target release branch to use for generating the Release Notes and where the Pull Request will be opened.
• Starting commit: the commit (not inclusive) from which to start generating the Release Notes. See First commit of a new release
• Overwrite: will dictate whether the action will completely overwrite the current content of the release notes file (i.e. RC1 release notes) or it will migrate the current content (i.e. RC2+ release notes).

When you're ready you can press the "Run workflow" button. The Action will open a new Pull Request containing the Release Notes on the desired branch.

You can then add any manual change by updating this PR.

Warning: while manually editing the release notes take into account that the automation requires no newline inside the handwritten sections.

The sections to manually edit are only three:

• Description
• Target Environments
• Known Issues

Example

Let's say we want to generate the release notes for the Kura 5.1.2 version. We'll need to set the parameters as follows:

• Use workflow from: release-5.1.0 since this is the release branch for the 5.1.* version
• Starting commit: 0c002eb17beb4921abb3cc1d64eaf1a57a7a6e54 since this is the last commit of the previous version (5.1.1).
• Overwrite: checkbox needs to be ticked since this is the first RC. For successive RCs leave the checkbox unticked.

You might find it easier to navigate the commit history from the Github WebUI since it provides a useful “Copy the full SHA" button.

⚠️ Note: For this to work on branch others than the default one the release notes action needs to be backported to the desired branch. Failing to do so will generate an error during the workflow run because of the missing configuration files (the files inside .github/release_notes_templates)