A sample of vesioning workflow

[liuy97]

Refs #60, @hildeorten, if you have written this similar documentation, please let me know. Here is to create a sample of a practical sample of versioning system. This versioning workflow will help us to evaluate whether versioning system works correctly. In the following table, ID is an integer beginning from 1 for demo. One element always have and only have one ID. "isBusiness" stands for whether a version is a business version.

This workflow has been implemented in the demo in order understand Hilde's design. It can be tested from my github, whose backend is qddt.nsd.no.

Step 1, create a study

ID	Element	Revision	Major	Minor	isBusiness	Rational L1	Rational L2	Change Type
1	Study	0	1	0	Yes	create	create	create

Step 2, update study label

ID	Element	Revision	Major	Minor	isBusiness	Rational L1	Rational L2	Change Type
1	Study	1	1	0	No	MeaningChange	Conceptual improvement	WIP

Step 3, update study description

ID	Element	Revision	Major	Minor	isBusiness	Rational L1	Rational L2	Change Type
1	Study	2	1	0	No	MeaningChange	Conceptual improvement	WIP

Step 4, Save as a Business version

ID	Element	Revision	Major	Minor	isBusiness	Rational L1	Rational L2	Change Type
1	Study	3	1	1	Yes

Step 5, Create a Topic for study

ID	Element	Revision	Major	Minor	isBusiness	Rational L1	Rational L2	Change Type
1	Study	3	1	1	Yes
2	Topic	0	1	0	Yes	create	create	create

[hildeorten]

Issue #75 ref #60 • General comments regarding larger packing structures like Study and Module:

The use of rationale codes as displayed in your system would apply at the Concept level and for other versionable lower level elements question items etc. In contrast to the lower level elements structures like concepts, question items etc., higher packing structures like Study and Module need only a few business versions (even if there will be many revisions of them). The changes made to the Study or Module at the level of the lower elements should preferably be displayed. The user could then version the module by selecting one Change Type ‘Major’ vs. ‘Minor’.

• It should be possible to build an element step by step. For example you enter only the name first and save. This means that content elements should be optional, but at least one should be filled in or changed before a save. The user decides when to save this as a business version. Then the usage of rationale codes are mandatory. Incompleteness of the element may be allowed, but an alert from the machine to the user that the element is not complete may be useful.

• Revisions that are not business versions should always be followed by the rationale code ‘work in progress’, and should not lead to a business version change. Questions:

• Currently the tool one business version has several revisions. It looks to me that the isBusiness attribute you suggest could be one way to distinguish between the business versions and the revisions that has the same version number?
• How woud this work in relation to the late bound in the tool?

• The following EventTypes, and rationale codes at level 1 and 2 should be available in the tool:
Event types:
Create Add content element Remove content element Change Change rationale Level 1: -TypoOrNoMeaningChange (minor version Change rationale Level 2: Orthographical adjustment

• Meaning change Change rationale Level 2:
  • Conceptual improvement
  • Real life change
  • Other purpose

               -WorkInProgress (equals a revision) 

• Please include definitions using tooltip etc. See attached document.

• If several changes is made before one save (batch versioning), users would like to document the changes by using more than one rationale code. See p. 24 in the Common metadata for the three DASISH tools document, p. 24 https://github.com/DASISH/survey-tools-metadata/blob/master/reports/DASISH%203.2%20Towards%20a%20common%20metadata%20understanding%20for%20the%20three%20DASISH%20WP3.2%20tools%202015_01_05_3.pdf. It should be possible to view each change to the element since the last business version and be able to assign more than one rationale code – one for each change. But there should only be one rationale description for each version of the element. See an example at attachment ‘3c.3_Versioning and rationale codes’. • Versioning should not have an own window. It should be possible to do the versioning in the window of each element.

• When an element has been changed the users need to decide about the meaning of a change. Please see the attached document ‘3b.2_Versioning policy for Concepts and Question Items draft v.0.3’.

• Revision: Is this just development – work in progress (Note: ChangeType removal could be regarded as this, but not additions. As elements can be created by building up step by step, an addition of for example a name may be the last thing you do to complete an element = a major business version). Should the tool or the person assign the rationale code for additions? At least the users should be able to see them.
• Version: Is it a version (Minor vs. Major)
• New-based on: Is it now so different that it cannot be viewed as the same element (same ID) any more, but there is still a relationship between this and the original element.
• New: The change is so big that this has to be regarded as a new element, with no based on reference to the original.

It would be a great advantage if the users could select between all these alternatives (revision, version, new-based on and new) from the same window.

3c.3_Versioning and rationale codes.pptx

3b.2_Versioning policy for Concepts and Question Items draft v.0.3.docx

RationaleCode controlled vocabularies_2016-07-08.xlsx

[sarah-city]

Hi. I wanted to add my thoughts to Hilde's suggestions on versioning.

1. I absolutely agree that it should be possible to version within same window as the element being versioned
2. The current rationale codes available for versioning seem to mix up several things including whether somehting is a work in progress or not, the reason/type of change being versioned and "milestone" Milestones are to do with timing and publication - they shouldn't be included under versioning rationale codes
3. I like the suggestion to allow the user to define whether something is a "work in progress" (no new business version required) or ready to be versioned. If we do this though, we will need to be able to see at a glance which elements are still works in progress and will require versioning before publication.
4. I think it makes most sense to make the workflow a two stage process rather than trying to do all in one drop down menu ie. 1) Select the scale of the changes i.e. work in progess vs. version vs. newBasedon [User defined] 2) if applicable (i.,e. if its a version/newBasedon) to give rationale/type of change [User defined] 3) When versioning, whether something is designated a new minor vs. major version will be determined by the rationale code chosen e.g. typo (minor) vs. conceptual improvement (major)?

