new release procedures - hapi-server/data-specification GitHub Wiki

All changes to the HAPI master branch worthy of showing up in the change log should come in via a Pull Request that is tied to the issue being addressed.

When making a PR:

  • start from the issue to make the PR
  • the name of the PR ends up being visible, so make it this: issue #: decent description for use in change log
  • immediately (manually) tag the PR with the correct milestone
  • when you merge, delete the branch

Notes on the version number: the spec document (the .md file) and the PDF version should all have all three digits for semantic versioning. New minor versions start with a 0 for the point release number. (In contrast, in the HAPI header responses, on version X.Y should be returned.)

New Release

First, make a new branch for the release prep.

The JSON schema and then the verifier need to be in place before announcing a new release.

In the dev folder

  1. make sure all the TOC links work in the dev spec document, especially if there were sections added in the middle that affect subsequent numbering
  2. if any error codes were changed, do a check: are the JSON error codes in the appendix are consistent with the table earlier in the text?
  3. update all the version numbers of HAPI in the examples to the soon-to-be-latest version.
  4. update the front matter with the right version info; if there are significant changes, those can be added to the front
  5. check out the project locally; create a new dir for the new release;
  6. copy the dev version of the spec into the new directory and rename it with the right version tag
  7. edit the change log first in the dev directory to add new changes, then copy it to the new version dir

Changelog

  1. Put link to total diff since last release, unless there were major structural changes, in which case skip this step
  2. Use PRs linked to release milestone to get list of all changes for this version
  3. put them into the right categories in the change log: API changes, response changes, clarifications
  4. Note any non-backwards compatible changes
  5. copy the dev version of the changelog (no need to rename)
  6. commit and push the changes
  7. (we are slowly phasing this out) update the "Significant Changes to Specification" portion of the dev spec document to list all changes and point to location in changelog.md

Once committed:

  1. make PDF (Bob does this)
  2. commit that too
  3. add PDF to Zenodo as new version

Update references to new release

  1. update the hapi-server.org web page
  2. update the README.md file for the project

After release

Create a new branch, e.g., 3.2.0. Modify the dev README to have 3.2.0-dev in the header.

Typos/Clarifications/Restructuring

  • Every change should be tied to an issue - group restructuring or edits together if needed
  • Commit message should start with Typo, Clarifications, Restructuring

Corrections or clarifications: making a point release

  • Create branch with incremented 3rd digit in semantic version number (if latest is 3.3.0, then make 3.3.1)