-
Task
-
Resolution: Done
-
Low
-
None
Policy: Rules on version numbers in upgrade.txt notes
On the 1st of July 2022, it was finalised that:
- Only one version number will be mentioned in section headers of the upgrade.txt notes.
- That version number must correspond to the upcoming version of the branch that the change applies to, except in the case of parallel development where the earlier upcoming major version number will be noted in upgrade.txt.
- In the case where the change applies to multiple branches:
- Version numbers from other branches are not to be mentioned on the section header. Only the version number relevant to the branch will be mentioned on the section header, except during parallel development periods where the version number mentioned will be the version number of the development branch that will be released first.
- Developers have the prerogative to mention the other version numbers the change applies to, but only within the upgrade note itself. Example:
=== 4.1 ===* We fixed a flaw in the API (This was fixed in 4.1, 4.0.2 and 3.11.8).
Voting options
Option A: Only include the version number relevant to the branch. No mention of versions from other branches.
Examples:
- Patch affecting master only (e.g. master = upcoming v4.1):
== 4.1 == - Patch applied to master and stable branches (e.g. master, 4.0, 3.11):
- master:
== 4.1 == - MOODLE_400_STABLE:
== 4.0.2 == - MOODLE_311_STABLE:
== 3.11.8 ==
- master:
- Patch applied only on stable branches and not on master (e.g. 4.0, 3.11):
- MOODLE_400_STABLE:
== 4.0.2 == - MOODLE_311_STABLE:
== 3.11.8 ==
- MOODLE_400_STABLE:
Option B: Include all affected versions in all branches to which the change applies.
Examples:
- Patch affecting master only (e.g. master = upcoming v4.1):
== 4.1 == - Patch applied to master and stable branches (e.g. master, 4.0, 3.11):
== 4.1, 4.0.2, 3.11.8 == - Patch applied only on stable branches and not on master (e.g. 4.0, 3.11):
== 4.0.2, 3.11.8 ==
Option C: Include only versions for stable branches. Just like the "Fix Version" field on the tracker.
Examples:
- Patch affecting master only (e.g. master = upcoming v4.1):
== 4.1 == - Patch applied to master and stable branches (e.g. master, 4.0, 3.11):
== 4.0.2, 3.11.8 == - Patch applied only on stable branches and not on master (e.g. 4.0, 3.11):
== 4.0.2, 3.11.8 ==
—
Original issue description below:
—
There was an internal integrator discussion about this. We need to get it documented (hence creating this issue). But the general principle was
1. Only document the relevant version in the upgrade.txt, not mixed branches
Right
master branch
== 3.1 ==
|
- Changed foo argument in bar
|
MOODLE_30_STABLE
== 3.0.2 ==
|
- Changed foo argument in bar
|
Wrong
master branch
== 3.1, 3.0.2, 2.9.7 ==
|
- Changed foo argument in bar
|
MOODLE_30_STABLE
== 3.1, 3.0.2 ==
|
- Changed foo argument in bar
|
2. Only document relevant changes in third-party library upgrades
My proposal was:
"Document any api changes in third party libraries which would impact developers. It is not necessarily to document an library upgrade when there is no notable api change or it is unlikely impact to Moodle plugins/customisations."
- has been marked as being related by
-
-
- Closed
-