NB: If the scale of change is so big that something needs to become a new element then presumably we would just enter it as a new element rather than going through the versioning workflow?

1. We discussed with Benjamin and agreed that it probably wouldn't make sense to version categories. Versioning would start with response domains
2. We agreed in Bergen in May that question items repeated from previous ESS rounds (studies) would be designated "Newbasedon" in the new module. I am still not sure how this functionality is intended to work? Would it require a special rationale code?

(In general what is the workflow for creating a repeat module?)

1. The option to add comments to versioning decisions/rationales is good and should be retained
2. How am I able to view previous versions of an element? Can we set it up so that I click on that version in the history and it pops up? Would be good to be able to select a particular version - and comments associated with that version - to review.

[sarah-city]

Hi Yong.

Here are ESS HQ comments on the versioning workflow. We like this a lot - thank you.

Sarah Comments on versioning demo available 010816.docx

[liuy97]

• [x] We would like to change “save as revision” to “save as work in progress”
• [x] “save as version” needs a lower case v
• [x] “Rational L1” should be labelled “Rationale L1”
• [ ] a summary of the overall change (Refs #99)
• [ ] We would like to organised so that revisions and versions of an element are grouped together
• [ ] access the full history of an element and trace back through the different business versions

The other feedback is listed here:

A couple of questions re workflow:

1. Presumably, once the basic set up is agreed this will be integrated into the main workflow for all versionable elements i.e. replace the current versioning functionality available for each concept, question item etc?
2. We like that designating something a new item/new item based on automatically creates a new element in the list which can then be clicked on and edited. Where do these new/new based on elements appear in the module hierarchy? Presumably if we create a “new” question item, it will appear nested under the same concept as the original question item? Similarly, if we create a “new based on” subconcept, it will appear nested under the same top level concept as the original?

Versioning Policy

We still need to agree:

• Exactly which elements will be versioned
• How/whether versioning one element affects versioning of higher level elements (probably not – all manual?)
• A final list of rationale codes
• When/how often things will be versioned

[hildeorten]

@liuy97 @StigNorland

Regarding a couple of questions re workflow.

1. Stig, is Yongs versioning demo possible at the backend?
2. Ad 2: See #116

Regarding the action points with tick boxes, last box, see attachment Suggestion for how a versioning history may look like.docx

[StigNorland]

It is not possible in the backend. (L1 and L2)

[hildeorten]

@StigNorland @liuy97

Would this be possible if the list is constructed as a flat list as in the examples below? MeaningChange.ConceptualImprovement MeaningChange.RealLifeChange MeaningChange.OtherChange

Would keys which contain separated meaning content like the below be supported by the back end? Based on this, could a front end similar to that of Yong be possible?

[liuy97]

Yes, the list can be listed as a lat construction.

[hildeorten]

VersionDemo+ho-1.docx Save type5.docx

@liuy97 @StigNorland

To finalise the versioning system:

Please find the following attached:

• A list of Vertioning rationale codes with terms and definitions
• An improvement of the layout of the Versioning Demo Please get back with comments, B and H.

[BenjaminNSD]

Last comment was moved to #63