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 [email protected]
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. 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!
8. generate new wiki page for the release notes
   • use utils/create_release_notes.py script
9. reference new release notes on master page: https://github.com/nexusformat/definitions/wiki/Release-Notes (newest release first)
10. 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
11. commit the PDF manual as-built into legacy_docs
12. add link in the release notes to the documentation PDF
13. update CHANGES.rst
14. announce the new release to the community via: [email protected]
15. 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)