Provide an "Unreleased" section in CHANGELOGs to support & organise contributor proposed changes

[xurizaemon]

From @uberhacker last couple PRs we got talking about proposing changes to the CHANGELOG in PRs.

Problem:

1. Contributor PRs should include CHANGELOG entries (per PR template).
2. Current CHANGELOG format places each change details under a release heading, which includes version number and date.
3. Contributors proposing a change cannot know the date or version of the upcoming release the change will appear in.
4. Requiring contributors to provide release information may cause inaccuracy or require fixes to release details.
5. PRs with potentially inaccurate or incorrect information place additional maintenance tasks on Lando core team.

In recent PRs this came up in review (lando/acquia#95 (comment), lando/backdrop#47 (comment)). It's not exactly a roadblock, and but I think it's an opportunity to ensure the default path is straightforward.

Being uncertain about details (eg questions like "Will my change increment the patch, minor or major release?") shouldn't be an impediment to proposing changes. Contributors, esp new ones, may be uncertain or unaware of impact here, and that may add friction / resistance to the process for them.

I propose the addition of an "Unreleased" section at the top of each repo CHANGELOG, per https://keepachangelog.com

PRs can then add changes to the new Unreleased section, and at release time the maintainer inserts the heading above changes in the released version. From the KeepAChangelog website:

Q: How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

• People can see what changes they might expect in upcoming releases
• At release time, you can move the Unreleased section changes into a new release version section.

There are other approaches (from fully embracing Keep a Changelog, or tools which manage the changelog for you). This issue kicks off by presenting the current challenge and a minimal approach to addressing it.

[reynoldsalec]

@xurizaemon I'm down with that.

In the past I've just put "TBD" for the date and left the presumptive version. That way when merging in a PR, all the maintainer has to do is update the date (and, if needed, the release version) in a quick commit from the GitHub interface before making the release. But "Unreleased" is clearer and only involves a minor extra copy/paste/edit for the maintainer.

[xurizaemon]

Great! My proposal here (just so we have something specific to discuss) is the addition of

## Unreleased

at the top of each Lando project's CHANGELOG.md (above the most recent release).

Adopting Keep a Changelog (as a stretch goal?) is IMO a fine idea 😄 it saves Lando team having to make decisions and gives you a well-documented approach, but that's for core team to decide.

[reynoldsalec]

Agreed, ## Unreleased seems like a good practice. If @xurizaemon and @uberhacker have ideas on places in the docs that we should update to reflect that, please put some PRs up for those. Beyond that, it'll probably be up to maintainers to encourage that standard...CHANGELOG edits are definitely one of the more difficult things to enforce on contributors.

I put in a ticket on lando/prepare-release-action to add some automation (per @AaronFeledy's suggestion) that will automatically insert the correct release/date into the CHANGELOG upon a maintainer creating a release; we can discuss that at Tuesday's DevOps Contributor Meeting: lando/prepare-release-action#15

[pirog]

So, i've updated https://github.com/lando/prepare-release-action to automate this.

the tl;dr is that as long as you are using the normal lando plugin settings it should "just work". however, it will not work on the next release you make but all subsequent ones.

If you want to have it work on the next release you need to add the correct tokens at the top of the CHANGELOG.md eg this

## {{ UNRELEASED_VERSION }} - [{{ UNRELEASED_DATE }}]({{ UNRELEASED_LINK }})

every release these will be correctly populated and a new set of tokens will be prepended to the CHANGELOG.md a la this diff

probably safe to close this out but will leave that to @xurizaemon and @reynoldsalec