[Proposal] Automatic changelog generation

The last needed step to put together a fully-automated release process for this project is to handle CHANGELOG generation.

This is a discussion issue designed to start a conversation on this topic.

Refs elastic/apm-agent-java#991

Proposal

Instead of manually writing and publishing a log of changes on each release, a CHANGELOG.md file would be automatically generated using the GitHub Changelog Generator.

Details

The way the automatic process works is by examining labels and attempting to slot closed issues and merged PRs between given tags into release entries in the CHANGELOG.md file.

Obviously, this means that the project must become very diligent about using labels to correctly identify issues which are bugs and enhancements. It seems that this is mostly the case already, but there is some divergence between what appears in the release notes and what appears when the script is run against the repo as it sits today.

An additional caveat is that when issues are closed without being resolved, labels would need to be updated so that the script does not get confused and think that it means that the issue in question was resolved.

Any label can be excluded, so it should be no problem to exclude meta-issues, if desired.

Handling historical entries

We should likely not disturb the already published CHANGELOG entries, but this should be no problem and we can easily preserve the previous changelog while also switching to automatic generation for future releases.

Putting in custom entries

Of course, not all features or bugs fit correspond directly to an issue. For these, we can create summary issues which the changelog generator will know to look for. This is explained here.

Ensuring things look right

We can make it easy to run the script locally to preview changes before the release process is kicked off or we could include a pause in the automated Jenkins job to inspect the CHANGELOG. (I prefer the first option, for the record.)

Discussion

If this sounds like a reasonable course of action, go ahead and give this a thumbs-up.

Please feel free to inspect the sample output I prepared and compare it to the (actual CHANGELOG)[https://www.elastic.co/guide/en/apm/agent/java/current/release-notes-1.x.html] so you can get a sense of how we would need to label issues and PRs going forward.

If you have questions or concerns, please leave them in comments below. Thanks.

[cachedout]

I think we’ve landed on manually updating the CHANGELOG. This decision is reflected in the way that the release pipeline is currently written.

Therefore, I am going to go ahead and close this issue. Thank you to everybody for a productive discussion.

[cachedout]

That means that when we want to release, the release notes are already ready to be published so it does not slow down the release process.

Sounds good. The automated process is easy to put in place if you ever decide that you want it, but from an automated-release perspective, if we can consider the CHANGELOG already complete by the time we kick off the release process, that’s even easier. 😉