I propose to put the changelogs for the current master in the final location, e.g. now starting release: 10.4.
The file location will influence the URL. If these are changed, all already generated URLs (which are often linked and indexed in search engines) will be broken.
I know this is documented differently:
New changelog files should usually be added to the typo3/sysext/core/Documentation/Changelog/master directory. If a version is to be released, all files in this directory will be moved to a directory that is named after the release number.
The URLs that are generated in master are now all broken. These have already been indexed in the search engines, linked from decisions and other places.
The major issue I have with this change is that we then have no feasible way to tell what has been proofread.
The workflow a few days prior to release is that all docs are proofread, wording is aligned and tenses are corrected.
Then for each block of proofread documentation, the real docs are updated with a PR on the respective docs repositories.
After that, „final changelogs“ are moved into the respective release folder.
Depending on the amount of changelogs, this process goes through multiple iterations with the master folder acting as the todo list.
To address the issues you mentioned:
Referencing changelog files prior to release should be pointing to a specific commit on either git.typo3.org or github - they could get reverted which would break the link as well.
So it‘s a symptom rather than a cause.
Moved changelog files should be redirected or 404 on purpose because that‘s what actually happened. Automation might help here.
Option B would be to come up with a feasible workflow for the people proofreading the docs prior to release.
Given the amount of small pieces of work, one ticket per Changelog would be overkill, since managing the ticket would often times take longer that the fix on the respective changelog.
Also I think such a new workflow should be discussed with the people actually doing the proofreading so we don‘t risk making their lives harder.
The workflow a few days prior to release is that all docs are proofread, wording is aligned and tenses are corrected.
Then for each block of proofread documentation, the real docs are updated with a PR on the respective docs repositories.
After that, „final changelogs“ are moved into the respective release folder.
@dermattes I have not answered yet because I am trying to clarify some things with Susi and Anja. I think it is better to clarify some open questions, e.g. via Slack call and then get back to my original suggestion here after that.
From what I understood from what you wrote above: The main docs are updated together with the changelog in the core. This is managed by creating chunks of changelogs to update as patches in Gerrit (once a changelog is updated and main docs is updated it is moved from master to release folder). This is not the current practice: most of the changelogs have been moved to 10.3 directory. Most of these are not yet documented.
This is not the scope of this decision, but I guess this decision depends on the workflow in general.
Also, I do not know who is initially “in charge” of updating the “main docs” for the next release. The Core Team? The GmbH? The docs team? And who coordinates this?
That would be very helpful because if it’s not the docs team I can more or less just leave it to someone else.