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.