Use-cases

1. Plugin update (version 2.0.0 > version 2.1.0)
2. Plugin migration (quickNav to pageNav)
3. Data corrections (title = displayTitle)

Context

• AAT database json
• Adapt fw json

Considerations

Algorithm must:

• List fromPlugins at which the json was created
• List toPlugins to which json should be migrated
• Keep track of plugin versions for the current state of the json, as versions will tick upwards when each migration step is applied
• !Allow application of schema defaults
  • !Defaults will not be available for interim steps, reconsider?
• Allow highly custom and standard tasks
  • Utilise js instead of json
  • Have a very simple migration script API, perhaps similar to a testing framework
• Provide a summary of json changes
  • A diff per content item should be possible
• Be able to modify all json in the course, adding, removing, updating or deleting properties accordingly

Migration steps must:

• Be able to check the fromPlugins and toPlugins, and data
  • May have rule based version number (=>1.0.0)
• Keep track of the version applied
• Mutate the data
• Check data
• Fail early
• Define tests to pass or fail to validate the migration steps

Todo

Design

• review process of performing a migration (capture, update, migrate)

Issues

• talk about the missing interim schemas
• talk about Journal for undo behaviour in the AAT

Functionality

• Capture and run all languages and not just the first
• Keep track of plugin versions
  • removePlugin({ name: 'quickNav' });
  • addPlugin({ name: 'pageNav'', version: '6.1.0' });
  • updatePlugin({ name: 'adapt-contrib-text', version: '6.1.0' });
• Trap task runs and step runs for output via json or console
• Update whereFromPlugin to use a range rather than <= a single version
  • due to using <= for whereFromPlugin multiple tasks are marked as applicable and only performed in order due to their sequence within the migration file, this could lead to potential issues with tasks not being performed in the correct order.
  • potential issues - If a describe task is stopped with whereContent the migration script will not run updatePlugin and therefore the proceeding tasks will not be applicable, a potential solutions:
    • overlap versions such that two tasks whereFromPlugin range starts with the preceeding update version
    • swap whereContent to wherePlugin which rather than checking if content is present will check if the plugin is part of the course (this would also reduce code duplication throughout the migration scripts)
    • ensure that if a migration task requires an attribute to be included the check for that attribute is carried out within the mutate function rather than whereContent, this ensures that the migration script will always run and always run the updatePlugin function

UI

• need to go through shapeup process to design the AAT process
  1. user clicks update plugins
  2. capture plugins and data
  3. update plugins
  4. tbc
     • select migrations, run, review, skip, cancel etc
     • run migrations, error at failed courses
• [] fail early
• make a pretty terminal output
• allow aat to display changes and answer questions
• handle errors with question, allow to run without ui