docs: show latest updates in changelog

[mmcallister]

Changelog does not show the latest changes by default:

https://goteleport.com/docs/changelog/

Selecting the updated version (or older) on the version selector in any of the doc pages does not change this behavior, as the preferences are stripped form the URL when going to the changelog. We have to manually edit it which does not result in a good user experience.

https://goteleport.com/docs/ver/17.x/changelog/

[zmb3]

This is probably as much a developer process issue as it is a docs issue.

We try to minimize the number of PRs that have to be merged in order to cut a release, so that means that:

• the latest changelog info for v15 is on branch/v15
• the latest changelog info for v16 is on branch/v16
• the latest changelog info for v17 is on branch/v17
• the master branch's changelog is rarely updated

In order to show the latest info for all supported releases in the docs (assuming we don't change our release process in any way), we might need some sort of pre-publish step that combines the content of CHANGELOG.md on the 3 supported branches.

[ptgott]

Related: #32790

[mmcallister]

cc @webvictim

[mmcallister]

I think the previous versions are fine, but In reference to the feedback from Gus:

the changelog doesn't have a version selector. as such, i kinda feel like this page ought to show the latest (i.e. v17) changelog instead of the v16 one.

It seems we could just create a redirect to the latest. Right now we are prioritizing the changelog for those who are on cloud vs self-hosted/OSS users. Could we just update the banner that now says:

This documentation is for a version of Teleport that is only available for self-hosted clusters.

to

The <latest version> documentation is for a version of Teleport that is only available for self-hosted clusters.

[zmb3]

I think a docs reader should be able to find the changelog for all currently-supported versions of Teleport on our website.

Ideally this is done without a version selector of any kind and you see a single changelog page that lists everything.

A version selector is suboptimal, but also acceptable. (We used to have one, but removed it because pages like "Upcoming releases" and "Changelog" are meant to be version agnostic.)

[webvictim]

I am fine with whatever means that when you click on "Changelog", you see the details of the latest self-hosted release.

[ptgott]

Just to clarify, how much are we prioritizing past releases that are missing from the changelog? Here are the Teleport release versions with no corresponding section in the CHANGELOG (as of #50780, which merges the changelogs of our currently supported release branches):

$ RELEASES=$(gh release list --limit 1000000000 | grep -Eo "v[0-9]+\.[0-9]+\.[0-9]+" | tr -d "v" | sort -u)
$ echo "$RELEASES" | xargs -I{} bash -c 'grep -q {} CHANGELOG.md || echo {}' | wc -l
184

This is quite a lot!

In terms of keeping the changelog up to date, we have a release plan item to update the changelogs when we publish a new release.

[mmcallister]

@zmb3 thoughts on Paul's Q? This is a lot of material to add. Should we just focus on updating going forward?

[zmb3]

I don't think we need to show all previous releases, as we can always reference the full changelog in git.

Maybe we show all releases for the "current" major version (ie whatever the latest cloud-deployed version is), and the most recent 5 or so releases for the other currently-supported branches?

[camscale]

If the goal is to have a single unified changelog in the docs, then I think we'll need some automation around it. When we cut a release on a release branch, we create a single PR for that release and add a changelog for just that release to the branch.

How's this idea:

Each branch contains a changelog of just that version. So the v17 changelog starts at 17.0.0 and has only v17 changes. Likewise for v16 and v15. This makes the changelog for that release branch relevant to just that branch.

A post-release workflow takes the updated changelog from the release branch and combines it with the others and publishes a unified changelog on master. So master has the changelog back to the beginning of Teleport, which would be kind of expected for someone coming to the github repository. The docs can publish the master version if we want the entire changelog history there, or if we do version-based changelog pages, it could show just the changelog for that version.

The post-release workflow should also have a workflow_dispatch trigger so it can be manually invoked for those times when the changelog is updated for documentation purposes - we can easily regenerate the version on master that way.

This makes the master changelog fully generated and should not be edited by hand. All the release branch changelogs are updated as we do releases and there is only a single place for each version's changelog.