Sync (and improve) Agent release notes

[bmorelli25]

Description of the issue

Follow up issue from the July 17th APM Agent weekly meeting. It was brought up that each Agent has a different way of documenting a release. Some use a changelog, some use release notes, and some use a hybrid of the two:

• Go Agent -- Changelog: CHANGELOG.md -> Releases
• Java Agent -- Release notes with headings Features, Bug Fixes, and Breaking changes: CHANGELOG.md -> Releases
• .NET Agent -- Release notes with headings New features, Bug fixes, and Breaking changes: Releases
• Node.js Agent -- Changelog: CHANGELOG.md. Releases has no information.
• Python Agent -- Release notes with headings New Features, Bugfixes, Breaking changes, and Other changes: CHANGELOG.md -> Releases
• Ruby Agent -- Release notes with headings Fixed, Added, Changed: CHANGELOG.md. Empty Releases.
• RUM Agent -- Hybrid with headings Bug Fixes, Features, Performance Improvements, Breaking changes: CHANGELOG.md. Releases link back to changelog.

@nehaduggal realized that it can be difficult to read through and understand what has changed in some of these changelogs/release notes.

What we are voting on

Syncing Agent release notes to use a similar style and to publish in the same location. Here's one possible solution:

• Agents publish release notes on the GitHub release page. This page will then be linked to from each Agent's documentation. Go, Java, .NET, and Python are already doing this. I think some teams automate releases, so I'd be curious to hear how this would impact you.
• Agents publish release notes instead of changelogs. Release notes are typically more human readable, provide headers for easy scanning (like New features, Bug fixes, and Breaking changes), and may even have a sentence or two at the beginning that highlights the important changes in the release. .NET, Java, and Python have good examples of what this looks like. I can also provide some sort of template to help with this process.

---

@elastic/apm-agent-devs, thoughts? Part of https://github.com/elastic/apm-dev/issues/425.

[gregkalapos]

👍

I think the proposal is good, and unifying this is a good idea - having human readable release notes is in my opinion super useful. In case we go with that, do we wanna also unify the headings?

Also 1 thing that was brought up is that currently release notes are linked from the documentation, but they are not part of it - I personally think this is not an issue and I’d prefer having those on GitHub - just copying would be not that easy, since GitHub uses MD and in docs we use AsciiDoc.

[felixbarny]

One other option I have seen is to have the release notes in the documentation (in asciidoc) and link to them from the GitHub releases page. The downside is that users have to do one more click and might not bother to do so when looking at the mail sent by GitHub when they subscribe to "Releases only". Having the actual release notes in that mail is just ever so slightly more convenient.

[watson]

In the Node.js agent, we use a changelog formatted a bit like proper release notes:

We publish an edited version of the git history with focus only on the changes that a user might care about: New features, bug fixes, breaking changes and performance improvements - all clearly marked as such and with links to the relevant PR's. We don't, however, do much rewriting compared to what's already in the commit messages, though we try to always make the commit messages as relevant to the user as possible.

I think it would be great to use the "Releases" feature of GitHub and link to that from the documentation and from the CONTRIBUTING.md file and I'm sure we can find a way to semi-automate this so it fits into our current release process 👍

[bmorelli25]

Awesome, thanks for the feedback everyone! Based on the thumbs and comments, seems like everyone so far is on board with the plan.

Also 1 thing that was brought up is that currently release notes are linked from the documentation, but they are not part of it - I personally think this is not an issue and I’d prefer having those on GitHub - just copying would be not that easy, since GitHub uses MD and in docs we use AsciiDoc.

One other option I have seen is to have the release notes in the documentation (in asciidoc) and link to them from the GitHub releases page. The downside is that users have to do one more click and might not bother to do so when looking at the mail sent by GitHub when they subscribe to "Releases only". Having the actual release notes in that mail is just ever so slightly more convenient.

I agree with both of these statements. I'm not sure the extra work you would have to put in is worth having release notes in the documentation. I think linking directly from the release notes section to the releases page is good enough, at least for now. We can always reassess in the future.

having human readable release notes is in my opinion super useful. In case we go with that, do we wanna also unify the headings?

I think that would make sense, especially since everyone seems to be using similar terms already. Thomas' suggestion seems to be inline with that: New features, Bug fixes, Breaking changes, and Performance improvements.

[felixbarny]

One benefit of having the release notes inside of the normal documentation as asciidoc is the ability to properly link from the release notes to the corresponding documentation. We kinda transitioned away from linking from the release notes to the GitHub PRs in favor of linking to the actual documentation in case it's a new feature. Firstly, that ensures that we actually have documentation for new features. secondly, it probably more useful to users who are less interested in the thought process and commits behind the feature but rather care about how to actually enable/use it.

Not saying that this is not possible with having the release notes on the GitHub releases page as markdown but there is no validation that the links are and will remain valid. Also, there can be timing issues. For example, before the actual release, you'll have to link to the master version of the documentation. But after the release, you'd probably want it to be fixed to the 1.x branch, for example. We'd get that for free when the release notes are just a part of the regular documentation.

Having said all that, the point of having the actual release notes in the GitHub release email notification still holds strong.

[hmdhk]

In the RUM agent we have multiple packages each of which have their own changelog. on each release we manually aggregate the items from those change logs into the top level change log.

I slightly prefer having the release notes in a md doc in the repo instead of the Github releases and linking to it from the release page. Using the asciidocs is also equally better than using the github release page. the main reason would to have the release notes in the format of a document which is easier to edit and review.

[bmorelli25]

One benefit of having the release notes inside of the normal documentation as asciidoc is the ability to properly link from the release notes to the corresponding documentation

the main reason would to have the release notes in the format of a document which is easier to edit and review.

Both are great points. Gil mentioned we also have telemetry on documentation, so that may be another reason to add release notes to the docs.

For this option, we (I) could rename each Agent's CHANGELOG.md file to CHANGELOG.asciidoc and update the format from markdown to asciidoc. We'd then include this file in the docs build.

The only added complexity comes when you branch to a new version. Care would need to be taken to ensure the right release notes remain on the correct branch. Not a super big deal, but one worth mentioning.