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

How to write upgrade.txt



    • Task
    • Resolution: Duplicate
    • Minor
    • None
    • 3.4
    • Policy
    • None


      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.


        Issue Links



              stronk7 Eloy Lafuente (stronk7)
              marina Marina Glancy
              2 Vote for this issue
              9 Start watching this issue




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