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). NOTE: pagmo uses a MAJOR.MINOR.PATCH versioning scheme, please make sure all 3 numbers are always defined.

• When updating pagmo from version x.y to x.(y+1) (i.e., a minor version update), 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 minor 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 minor release, pagmo 2.124, will have SOVERSION 457 and VERSION 457.0. Although it's tempting, DO NOT [skip ci] in the commit (see the pitfalls section below). NOTE: pagmo currently commits to guaranteeing binary (ABI) stability across patch releases (i.e., from x.y.z to x.y.(z+1)).

• 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.

• 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. The conda web bots will detect the presence of new releases for both pagmo and pygmo, and they will automatically open PRs to the feedstocks. Note that the automatic PR to pygmo will initially fail, as it will be looking for an updated version of pagmo which will however be available only after the pagmo PR has been merged. After the PR to the pagmo feedstock has been merged, you can ping (e.g., git commit --allow-empty) the pygmo PR to re-trigger the CI. If the pagmo/pygmo conda recipes/scripts need updating (e.g., a new dependency has been added to pagmo/pygmo), you'll have to go the usual route of manually cloning the feedstock, applying the necessary changes, etc.

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.