version number of NeXus definitions: need to be able to change this

[prjemian]

Currently, a change in the version number will likely cause problems with the validation of both NXDL files and data files. We need to identify exactly what are the problems and then address them with a method to make it easier to change the version and document for each NXDL what is the compatilibity.

[prjemian]

from cmake_include/nxdl_release.cmake:

Be VERY judicious about updating NXDL_MAJOR_RELEASE and/or NXDL_MINOR_RELEASE
They are used to define the XML namespace for the NXDL files.
This namespace is used in:

• NXDL documents
• NeXus data file validation
• XSLT transformations
• XSD specifications
• SCH specifications
• client source code files
• examples in the manual
• possibly other places, as well

[prjemian]

references on versioning in XML Schema:

• http://www.xfront.com/Versioning.pdf
• https://www.w3.org/XML/2005/xsd-versioning-use-cases/
• http://stackoverflow.com/questions/2014237/what-are-the-best-practices-for-versioning-xml-schemas
• http://www.xml.com/pub/a/2004/07/21/design.html

There are several version numbers to be considered:
(1) version of each NXDL file
(2) version of the suite of NXDL definitions (*.nxdl.xml)
(3) version of the rules for writing NXDL files (nxdl.xsd and related)

We already have (1). Older versions can be obtained from version control (with some investigative work).

We do not have an easy way to change (3). This is currently the version tied to the release. It can be argued that this number should not change very often. A change to this version number is quite complex since it is used in the declared namespace for all NXDL files. Software (both within NeXus and 3rd party) has this number built in. The rules we have set out for writing NXDL seem to be stable. AND, the way we use this version number in the nxdl.xsd is consistent with the best practices document.

This need expressed by this issue is concerned more with (2). At present, we have no identified component that differentiates between (2) and (3). At present, we have no identified component that differentiates between (2) and (3). To implement (2), it may be as simple as adding a clearly-defined term that provides this version, such that its change does not require every NXDL file and every software tool to be updated. When this number is changed, we would create a new tag in GitHub so that older version would remain accessible.

Any proposed versioning method for (2) needs to be tested before it is accepted to ensure this will provide us the version service we need to write and validate data files.

[prjemian]

The top-level file NXDL_VERSION contains the current NXDL version number: 3.1 now.
It is only referenced in the conf.py file of the documentation which, in turn, places that version number in the manual. This process could be changed if something different is planned.

The XML namespace, and consequently the schemaLocation, both incorporate the string "3.1" into the XML Schema (nxdl.xsd & nxdlTypes.xsd), all the NXDL files, and some of the Python code in various places in the definitions repository. Likely other code such as used by NeXpy uses this same string to process the XML files in some way.

http://definition.nexusformat.org/nxdl/3.1

This is the string that, due to its use in the namespace and schemaLocation strings, has become very difficult to change.

One proposition for (2) above is that we leave the namespace string constant as we change the NXDL_VERSION file content. The NXDL_VERSION file is changed when the GitHub repository is tagged with a new version. Immediately, the namespace string and the NXDL_VERSION will become unsynchronized. That is something we must accept until we identify a better way to keep them in sync while also supporting the validation of data files written with previous NXDL versions.

[prjemian]

from the discussion during today's telco:

There are four known uses of the NeXus definitions version:
(1) version of each NXDL file
(2) version of the suite of NXDL definitions (*.nxdl.xml)
(3) version of the rules for writing NXDL files (nxdl.xsd and related)
(4) version used in the XML namespace

Here is the proposition:

Each NXDL file has a "version" attribute. This solves (1). Is there a more accessible place to keep and provide this version information?

Item (2) may not be necessary to solve. Discussion?

Changes in item (3) are the best motivation for a new version number. One example for an update to the version number might be due to the addition of the NIAC 2014 method to identify the default data to be plotted.

Item (4)
Leave the XML Namespace string unchanged. It is:

http://definition.nexusformat.org/nxdl/3.1

[prjemian]

1. each NXDL file has a definitions/@Version attribute that declares the version of this NXDL

2. we will tag the definitions repository with new releases of the NeXus definitions

   a. such as: change of NXmx will compel a new NeXus definitions tag

   b. before pushing a new change, we should copy the current documentation PDF to a place to be setup to retain legacy versions of the documentation (we can do this manually until we decide how to automate this in a robust way)

3. changes in the NXDL language (such as new unit types) will become part of a new tag

4. the syntax of the NXDL language is currently 3.1

[prjemian]

Suggest we use a modified semantic versioning: major.minor and no ".patch"
http://semver.org

major: (not described above) 3 (currently) - changes in NXDL language that are incompatible with previous versions
minor: (item 2&3 above) 1 (currently) - changes in NXDL structure

patch: (item 1 above) releases for NXDL file changes

• generally, we tend to leave out the patch from the version
• instead it is proposed that we move the major.minor tag to point to the newest commit hash

[prjemian]

This latest content added to the manual installation page.

[prjemian]

resolved with commit 0c0d734 and issue #254