Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-58879

How to write upgrade.txt

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Open
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: 3.4
    • Fix Version/s: None
    • Component/s: Policy
    • Labels:
      None
    • Affected Branches:
      MOODLE_34_STABLE

      Description

      During development cycle we put various notes for developers in various upgrade.txt
      They are not well organised, there are many locations and it becomes confusing for plugin developers where to look for information.
      For 3.3 everything was summarized here: https://docs.moodle.org/dev/Moodle_3.3_release_notes#Upgrading_plugins

      Let's once and forever agree on what goes in upgrade.txt, which files to use and refer to this policy in the future.

      Question 1. Which upgrade.txt to use?

      What we have currently:
      1. Notes about changes in core APIs, deprecations, etc. go to lib/upgrade.txt
      2. Notes about changes in some core APIs, however, go to their personal upgrade.txt, for example, tag/upgrade.txt, media/upgrade.txt, cache/upgrade.txt and even admin/upgrade.txt
      3. Notes about changes in individual plugin types go to the parent directory of this plugin type, for example: question/type/upgrade.txt , course/format/upgrade.txt , mod/upgrade.txt , etc.
      4. Notes about changes in individual plugins go to the upgrade.txt in this plugin, for example mod/forum/upgrade.txt , admin/tool/behat/upgrade.txt , etc.

      Notes in #1 should be read by all plugin devs during upgrade. Notes in #2 should be read by almost all plugins devs during upgrade if they remember to do it. Notes in #3 should be read by devs of plugins of this type. Notes in #4 should be read by devs of plugins that depend on this plugin or use its methods.

      Question 2. Format in lib/db/upgrade.txt

      Currently we use a list that becomes several pages long by the time of release, it is not sorted, not categories and hard to read.

      Question 3. What exactly should we mention in upgrade.txt

      I think this is clear - only notes to developers, no information for admins, teachers or students should go here.

      Deprecations, API changes and new features are all mixed together in this list. Perhaps we can discuss how to distinguish them.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              Unassigned Unassigned
              Reporter:
              marina Marina Glancy
              Participants:
              Component watchers:
              Adrian Greeve, Andrew Lyons, Eloy Lafuente (stronk7), Juan Leyva, Jun Pataleta, Sander Bangma
              Votes:
              2 Vote for this issue
              Watchers:
              8 Start watching this issue

                Dates

                Created:
                Updated: