How to make a release

Step-by-step instructions

• Make sure the pagmo version number is set to the correct value. The version number is at the top of the root CMakeLists.txt file, in the variable PAGMO_PROJECT_VERSION. If the version number is not the correct one, rectify it and commit and push the changes to the pagmo repository. Although it's tempting, DO NOT [skip ci] in the commit (see the pitfalls section below).

• Make sure to bump up the VERSION and SOVERSION properties of the pagmo shared library target in the main CMakeLists.txt file. Note that SOVERSION is a single integral which needs to be increased by one at every pagmo release, while VERSION is just SOVERSION.0. VERSION and SOVERSION are unrelated to the pagmo2 version - you can think of them as internal version numbers of the pagmo DLL. For example, let's say that pagmo version 2.123 has SOVERSION 456 and VERSION 456.0. The next release, pagmo 2.124, will have SOVERSION 457 and VERSION 457.0.

• Make sure the doc/sphinx/changelog.rst file is up to date, and that the section title for the new release contains the correct version & date (e.g., "2.2 (unreleased)" is not ok, fix it with the appropriate date: "2.2 (2017-05-12)"). If you had to modify the changelog, commit and push the changes to the pagmo repository before doing anything else. Although it's tempting, DO NOT [skip ci] in the commit (see the pitfalls section below).

• Create a new release via the webpage https://github.com/esa/pagmo2/releases. It is very important that the "Tag version" field in the new release form starts with a v. That is, if you are releasing version 2.3.4, the "Tag version" field must read v2.3.4. Also, there must be at least one major and one minor version number in the release number (e.g., 2.3, 2.3.4, 2.3.4.5 are all fine, 3 is not :) )

• The other fields in the new release form are not crucial, but please try at least to be consistent with previous releases :)

• After the new release has been created, patiently wait for the CI builds to run. If everything went ok, the new pypi pygmo packages will show up at https://pypi.org/project/pygmo/

• Also, double check the newly-created DOI on Zenodo (double check the authors especially)

• After the pypi packages have been published, it's time to update the conda packages at https://github.com/conda-forge/pagmo-feedstock and https://github.com/conda-forge/pygmo-feedstock. Starting from pagmo 2.4, you need to update first pagmo and then pygmo: since version 2.4 pygmo depends on pagmo, and thus the new pagmo needs to be available in conda before the new pygmo, otherwise the conda-forge CI process will fail. For both pagmo and pygmo you need to:

  • fork the feedstock and create a new PR (just like you fork & create PRs in the usual github workflow)
  • update the file recipe/meta.yaml. In normal circumstances, you need only to update the {% set version = ... %} line at the very beginning (set it to the newly released version number), and the sha256: field around line 9 or so. The sha256 field must be updated with the checksum of the new pagmo-x.y.z.tar.gz source archive that was generated by the release steps above. In order to compute the new sha256, download the newly-released .tar.gz archive from https://github.com/esa/pagmo2/releases, run openssl sha256 filename.tar.gz in a console, and copy the output to the sha256: field in the recipe/meta.yaml file.
  • sometimes new versions might require changes in the build scripts (e.g., enable a new optional feature - like ipopt) and in the dependencies (e.g., add ipopt as a dependency on unix platforms). Modify the meta.yaml, build.sh and bld.bat files as needed.

Pitfalls

• Do not tag a release in correspondence of a commit which skips the CI services (i.e., if the commit message contains [skip ci], [skip appveyor], etc.). Doing so will prevent the CI from running, and no packages will be produced for the new pagmo version.