Adoption of Changelog Enforcer GitHub Action in Autoware Repositories

[xmfcx]

Checklist

• [X] I've read the contribution guidelines.
• [X] I've searched other issues and no duplicate issues were found.
• [X] I've agreed with the maintainers that I can plan this task.

Description

To improve the management and tracking of changes across the Autoware repositories, I propose the adoption of the Changelog Enforcer GitHub Action. This action will ensure that every pull request includes a changelog update, helping us maintain a clear and consistent record of changes.

We will also enforce the https://keepachangelog.com/en/1.0.0/ format.

We aim to start this with the autoware.universe repository and, if successful, expand to other repositories like autoware_launch and autoware_msgs.

Purpose

The primary goals of implementing this action are:

1. Ensuring Consistency: Each PR should contribute to the changelog, making it easier to track changes over time.
2. Improving Transparency: Clear documentation of changes enhances transparency for both developers and users.
3. Simplifying Release Process: With quarterly releases planned using CalVer, a well-maintained changelog will streamline the release process.

Possible approaches

1. Gradual Implementation: Start with autoware.universe, assess the effectiveness, and then proceed to other repositories.
2. Automate Changelog Entries: Utilize the Changelog Enforcer to automate the inclusion of changelog updates in PRs.
3. Quarterly Sync with CalVer: Align the changelog updates with our quarterly CalVer release cycle, ensuring that each release has a comprehensive changelog.
4. Centralized Changelog for Main Autoware Folder: Compile changes from the child repositories' changelogs into the main Autoware folder's changelog for each release.

Definition of done

• [ ] Agreement on the adoption of the Changelog Enforcer GitHub Action.
• [ ] Successful implementation and testing in the autoware.universe repository.
• [ ] Development of a clear guideline for contributors on how to update the changelog.
• [ ] Establishment of a process for syncing the main Autoware folder's changelog with child repositories.
• [ ] Review and adjust the process after the first quarterly release cycle.

cc. @mitsudome-r @yukkysaito @isamu-takagi @TakaHoribe

[xmfcx]

github-changelog-generator

There is also an automated way of doing it using github-changelog-generator.

• It generates CHANGELOG.md files like this.
• Related Github Action: https://github.com/marketplace/actions/generate-changelog

Github Releases

There is also Github Releases.

• automatically-generated-release-notes

I will investigate these options more and also share my findings. Please don't hesitate to add your inputs.

---

Edit:

---

semantic-release

https://github.com/semantic-release/semantic-release#-semantic-release

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package.

clerk

This is my favorite so far. :sparkling_heart:

Clerk ensures that release notes can be generated from PRs by looking for a release note in the PR description. You can add a note to your PR by adding a single line to its description beginning with notes:.

• https://github.com/electron/clerk
• https://github.com/apps/release-clerk

Example Changelog: https://github.com/electron/electron/releases

Example PR: https://github.com/electron/electron/pull/40536

This looks like the best mix of automation and manual provision. The developers don't need to touch the CHANGELOG.md file.

Developers just use the commit messages with the Conventional Commit style as usual and just add Release Notes section for each PR and rest is automated.

[xmfcx]

https://github.com/googleapis/release-please#release-please

Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects.

https://github.com/google-github-actions/release-please-action

Example CHANGELOG: https://github.com/googleapis/gapic-generator/blob/master/CHANGELOG.md

[TakaHoribe]

@xmfcx I strongly support this activity. Moreover, it should be linked with future releases of Autoware.

One question: is it required to modify the changelog file in all PRs? Or, the changelog is updated automatically from the PR's description?

[xmfcx]

@TakaHoribe thank you!

is it required to modify the changelog file in all PRs? Or, the changelog is updated automatically from the PR's description?

For the https://github.com/marketplace/actions/changelog-enforcer mentioned in the first issue, you must manually edit the changelog.

But if we use https://github.com/googleapis/release-please#release-please then it is completely automated (from Commit Message.

It generates ChangeLogs like this: https://github.com/googleapis/gapic-generator/blob/master/CHANGELOG.md

release-please seems very popular and also maintained by Google(?) for now it is the most promising option. And it requires the least additional effort from the contributors.

[shmpwk]

@xmfcx Interesting investigation! Actually, we TIER IV has already automated changelog here. They are created by generate-changelog CI which wraps git-cliff. I'm curious if changelog-enforcer and other changelog generator are better than our current automated changelog.