Versioning of base classes and application definitions

[zjttoefs]

There is no infrastructure to support this. We only work of the latest version. With science progressing this will not be viable for the long term.

[prjemian]

This is directly related to this definitions issue: nexusformat/definitions#387

[prjemian]

Every NXDL file has a "version" attribute on the root element. Thus, each NXDL has its own version.

What infrastructure is needed? Perhaps a convenient way to identify a new version of each NXDL with its initial commit hash?

[zjttoefs]

The question a validation tool has is: How do I find a particular version of a definition?
For users looking at a given file it may be more: How do I find the documentation for a particular version?

For the moment the manual only includes the latest version.
Plus application definitions may expect certain versions of a base class (at least, at most).

This is problem material for the code camp, unless someone has a proposed solution ready by then.

[prjemian]

As discussed http://www.nexusformat.org/NIAC2016Minutes.html

• You make the change to NXDL and change the version in the NXDL file
• You build a manual and commit it into the repository
• Then you tag the git repository

The proposal was accepted on probation with 12 yes. To be revisited at the next NIAC in order to check if it works.

[prjemian]

I want to revise that procedure slightly, based on how the version number is written into the manual:

• Make the changes to file(s) in the definitions repository
• Change the version in the NXDL file (such as v3.3)
• Commit the changes into the repository and note the GitHub commit code (SHA)
• Create a tag from that commit using the same version string (such as v3.3)
• Create a release from that tag using the same version string (such as v3.3)
• Build a PDF version of the manual
  • follow the naming pattern in use
  • nexus- + release name + yyyy-mm-dd + GitHub commit code + .pdf
  • example: nexus-v3.2-2016-11-22-32b130a.pdf
• Commit the PDF manual as-built into https://github.com/nexusformat/definitions/legacy_docs

[prjemian]

See the manual as well: http://download.nexusformat.org/doc/html/installation.html?highlight=semantic#nexus-definitions

[prjemian]

Need to make a wiki page describing how the manual is built.

[prjemian]

regarding: discussion
about how to build the documentation,

see: https://github.com/nexusformat/definitions/wiki/Building-the-distribution

[prjemian]

regarding: discussion
about procedure to make a new release,

see: https://github.com/nexusformat/definitions/wiki/Release-Procedure

[prjemian]

With the documents describing the release procedure and how to build the documentation in the definitions wiki (prepared for the v3.3 release), this issue can be closed.