Documentation process improvement

[CyrilleB79]

Issue

PR #15190 as well as PR #15037 introduce many formatting and structure changes in the change log. Given the size of the change log, I understand it and welcome it. However, since there has been various merges from beta to master in 2023.2 dev cycle (and some of them are already quite old), this causes extra work for translators.

Suggestions

To mitigate this issue in the future, I would suggest to the review process as follows:

• More careful reviewing ofr change log spelling and formatting ("Braille" capitalized, key names using code formatting, etc.)
• Do not merge master to beta long before the beta phase of the dev cycle
• Perform a check of the change log before the merge to beta; if some items of the change log need to be grouped together this should be done before this merge if possible.

Of course all these requirements are just nice-to-have and not always possible. E.g. #15013 required a merge of master to beta quite early to be validated.

[seanbudd]

Also, I think it would be helpful for us to announce when the first master to beta merge occurs. In that message make it clear that until a beta is released, the translation strings are subject to change.

Do not merge master to beta long before the beta phase of the dev cycle

I think this is not ideal - an earlier merge presents alpha translators with strings early, so issues or poor phrasing is caught early. It essentially includes translators in the alpha stage, and allows for a partially translated alpha as well. I think it should just be made more transparent as to when translation strings should be considered stable.

[CyrilleB79]

Also, I think it would be helpful for us to announce when the first master to beta merge occurs. In that message make it clear that until a beta is released, the translation strings are subject to change.

Yes, a message on the translators list would be welcome.

Do not merge master to beta long before the beta phase of the dev cycle

I think this is not ideal - an earlier merge presents alpha translators with strings early, so issues or poor phrasing is caught early. It essentially includes translators in the alpha stage, and allows for a partially translated alpha as well.

I think that merging master to beta about two weeks before the beta cycle would be a good compromise between:

• do not merge to early so that there are not too much changes in the translation
• merge early enough so that:
  • catch early poor phrasing or typo issues
  • allow to have a significant part of first beta translated for non-English users, which allows non-English beta users to test the translation.

[seanbudd]

In terms of change of process, the following suggestion is reasonable to incorporate

Perform a check of the change log before the merge to beta; if some items of the change log need to be grouped together this should be done before this merge if possible.

The PR to review documentation exists to catch what was missed in previous reviews of the changelog, so we can't really improve there. We also want to allow translations as early as possible, but we can improve communication around the stability of strings

[seanbudd]

Do you think this issue could be closed now?

[CyrilleB79]

Is all the release process i n releaseProcess.md?

My concern was that grouping/reordering of the items and general review of the change log had been done after translator had worked on it. If possible it should be done before the merge to beta. Of course, subsequent work (corrections, rewording) can also be done again in the beta. But it's important that it is done at least once before the first merge to beta. IMO, this does not appear clearly in the release process; grouping has already been done though for NVDA 2024.1, so you are aware of this in any case.

[seanbudd]

@CyrilleB79 - Public release process notes should all be in that document.

We didn't introduce a hard rule about fixing up changes before merging to beta, but instead there's been other changes that have the same material affect.

We are also releasing betas a lot sooner after the previous release, opting for early betas rather than stabler betas. This means code will only be on beta branch for about a week or so before releasing a beta, because we are aiming for betas 1 week after the previous stable. This isn't the case for API breaking releases though, which will likely have a longer period of a beta branch without a beta released.

We will also be notifying translators of the stability of translations. For example: when merging to beta, notifying them that strings are still unstable, they are translating alpha. When releasing a beta, notifying them that strings are stabler, but more changes should be expected. And then continuing with the standard translation freeze notices for late beta, rc and final release.