Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Versioning protocol is unclear #47

Open
jamesrhester opened this issue Jul 24, 2017 · 3 comments
Open

Versioning protocol is unclear #47

jamesrhester opened this issue Jul 24, 2017 · 3 comments

Comments

@jamesrhester
Copy link
Contributor

jamesrhester commented Jul 24, 2017

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
Copy link
Contributor Author

jamesrhester commented Jul 24, 2017

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
Copy link
Collaborator

vaitkus commented Jul 24, 2017

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).
  1. 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.
  1. 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
Copy link
Contributor Author

jamesrhester commented Jan 7, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants