Should Workflow Version also track changes to Steps?

[shaunanoordin]

Discussion & Possible Feature Request

Question: should a workflow's version attribute also keep track of changes to that WF's steps? Currently, the version only keeps track of changes to the workflow's tasks.

My current understanding:

• Assumed purpose: a workflow's version (e.g. exampleWorkflow.version = '12.345' means major version 12, minor version 345) is used by project owners to keep track of which version of the WF (and its questions) that volunteers saw when they submit their classifications.
• The major version number is incremented by 1 every time...
  • A new Task is added to workflow.tasks
  • A Task is removed from workflow.tasks
  • A Task's task.next is changed (i.e. flow of the WF is changed)
  • A branching ('single'-type) Task's answer's task.answers[x].next is changed. (i.e. flow of the WF is changed)
  • workflow.first_task is changed. ~~(untested) ...when workflow.first_task is changed...? Probably? (TODO: Shaun, test this and confirm.)~~ (Update: yup)
• The minor version number is incremented by 1 every time...
  • Any attribute within a Task is edited. (e.g. change task.question for "Do you see a cat?" to "Do you see any feline?")
  • ...except for task.next or task.answers[x].next, which triggers a major version bump.
• ❗ No version changes are observed when the Steps are changed.

Dev Notes

The complication:

• The new Pages Editor on PFE introduces the concept of organising Tasks into Steps (aka Pages) to project owners.
  • Link: example staging WF in the Pages Editor. (Please ping Shaun/Sam/Sean before editing, and for any questions.)
• In certain cases, a workflow can be modified without adjusting the version, which defeats the assumed purpose of the workflow version.
  • e.g. rearranging workflow Steps/Pages doesn't cause a version bump.
  • Note: in most cases however, the Pages Editor will create/delete Tasks alongside creating/deleting Steps, so this problem was masked for a long time.

Testing:

• Open the link above.
• Add a Task (which also adds a Step/Page at the same time). Observe that the major version number increases as expected (because a Task was added.)
• Edit that Task T0 in Step/Page P0, by changing its main question or instruction. Observe that the minor version increases as expected
• Add another Task in another Step/Page, so you have at least 2 pages.
• Rearrange the pages (either via drag & drop, or the sorting arrows). Observe that no version changes happen, which isn't expected. (Examining the workflow resource will show that workflow.tasks remains unchanged, while workflow.steps was updated.)

Thoughts:

• The major version number also should increment when...
  • A new Step is added to workflow.steps
  • A Step is removed to workflow.steps
  • A Step's step.next is changed (or more accurately, step[1].next, due to the nesting arrays)
  • The order of Steps in workflow.steps is changed.
• ❔ I'm not sure if it's the major OR minor version that should change when...
  • A Task is added to a Step. e.g. workflow = { tasks: { T1 }, steps: [ [ 'S1', { taskKeys: [ 'T1' ] } ] ] } ==> workflow = { tasks: { T1, T2 }, steps: [ [ 'S1', { taskKeys: [ 'T1', 'T2' ] } ] ] }
    • (As mentioned, a Task is created at the same as a Step on the frontend, so in practice it'll still trigger a major update in practice.)
  • A Task is removed a Step.
  • The order of Tasks in a Step is changed.

Status

This will eventually affect project owners when the Pages Editor is more widely adopted, but for now there's still time for discussion.

I think the first thing that needs to be done is for someone with more knowledge to check my assumptions, especially (1) the assumed purpose of the workflow version, and (2) whether the major & minor versions are being incremented (and not) as I described.