New release (How to) - Materials-Consortia/OPTIMADE GitHub Wiki

Release instructions

Pre-release checklist

  • Check AUTHORS is up to date
  • Update the CHANGELOG
  • Spellcheck the new specification text with make spell and interactively add any new words to the wordlist with make fix_spelling
  • Review changes since the last versions and decide whether the new version number is appropriate
  • Ideally release 1 or 2 release candidates in the weeks/months before the main release
  • Check the HTML build of the specification and update the gh-pages branch to point to the latest release

Release procedure

  1. develop: Merge PRs that should go into the release.
    • Check that the specification is internally consistent and "ready for release".
    • Ensure that the ./schemas, CHANGELOG and AUTHORS have been updated for the new release.
  2. develop: Create PR that updates the version at the top of optimade.rst. Merge this PR against develop as the last thing before releasing.
  3. master: Merge the develop branch into the master branch:
    1. Create PR on GitHub (Link).
    2. Use git on your local machine to merge develop into master once all CI checks have passed.
      1. Fetch all (git fetch --all -p).
      2. Checkout master (git checkout master, if you have never checked out master, first do git branch master origin/develop, if origin is the remote for Materials-Consortia/OPTiMaDe).
      3. Run git merge --ff-only origin/develop.
      4. If this was successful, push to origin, i.e., git push (this may require temporarily disabling branch protections on master). Note: If this was not successful, you should merge a "fixing" PR into develop that makes it possible to merge using fast-forwarding (ff).
  4. master: Use the GitHub interface to create a release on the latest commit in master with the new version number, e.g. v1.0.0. (Make sure to select to tag master as the UI will default to develop.) This will create a tag in the git repository.
  5. develop: Create a PR that updates the version string at the top of optimade.rst in the develop branch to add the suffix ~develop to the version number. (Note: this intentionally breaks semantic versioning for non-released develop versions.)
  6. Archive the released specification text on Zenodo as a new version of https://doi.org/10.5281/zenodo.4195050 (currently only @ml-evs can do this -- if you are reading this in 100 years then i) I am dead, ii) hopefully Zenodo would have added support for organizational control of records)

Note: For historical reasons, versions v0.9.6 and v0.9.7 were never released/tagged. By default, however, it is understood that the version number should only be increased after a new release has been made.

Ideally, release candidates suffixed with -rc.<n> should be made available for provider implementation before the official release. These should be considered as a feature freeze, but implementation details may change slightly in the final release.