Discussion List Archives

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[ddlm-group] Dictionary versioning

  • To: ddlm-group <ddlm-group@iucr.org>
  • Subject: [ddlm-group] Dictionary versioning
  • From: James Hester <jamesrhester@gmail.com>
  • Date: Mon, 24 Jul 2017 15:58:40 +1000
  • DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025;h=mime-version:from:date:message-id:subject:to;bh=h4Y5Zqp0AD6UGUln1GqjE7NapAb5h9yfNxoa8uhzSiY=;b=Y8Dp0e0RzsZ/QB5lDYoBtJeglYwZiQUwZbDB6Iz1cVLcv+66Lx74YHKWFg+POLcfT1Y1Mm7Lhy8O+gooLnvGAP7b0MJwPGjobKMTl+FwxyzniWsXMESJB7aTW3aDfcWfjnnTItexNzbo6UZSzXQNEQ7K9z74fS3onHpjQoENflHUqUGYJnFHzmFAJuCqVbo+Vul/ln8RJGcUy9DQ4zx9pxz8r0OLSZ2vG2rw1f44IjJw7ksFIijiqCRInc7HiWo8yCH0qct5pv9f2RUp+8bPmbl7iF6lYrqSWtgL7I3OFpp6CdQfhx9Vzo1Ezm5H2Blb0GJM3jp0FrzasFGElQlR8w==
Dear DDLm group,

The vagueness of dictionary versioning has been raised as an issue (see https://github.com/COMCIFS/cif_core/issues/47). Now that dictionaries can import template dictionaries, it becomes possible that the template dictionary could change in ways that would render the main dictionary incorrect, for example, if a necessary attribute was removed from the template definition.  Such fiddling with template attributes has recently been proposed (see https://github.com/COMCIFS/cif_core/issues/42) as a solution to certain technical issues.

While COMCIFS will obviously endeavour to maintain both template dictionaries and main dictionaries as a compatible whole, we should come up with some principles for versioning to guide authors and editors, as well as authors of dictionary checking software.  I suggest that we use semantic versioning of the form <major>.<minor>.<patch>, where a change in the major version number is required when incompatible changes are introduced.

There are two situations that are important: importing pieces of a definition from a template dictionary, and importing a whole dictionary in order to build on it. 

Versioning in template dictionaries: Firstly, there has been no explicit statement of how importation should treat the presence of the same attribute in both the template and the importing definition - I suggest the simple principle that the value in the importing definition always has precedence over the imported value. Assuming this, a template dictionary will be potentially incompatible with an importing dictionary if attributes are removed from a definition, a definition is itself removed, or the value of an attribute is changed in a way that would change the behaviour of software.  Either of these three changes would require an increase in the major version number of a template dictionary.  Other changes are covered by the rules below for full dictionaries.

Versioning in full dictionaries: we never make any changes in a domain dictionary that would require a change in major version number as this would undermine our goal of stable, universal data names. We are then left with simple rules for changing the non-major version numbers in both full and template dictionaries:
  1. change the patch version for typo correction, rewording and clarification
  2. increment the minor version for all other changes: additions to enumerations, new definitions, moving data names to aliases of new definitions
Feel free to respond either on the github issue or here.

T +61 (02) 9717 9907
F +61 (02) 9717 3145
M +61 (04) 0249 4148
ddlm-group mailing list

Reply to: [list | sender only]
International Union of Crystallography

Scientific Union Member of the International Science Council (admitted 1947). Member of CODATA, the ISC Committee on Data. Partner with UNESCO, the United Nations Educational, Scientific and Cultural Organization in the International Year of Crystallography 2014.

International Science Council Scientific Freedom Policy

The IUCr observes the basic policy of non-discrimination and affirms the right and freedom of scientists to associate in international scientific activity without regard to such factors as ethnic origin, religion, citizenship, language, political stance, gender, sex or age, in accordance with the Statutes of the International Council for Science.