Put changelogs in current release not in "master" directory but in directory for release?

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.

https://docs.typo3.org/c/typo3/cms-core/master/en-us/Changelog/Howto.html

Current problems

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.

Disadvantages

I see no disadvantages in changing this.

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.

Ah, ok. I was not aware of this.

To address the problem of having a todolist for the changelog, I created an issue per release. This can be checked off: Documentation updates related to Changelog 10.3 · Issue #845 · TYPO3-Documentation/TYPO3CMS-Reference-CoreApi · GitHub

We talked about this with Susi during initiatives week.

If the workflow is as you describe above and I understood you correctly, this is something that is not really necessary.

Could you clarify for me what you mean by „if the workflow is as you describe“?

As for your last sentence: What exactly do you mean by „something that is not necessary“?

@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.

@dermattes We are currently not on the same page about the workflow.

  • my latest information: an issue is created on GitHub for each release with a todo item (checkbox) for each changelog, e.g. https://github.com/TYPO3-Documentation/T3DocTeam/issues/121
  • 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.

See

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.