We currently have “master” as current main version in the documentation. But what is “master”? Does it reflect the core “master” which is (currently) the unreleased 10.3-dev or does it reflect the latest release which is 10.2? If it refers to the unreleased master, we could update the docs as soon as a core patch is merged (and requires a change to the documenation). This is good from maintainance perspective. But possibly not from the users perspective because they get documentation for yet unreleased features.
I made a proposal to add an additional branch (latest) for latest release, keep working on master, updating documentation early, but use “latest” as URLs to link to. I think this would require a change on Intercept and is more work in the long run.
A less work-intensive alternative would be to affirm “master” (in docs) as being the equivalent to the core master which would mean it may contain not yet released changes.
Introducing /latest/ and easily be able to switch between the same page for different versions (assuming the title and position did not change between releases) is a good idea imho. And for links we publish ourselves then link to /latest/ instead of master so that it is clear that git-master for code and master for docs have the same meaning.
As maintaining a /latest/ would be more work and I would not want to put more work on the documentation team I would stick with LTS versions + master.
But as for many features currently the most authoritative information seems to be in the ChangeLogs, I would welcome linking those in all possibly affected areas in the documentation! This would make a non-released feature easily identifiable.
The requirement for that would be of course that master’s ChangeLogs are perma-linkable in documentation, which I lack the knowledge if they are already.
we use master in the docs like master in the core: This means it reflects the current not yet released development state. As soon as a patch is merged, the documentation can be changed
we use the “versionadded”, deprecated etc. directives to point out since when a feature exists, since when it was deprecated etc.
we create an issue for each major.minor release in the team repo to keep track of which changes were already made, see example. for 10.3 This gets continously updated, currently by myself, the tools to do this are online.
about linking to the changelogs: Martin Bless came up with a good solution for permalinks to a changelog. This is now documented. This requires, that the link for “core” is added to Settings.cfg. I will do this shortly for the core manuals (“TYPO3 Explained”, etc.)
link to changelog doc:t3core:Changelog/8.1/Deprecation-75625-DeprecatedCacheClearingOptions`
add this to Settings.cfg (replace “master” with version) t3core = https://docs.typo3.org/c/typo3/cms-core/master/en-us/
The suggestion to create a “latest” will have to be postponed for now due to existing workload, but should be revisited some time in the future.