Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-4418

Some Upgrade.txt guidelines

    XMLWordPrintable

Details

    • Task
    • Resolution: Done
    • Low
    • Coding style
    • None

    Description

      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 ==

      • 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 ==

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

      Attachments

        Issue Links

          Activity

            People

              Dates

                Created:
                Updated:
                Resolved:

                Clockify

                  Error rendering 'clockify-timesheets-time-tracking-reports:timer-sidebar'. Please contact your Jira administrators.