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

Introduce tooling for upgrade note management

XMLWordPrintable

    • MOODLE_405_STABLE
    • MOODLE_405_STABLE
    • MDL-81125-main-alt
    • Hide

      Setup

      1. Update node dependenceis 

        npm i

      Creation of a new entries

      This is largely a smoke test. Basically have a play. Try some different things.

      Via npm

      1. Run the upgrade note creator via npm: 

        npm run upgradenote

      2. Fill in the various prompts, some things to try:
        1. an issue number which is not in any of the following formats:
          1. \d+
          2. [a-z]-\d+
        2. The text editor
        3. Long text
        4. Adding more than one note for a single issue
      3. Run the upgrade note creator via npm with args: 

        npm run upgradenote -- -h

        NOTE: When running it via npm you {}MUST{} use -- before your args. This is to tell npm that the args are not for it, but for our script

        1. things to try:
          1. Invalid issue numbers 

            npm run upgradenote -- -i XXX
            		 
            npm run upgradenote -- -i XXX-XXX
            		 
            npm run upgradenote -- -i XXX-123-XXX
            		 
            npm run upgradenote -- -i 123-XXX
            		 
            npm run upgradenote -- -i XXX_123

          2. Valid issue numbers: 

            npm run upgradenote -- -i XXX-123
            		 
            npm run upgradenote -- -i 123
            		 
            npm run upgradenote -- -i MDLSITE-1234

          3. Invalid/valid components 

            # Valid:
            		 
            npm run upgradenote -- -i 80085 -c core
            		 
            npm run upgradenote -- -i 80085 -c mod_forum
            		 
            # Rewritten to core_block because the path is both a plugintype and subsytem
            		 
            npm run upgradenote -- -i 80085 -c block
            		 
            # Invalid:
            		 
            npm run upgradenote -- -i 80085 -c XXX
            		 
            npm run upgradenote -- -i 80085 -c core_XXX
            		 
            npm run upgradenote -- -i 80085 -c blocks

          4. Fix type 

            # Valid
            		 
            npm run upgradenote -- -i 80085 -c core_block -t fixed
            		 
            npm run upgradenote -- -i 80085 -c core_block -t improved
            		 
            npm run upgradenote -- -i 80085 -c core_block -t deprecated
            		 
            npm run upgradenote -- -i 80085 -c core_block -t removed
            		 
            npm run upgradenote -- -i 80085 -c core_block -t changed
            		 
            # Invalid
            		 
            npm run upgradenote -- -i 80085 -c core_block -t klasdf

      Via the script

      1. Run the upgrade note creator via node: 

        node .grunt/upgradenotes.mjs create

      2. Run the same smoke tests as above
        Note: You do not need to use -- when running the script directly
        You can do so, but it is not required

      Generation of the upgrade notes summary

      1. Run the summary generator via node: 

        node .grunt/upgradenotes.mjs summary

      2. Find all UPGRADING-CURRENT.md files 

        find . -name UPGRADING-CURRENT.md

        1. Confirm that there is an UPGRADING-CURRENT.md file in the root of the project
        2. Confirm that there is an UPGRADING-CURRENT.md file for each plugin that you've created an upgrade note for
      3. Check the contents of the UPGRADING-CURRENT.md files
        1. Confirm that the contents of the UPGRADING-CURRENT.md file in the root directory contains notes for all components
        2. Confirm that the contents of the UPGRADING-CURRENT.md files for other components contain the notes for that component
      4. Generate a new upgade note for a component you haven't already generated one for
      5. Run the summary again
        1. Confirm that a new UPGRADING-CURRENT.md file was created for that component
        2. Confirm that the contents of the UPGRADING-CURRENT.md file for that component contains the notes for only that component
      6. Delete the newly creaed yml file for that component
      7. Run the summary generator again
        1. Confirm that the UPGRADING-CURRENT.md file for that component was deleted
      8. Re-run specifying a version (this will be used in the release process to generate version-specific docs): 

        node .grunt/upgradenotes.mjs summary 4.5

        1. Confirm that all of the UPGRADING-CURRENT.md files have been updated to include the version number

      Generation of the release-ready upgrade notes

      1. Run the summary generator via node: 

        node .grunt/upgradenotes.mjs release

      2. Find all UPGRADING.md files 

        find . -name UPGRADING.md

        1. Confirm that there is an UPGRADING.md file in the root of the project
        2. Confirm that there is an UPGRADING.md file for each plugin that you've created an upgrade note for
      3. Check the contents of the UPGRADING.md files
        1. Confirm that the contents of the UPGRADING.md file in the root directory contains notes for all components
        2. Confirm that the contents of the UPGRADING.md files for other components contain the notes for that component only
      4. Generate a new upgrade note for a component you haven't already generated one for
      5. Run the summary again
        1. Confirm that a new UPGRADING.md file was created for that component
        2. Confirm that the contents of the UPGRADING.md file for that component contains the notes for only that component
      6. Delete the newly created yml file for that component
      7. Run the generator again
        1. Confirm that the UPGRADING.md file for that component was NOT deleted
      8. Re-run specifying a version (this will be used in the release process to generate version-specific docs): 

        node .grunt/upgradenotes.mjs release 4.4 -d

        1. Confirm that all of the UPGRADING.md files have been updated to include the 4.4dev version number
        2. Confirm that all of the upgrade notes in .upgradenotes have been remove
      9. Generate some new notes for a couple of components 

        node .grunt/upgradenotes.mjs create -i 81125 -c core -t improved -m 'Did some cool stuff'
        		 
        node .grunt/upgradenotes.mjs create -i 81126 -c core_communication -t improved -m 'Did some other stuff'
        		 
        node .grunt/upgradenotes.mjs create -i 81127 -c mod_assign -t improved -m 'Deprecate some old stuff that impacts a subplugin'
        		 
        node .grunt/upgradenotes.mjs create -i 81128 -c core -t improved -m 'Replaced `format_string()` and `format_text()` with `\core\formatting`'
        		 
        node .grunt/upgradenotes.mjs create -i 81129 -c core_question -t improved -m 'Did some cool stuff'

      10. Run the release tool without specifying a version 

        node .grunt/upgradenotes.mjs release

        1. Confirm that the UPGRADING.md files have been updated to include the new notes without impacting the old ones
        2. Confirm that the .upgradenotes directory still has the files
      11. Generate another release note for an existing component 

        node .grunt/upgradenotes.mjs create -i 12345 -c mod_assign -t deprecated -m 'Deprecate some old stuff that impacts a subplugin'

      12. Run the release tool without specifying a version again 

        node .grunt/upgradenotes.mjs release

        1. *Confirm that the UPGRADING.md files have been updated to include the new notes under a version for "4.5dev"
        2. Confirm that the .upgradenotes directory still has the files
      13. Generate another release note for an existing component 

        node .grunt/upgradenotes.mjs create -i 12345 -c mod_assign -t deprecated -m 'Deprecated some other stuff'

      14. Run the release tool specifying a development version: 

        node .grunt/upgradenotes.mjs release 4.4dev

        1. Confirm that the UPGRADING.md files have been updated to replace the "4.5dev" heading with "4.4dev" label
        2. Confirm that the .upgradenotes directory still has the files
      15. Run the release tool specifying a different development version: 

        node .grunt/upgradenotes.mjs release 4.5dev

        1. Confirm that the UPGRADING.md files have been updated to replace the "4.4dev" heading with "4.5dev" label
        2. Confirm that the .upgradenotes directory still has the files
      16. Run the release tool specifying a different stable weekly version: 

        node .grunt/upgradenotes.mjs release 4.4.1+

        1. Confirm that the UPGRADING.md files have been updated to replace the "4.4dev" heading with "4.4.1+" label
        2. Confirm that the .upgradenotes directory still has the files
      17. Run the release tool specifying a the correct dev version (4.5dev):
      18. Run the release tool specifying a different development version: 

        node .grunt/upgradenotes.mjs release 4.5dev

        1. Confirm that the UPGRADING.md files have been updated to replace the heading with "4.5dev" label
        2. Confirm that the .upgradenotes directory still has the files
      19. Now run a real release again 

        node .grunt/upgradenotes.mjs release 4.5 -d

        1. Confirm that all of the UPGRADING.md files have been updated to include the version number
        2. Confirm that all of the upgrade notes in .upgradenotes have been remove
      Show
      Setup Update node dependenceis npm i Creation of a new entries This is largely a smoke test. Basically have a play. Try some different things. Via npm Run the upgrade note creator via npm : npm run upgradenote Fill in the various prompts, some things to try: an issue number which is not in any of the following formats: \d+ [a-z] -\d+ The text editor Long text Adding more than one note for a single issue Run the upgrade note creator via npm with args: npm run upgradenote -- -h NOTE: When running it via npm you { }MUST{ } use -- before your args. This is to tell npm that the args are not for it, but for our script things to try: Invalid issue numbers npm run upgradenote -- -i XXX npm run upgradenote -- -i XXX-XXX npm run upgradenote -- -i XXX-123-XXX npm run upgradenote -- -i 123-XXX npm run upgradenote -- -i XXX_123 Valid issue numbers: npm run upgradenote -- -i XXX-123 npm run upgradenote -- -i 123 npm run upgradenote -- -i MDLSITE-1234 Invalid/valid components # Valid: npm run upgradenote -- -i 80085 -c core npm run upgradenote -- -i 80085 -c mod_forum # Rewritten to core_block because the path is both a plugintype and subsytem npm run upgradenote -- -i 80085 -c block # Invalid: npm run upgradenote -- -i 80085 -c XXX npm run upgradenote -- -i 80085 -c core_XXX npm run upgradenote -- -i 80085 -c blocks Fix type # Valid npm run upgradenote -- -i 80085 -c core_block -t fixed npm run upgradenote -- -i 80085 -c core_block -t improved npm run upgradenote -- -i 80085 -c core_block -t deprecated npm run upgradenote -- -i 80085 -c core_block -t removed npm run upgradenote -- -i 80085 -c core_block -t changed # Invalid npm run upgradenote -- -i 80085 -c core_block -t klasdf Via the script Run the upgrade note creator via node : node .grunt/upgradenotes.mjs create Run the same smoke tests as above Note: You do not need to use -- when running the script directly You can do so, but it is not required Generation of the upgrade notes summary Run the summary generator via node: node .grunt/upgradenotes.mjs summary Find all UPGRADING-CURRENT.md files find . -name UPGRADING-CURRENT.md Confirm that there is an UPGRADING-CURRENT.md file in the root of the project Confirm that there is an UPGRADING-CURRENT.md file for each plugin that you've created an upgrade note for Check the contents of the UPGRADING-CURRENT.md files Confirm that the contents of the UPGRADING-CURRENT.md file in the root directory contains notes for all components Confirm that the contents of the UPGRADING-CURRENT.md files for other components contain the notes for that component Generate a new upgade note for a component you haven't already generated one for Run the summary again Confirm that a new UPGRADING-CURRENT.md file was created for that component Confirm that the contents of the UPGRADING-CURRENT.md file for that component contains the notes for only that component Delete the newly creaed yml file for that component Run the summary generator again Confirm that the UPGRADING-CURRENT.md file for that component was deleted Re-run specifying a version (this will be used in the release process to generate version-specific docs): node .grunt/upgradenotes.mjs summary 4.5 Confirm that all of the UPGRADING-CURRENT.md files have been updated to include the version number Generation of the release-ready upgrade notes Run the summary generator via node: node .grunt/upgradenotes.mjs release Find all UPGRADING.md files find . -name UPGRADING.md Confirm that there is an UPGRADING.md file in the root of the project Confirm that there is an UPGRADING.md file for each plugin that you've created an upgrade note for Check the contents of the UPGRADING.md files Confirm that the contents of the UPGRADING.md file in the root directory contains notes for all components Confirm that the contents of the UPGRADING.md files for other components contain the notes for that component only Generate a new upgrade note for a component you haven't already generated one for Run the summary again Confirm that a new UPGRADING.md file was created for that component Confirm that the contents of the UPGRADING.md file for that component contains the notes for only that component Delete the newly created yml file for that component Run the generator again Confirm that the UPGRADING.md file for that component was NOT deleted Re-run specifying a version (this will be used in the release process to generate version-specific docs): node .grunt/upgradenotes.mjs release 4.4 -d Confirm that all of the UPGRADING.md files have been updated to include the 4.4dev version number Confirm that all of the upgrade notes in .upgradenotes have been remove Generate some new notes for a couple of components node .grunt/upgradenotes.mjs create -i 81125 -c core -t improved -m 'Did some cool stuff' node .grunt/upgradenotes.mjs create -i 81126 -c core_communication -t improved -m 'Did some other stuff' node .grunt/upgradenotes.mjs create -i 81127 -c mod_assign -t improved -m 'Deprecate some old stuff that impacts a subplugin' node .grunt/upgradenotes.mjs create -i 81128 -c core -t improved -m 'Replaced `format_string()` and `format_text()` with `\core\formatting`' node .grunt/upgradenotes.mjs create -i 81129 -c core_question -t improved -m 'Did some cool stuff' Run the release tool without specifying a version node .grunt/upgradenotes.mjs release Confirm that the UPGRADING.md files have been updated to include the new notes without impacting the old ones Confirm that the .upgradenotes directory still has the files Generate another release note for an existing component node .grunt/upgradenotes.mjs create -i 12345 -c mod_assign -t deprecated -m 'Deprecate some old stuff that impacts a subplugin' Run the release tool without specifying a version again node .grunt/upgradenotes.mjs release *Confirm that the UPGRADING.md files have been updated to include the new notes under a version for "4.5dev" Confirm that the .upgradenotes directory still has the files Generate another release note for an existing component node .grunt/upgradenotes.mjs create -i 12345 -c mod_assign -t deprecated -m 'Deprecated some other stuff' Run the release tool specifying a development version: node .grunt/upgradenotes.mjs release 4.4dev Confirm that the UPGRADING.md files have been updated to replace the "4.5dev" heading with "4.4dev" label Confirm that the .upgradenotes directory still has the files Run the release tool specifying a different development version: node .grunt/upgradenotes.mjs release 4.5dev Confirm that the UPGRADING.md files have been updated to replace the "4.4dev" heading with "4.5dev" label Confirm that the .upgradenotes directory still has the files Run the release tool specifying a different stable weekly version: node .grunt/upgradenotes.mjs release 4.4.1+ Confirm that the UPGRADING.md files have been updated to replace the "4.4dev" heading with "4.4.1+" label Confirm that the .upgradenotes directory still has the files Run the release tool specifying a the correct dev version (4.5dev): Run the release tool specifying a different development version: node .grunt/upgradenotes.mjs release 4.5dev Confirm that the UPGRADING.md files have been updated to replace the heading with "4.5dev" label Confirm that the .upgradenotes directory still has the files Now run a real release again node .grunt/upgradenotes.mjs release 4.5 -d Confirm that all of the UPGRADING.md files have been updated to include the version number Confirm that all of the upgrade notes in .upgradenotes have been remove

      At the moment, Moodle has distributed upgrade notes in the form of loosely formatted upgrade.txt files in each subsystem, or component.

      The intent of these notes is to make it easier for a developer writing a plugin for one of these components to find out about API changes in that component that may impact them. Unfortunately most plugins work with a large number of subsystems and there is no centralised location for these, or easy way to quickly search through all of them. This makes discoverability of their content poor. At the time of writing Moodle has 127 distributed upgrade.txt files located.

      In addition, each file differs slightly and they look a bit like markdown (but are not markdown) – for example, there is no hard-and-fast rule about including an MDL issue number, or formatting/indentation/list type.

      Each file is hand-crafted and some files (lib/upgrade.txt) are a pain for integrators and developers alike due to the frequency of merge conflicts – especially when making changes to the core subsystem.

      This issue seeks to improve this situation by:

      • introducing a CLI tool to create upgrade notes
      • requiring an issue number
      • requiring a valid component name
      • requiring a note type (improvement, change, fix, removal, deprecation)
      • saving each upgrade note in their own file to avoid merge conflicts
      • providing tooling to generate an UPGRADING.md file containing all upgrade notes, rather than spreading them around the file system
      • allowing parts of the UPGRADING.md to be updated (replace the unreleased notes)
      • providing tooling to generate a version-specific set of upgrade notes that could be pumped into the moodle developer docs

      See https://youtu.be/X075kRhQ-4M for an example of this in action.

        1. MDL-81125-Generation of the release-ready upgrade notes.png
          MDL-81125-Generation of the release-ready upgrade notes.png
          1.29 MB
        2. MDL-81125-Generation of the upgrade notes summary.png
          MDL-81125-Generation of the upgrade notes summary.png
          634 kB
        3. MDL-81125-via npm.png
          MDL-81125-via npm.png
          966 kB
        4. MDL-81125-via the script.png
          MDL-81125-via the script.png
          470 kB

            dobedobedoh Andrew Lyons
            dobedobedoh Andrew Lyons
            Ilya Tregubov Ilya Tregubov
            Huong Nguyen Huong Nguyen
            Ron Carl Alfon Yu Ron Carl Alfon Yu
            Votes:
            5 Vote for this issue
            Watchers:
            19 Start watching this issue

              Created:
              Updated:
              Resolved:

                Estimated:
                Original Estimate - Not Specified
                Not Specified
                Remaining:
                Remaining Estimate - 0 minutes
                0m
                Logged:
                Time Spent - 4 days, 1 hour, 31 minutes
                4d 1h 31m

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