Edit the docs release plan

[ptgott]

Change the process for updating CHANGELOG.md to reflect the one that we use when preparing releases.

[camscale]

How is the changelog on master used? When doing releases, we never touch master. Looking at the changelog on master, it seems to mostly have draft release notes for the upcoming release, so right now it has draft v18 release notes. When v18 is cut from master v18 will have those release notes, but so will master. There will be a period of time that master will not have the next version release notes - I expect draft release notes may not come for months.

Do we need to differentiate between a just cut release branch for the first alpha release and the first actual release on that branch?

Should the changelog on a release branch contain only entries for that major version? That is, should we start a new release branch with the draft release notes only for that upcoming release which then get updated to published release notes when the release is made? And then just add release notes for that major release to that branch's changelog?

[ptgott]

How is the changelog on master used?

On the current docs site, the master changelog is visible at a URL path similar to /docs/ver/18.x. On the previous docs site (based on gravitational/docs), we would only display the changelog for the default docs version. We haven't added logic to the docs build to use a single version of the changelog like we have for the Upcoming Releases page.

Do we need to differentiate between a just cut release branch for the first alpha release and the first actual release on that branch?

I don't think so. Once we publish the first actual release on a major version, we change the default version of the docs site: there's already a distinction between the edge version (which can include alpha releases) and the default docs version.

Should the changelog on a release branch contain only entries for that major version? That is, should we start a new release branch with the draft release notes only for that upcoming release which then get updated to published release notes when the release is made? And then just add release notes for that major release to that branch's changelog?

The docs site only shows the edge version (master), the latest supported major version, and the previous two major versions. If we were to include a changelog only for entries under each version of the docs site, only four versions (included master) would be included in the changelog, and a user wouldn't be able to see changes included in EOL versions.

That said, we could only include release notes for a single version of the changelog on the appropriate version of the docs site, then provide instructions for navigating to the changelog on an EOL release branch.

Would it make sense to rephrase the paragraph as:

  For example, if we cut `branch/v20` from `master`, the `CHANGELOG.md` on
  `branch/v20` must end with `v20` release notes. `master` can end with draft notes
  for changes that will likely be included in the upcoming release.

[camscale]

The first sentence of that paragraph means each release branch has only changelog entries for that major version, which as you say means "a user wouldn't be able to see changes included in EOL versions." Do we need to do something about that? (see below)

For updating master, I suggest we say something like the CHANGELOG.md on master should be updated with a heading for the next major version under which features can be added during development on master.

We have the preflight checklist for cutting a new release branch, so this just needs to be an item to be added to roll the master changelog to the next version.

WRT EOL versions, perhaps we could append the freshly EOL version's changelog to the subsequent release's changelog? So when looking at the v15 changelog now, it would go all the way back to v1. When we release v18 and stop supporting v15, we add the v15 changelog to the end of the v16 changelog. That way there is a complete changelog available and we don't need to worry about maintaining concurrent changelogs across branches as we maintain those releases.

[ptgott]

I'll add the suggested wording re: master, thanks!

One issue with regard to adding the newly EOL changelog to the subsequent releases's changelog is that we'd need to work out a way to make the EOL changelog discoverable. I'm not sure this is straightforward, but I'm happy to work on ways to make this work.

I might make sense to save the work on EOL versions for a separate PR so we can take care of it when we have a plan to make the EOL changelog discoverable.

[ptgott]

@camscale Just checking to see if you were planning to give the discussion in this PR another look. Thanks!

[camscale]

Just checking to see if you were planning to give the discussion in this PR another look. Thanks!

@ptgott Sorry, it slipped past. Replied above in thread.