Releasing

In this document, we describe the procedure used to release a new version of Oríon to the public. Release artifacts are distributed through PyPI.

Creating a release candidate

The first step in releasing a new version is to create a release candidate. A release candidate allows us to thoroughly test the new version and iron out the remaining bugs. Additionally, it’s also at this time that we make sure to change the version number and update related documentation such as the README.rst.

  1. Create a new branch from the develop branch named release-{version}rc, where {version} is replaced by the number of the new version (e.g., 1.2.0). This effectively freezes the feature set for this new version, while allowing regular development to continue take place in the develop branch. More information is available in Version Control Guidelines.
  2. In README.rst, replace any link pointing to https://orion.readthedocs.io/en/latest/** to https://orion.readthedocs.io/en/stable/**.
  3. Create a new pull request for the branch created in the last step and list all the changes by category. Example: https://github.com/Epistimio/orion/pull/283.
  4. Update the Citation section in the project’s README.rst with the latest version of Oríon.
  5. Update the ROADMAP.md.
  6. Update the linters flake8, pylint, and doc8 to their latest versions in tox.ini, and address any new error.
  7. Run the stress tests according to the instructions in stress test’s documentation.

Making the release

Once the release is thoroughly tested and the core contributors are confident in the release, it’s time to create the release artifacts and publish the release.

  1. Merge the release candidate branch to master (no fast-forward merge, we want a merge commit).
  2. Create a new draft release on GitHub. Set the target branch to master and the tag version to v{version}. Reuse the changelog from the release candidate pull request’s for the description. See the 0.1.6 version example.
  3. Merge the master branch back to develop.
  4. Delete the release candidate branch.

Publishing the release

Once the release is correctly documented and integrated to the VCS workflow, we can publish it to the public.

  • Publish the GitHub release. The source code archives will be added automatically by GitHub to the release.
  • Publish the new version to PyPI by executing $ tox -e release from the tagged commit on the master branch.

After the release

Once published, it’s important to notify our user base and community that a new version exists so they can update their version or learn about Oríon.

  • Verify Oríon’s Zenodo page has been updated to reflect the new release on GitHub. Zenodo is configured to automatically create a new version whenever a new release is published on GitHub.
  • Verify Oríon’s Anaconda page contains the new version. Binaries for the new version are uploaded automatically by TravisCI when the tests pass for the merge commit tagged with the new version on the master branch .
  • Announce the new release on your #orion’s slack channel.
  • Announce the new release on relevant communication channels (e.g., email, forums, google groups)
  • Congratulations, you published a new version of Oríon!