Improve release notes

[adriangonz]

Right now we generate the release notes automatically from Git's history (using PR titles). However, this information alone may not be enough on some cases. One common example would be breaking changes introduced by the PR (e.g. dependency updates, changes on functionality, naming, etc.).

It would be good to define a process to document these kind of upgrade notes (including breaking changes) so that they also get incorporated on the release notes.

Before deciding on a process, we should research what other open source projects do to compile these notes and to generate the changelogs automatically. Prow may already have an opinion on how to compile and publish breaking changes?

[adriangonz]

/priority p1

[adriangonz]

I've been checking out how does Kubernetes handle this. I've summarised the main points below. What are your thoughts on this process @gsunner?

Adding release notes to PRs

On one hand, when a PR is created, a Prow automation checks if there is a populated block in the PR body such as:

Some public-facing release note.

If there isn't, a Prow automation will label the PR as do-not-merge/release-note-label-needed. The default PR template will already create an empty release-notes block.

Note that some PRs won't need public-facing release notes (e.g. fixes on the integration tests). To disable release notes for a PR, you can use the /release-note-none Prow command.

There are also a few other conventions to flag different types of release notes. This is documented in detail here: https://github.com/kubernetes/community/blob/62300e7e0b066131bfc45721f5042d9db9e14aea/contributors/guide/release-notes.md

Extracting release notes from PRs

On the other hand, at release time they've got some tooling which crawls over all the PRs, extracting the release-notes blocks. These blocks can then be used to generate the final release notes.

[gsunner]

I do like this that by deafult its "do-not-merge/release-note-label-needed" and then you have to "/release-note-none" to merge it.

But does this mean you only add a body to the PR if its "Some public-facing release note."?

[gsunner]

Actually I see the release-note has a particular format, so you can mix normal PR descriptions and ones for the public note.

[adriangonz]

@gsunner I had a go using the Prow plugin and the release-notes tool to generate the changelog. You can check these PRs on the sandbox repo:

• https://github.com/SeldonIO/jenkins-x-seldon-core-sandbox/pull/26
• https://github.com/SeldonIO/jenkins-x-seldon-core-sandbox/pull/27

By default, the release-notes tool uses this template. However, it seems that you bring your own through the --format flag. You can even output JSON and then process it manually.

The default template splits the changelog by kind (using the kind/* labels). It also shows any "action required" change. You can see an example below:

# Release notes for master

[Documentation](https://docs.k8s.io/docs/home)

# Changelog since v10.0.3

## Urgent Upgrade Notes

### (No, really, you MUST read this before you upgrade)

 - You now need to add a `release-notes` block on every PR. ([#27](https://github.com/SeldonIO/jenkins-x-seldon-core-sandbox/pull/27), [@adriangonz](https://github.com/adriangonz))

## Changes by Kind

### Documentation
 - Added `release-notes` plugin. ([#26](https://github.com/SeldonIO/jenkins-x-seldon-core-sandbox/pull/26), [@adriangonz](https://github.com/adriangonz)) [SIG Python]

That was generated running:

release-notes \
	--github-org SeldonIO \
	--github-repo jenkins-x-seldon-core-sandbox \
	--required-author '' \
	--start-rev v10.0.3 \
	--end-rev master \
	--output release-notes.md \
	--release-version v10.1.0

[axsaucedo]

This is really cool. As part of this I would be keen to explore potentially moving to squashed commits, which require having a required structure on the content of the PR which could go into the automated release, not sure if this would still be part of the context of this issue tho?

[axsaucedo]

It also may be worth creating a new pipeline that is focused on releases, such as jenkins-x-release.yaml potentially, such that is triggered manually through jx start pipeline...