Release Procedure

Describes how to make a new release of the NeXus definitions repository.

Preparatory Steps

Start planning long before the time to make a new release. These preparatory steps will be useful in automatically creating a set of release notes (example).

1. create a GitHub milestone for the new release
   • start here: https://github.com/nexusformat/definitions/milestones
   • assign (estimate) a date this is expected to be complete
2. create issues and assign them to the milestone
   • this cross-reference is needed to build the release notes
3. commit work referencing the issues by number in the commit message, such as #175 resolve ambiguity
   • this cross-reference is needed to build the release notes
4. create pull requests, assign them to the milestone
   • this cross-reference is needed to build the release notes
5. create tags for new or modified NXDL files, (can't assign them to the milestone, see SO)
   • this cross-reference is needed to build the release notes

Release Steps

1. resolve pull requests for milestone
   • or merge, close, or reassign to different milestone(s)
2. resolve issues for milestone
   • close or reassign to different milestone(s)
3. announce that new release is forthcoming via nexus@nexusformat.org
4. change the version in the NXDL_VERSION file (such as v2018.4)
5. commit the changes into the repository and note the GitHub commit code (SHA)
6. create a tag from that commit using the same version string (such as v2018.4)
7. run the CI workflow to build the documentation from this tag and select to deploy and upload (wait for it to succeed)
8. create a release from that tag using the same version string (such as v2018.4) - Very important not to use whitespace in the tag or release name!
9. generate new wiki page for the release notes
   • use utils/create_release_notes.py script
10. reference new release notes on master page: https://github.com/nexusformat/definitions/wiki/Release-Notes (newest release first)
11. build a PDF version of the (new version of the) manual
    • follow the naming pattern now in use (year.month, the old style was major.minor)
    • nexus- + release name + yyyy-mm-dd + GitHub commit code + .pdf
    • example new way: nexus-v2018.4-2018-04-30-abc1234.pdf
    • example old way: nexus-v3.2-2016-11-22-32b130a.pdf
12. commit the PDF manual as-built into legacy_docs
13. add link in the release notes to the documentation PDF
14. update CHANGES.rst
15. announce the new release to the community via: nexus@nexusformat.org
16. close the milestone

---

background

• https://github.com/nexusformat/NIAC/issues/1#issuecomment-308834940
• https://github.com/nexusformat/NIAC/issues/1#issuecomment-308838075
• https://github.com/nexusformat/definitions/issues/597 (CodeCamp2017: change versioning procedures)
• https://github.com/nexusformat/definitions/blob/master/utils/create_release_notes.py (code to build release notes)