Standardizing release notes across APM agents and APM server

[marclop]

Problem statement

While we're currently generating the APM Agents and APM Server release notes in ASCIIDoc format, and making them available in the docs webpage, there is no alignment or consensus over how they are generated and what the content is.

A side effect for some projects (like apm-server and apm-agent-go) is that a few PRs might be modifying the same file and line and on merging to master, the PR suddenly has merge conflicts, while it is not world-ending, it's much nicer to have a way to add a release note about a change which won't generate merge conflicts for pending PRs.

We'd like to change that and have a more standardized and agreed upon release notes format, content and generation process.

Broad solution

A maintainable and scalable changelog generation solution should take into account all the problems described above and solve them in a non-disruptive automated or semi-automated manner. There's to major requirements for the changelog generation process.

Non-conflicting changelog entries

A project's contributor should be able to add a release note about a change without creating merge-conflicts for existing pending changes. Release notes should contain information that's relevant to the consumers of the product and not necessarily all the implementation details of the change.

The process should allow for changeslog entries at any time although the preferred workflow should be to merge them with the code changes.

Ideally, the changelog's contents should be on every commit per version branch. This reduces the chance to experience merge conflicts when a change is merged to a branch.

Standardized format

A project's team should be able to define the exact format of a release changelog to match the specific project's requirements, headlines or content. Entries should be aggregated into a final changelog file.

Additional context

There is some prior / ongoing work in different teams:

• Elasticsearch: Implement new changelog process elasticsearch#67335
• Cloud-sdk-go changelogger: https://github.com/elastic/cloud-sdk-go/tree/master/cmd/changelogger
• Cloud: private.

[felixbarny]

I'm supportive of this proposal. If you feel strong enough about it, I propose you try this out in the Go agent. If the experiment is successful there, we can roll it out to more and eventually all agents.

[basepi]

Relevant: https://github.blog/2021-10-04-beta-github-releases-improving-release-experience/

Docs: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration