[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
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:
James.
Reply to: [list | sender only]
[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:
- change the patch version for typo correction, rewording and clarification
- increment the minor version for all other changes: additions to enumerations, new definitions, moving data names to aliases of new definitions
--
T +61 (02) 9717 9907
F +61 (02) 9717 3145
M +61 (04) 0249 4148
F +61 (02) 9717 3145
M +61 (04) 0249 4148
_______________________________________________ ddlm-group mailing list ddlm-group@iucr.org http://mailman.iucr.org/cgi-bin/mailman/listinfo/ddlm-group
Reply to: [list | sender only]
- Follow-Ups:
- Re: [ddlm-group] Dictionary versioning (Bollinger, John C)
- Prev by Date: Re: [ddlm-group] Character sets in DDLm attribute dictionary
- Next by Date: Re: [ddlm-group] Dictionary versioning
- Prev by thread: Re: [ddlm-group] Standardising inter-block linking
- Next by thread: Re: [ddlm-group] Dictionary versioning
- Index(es):