Versioning protocol is unclear

[jamesrhester]

It is not clear when the major/minor/patch version numbers should be bumped on DDLm dictionaries. This should be clarified and documented.

This issue was first raised during discussion of #35 .

[jamesrhester]

Up until now, the assumption has been that all dictionaries and templates are under central control and move together in lockstep, making versioning simply a record of changes with no need to ensure compatibility. There are essentially two scenarios to consider: importation of attributes from a single save frame (i.e. template) and importation of an entire dictionary into a 'Head' definition.

In the templating scenario, addition of an attribute to a template save block could duplicate an attribute already in the importing definition. We have currently not defined what should be done in this case during import; logically the template should take lowest precedence, in which case, additions to a template definition should not require a bump in major version number. Removal/change of an attribute in a template block could lead to an importing definition failing to be correct, so should require an increase in major version number.

In theory, we would never make any changes in a non-template dictionary that would require a change in major version number as this would undermine our goal of stable, universal data names. We are probably left with simple rules for full dictionaries, such as:

1. change the patch version for typos, rewording and clarification
2. increment the minor version for all other changes (additions to enumerations, new definitions, changing data names to aliases of new definitions)

[vaitkus]

I agree with your statements, however, a good way to start would be to define what should be consider compatible and incompatible API changes in regards to the CIF dictionaries, dictionary handling software and CIF files. The potential scenarios you provided could than serve an illustration of such changes. I propose this as a starting point:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. The semantics of version numbers follows the guidelines described in the “Semantic Versioning 2.0.0” document.

1. A major level change introduces incompatible changes. Restrictions:
   a) Older software may not be able to process the new dictionary correctly;
   b) Older valid files may become invalid according to the old dictionary;

Example 1: change in the DDL version;
Example 2: changing default values;
Example 3: incompatible data type change;
Example 4: changing category context from looped to unlooped and vice versa;
Example 5: addition of new functionality;
Example 6: major change in an imported file (removal/change of an attribute from a save frame).

2. A minor level change is supposed to introduce improvements, extensions and enhancements that are backwards compatible:
   a) Old files must be valid according to the new dictionary;
   b) New files may become invalid according to the old dictionary;
   c) Old software should be able to process new dictionaries.

Example 1: adding new enumerator values.
Example 2: adding new definitions.
Example 3: changing data names to aliases of new definitions.

3. A patch level change is supposed to correct bugs and introduce changes that are both backwards and forward compatible:
   a) Old files must be valid according to the new dictionary;
   b) New files must be valid according to the old dictionary;
   c) Old software must be able to process new dictionaries.

Example 1: correcting typos;
Example 2: rewording, clarification;
Example 3: compatible data type extension (i.e. Int -> Real, Real -> Text, etc.).

Of course, this is a very rudimentary draft and can be extended/modified as needed. What do you think?

[jamesrhester]

DDLm group discussion yielded some detailed principles. I'll need to put these together into a proper proposal.

[jamesrhester]

Further discussion moved to #141 .