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 project() CMake directive. 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 that the VERSION and SOVERSION properties of the pagmo shared library target in the main CMakeLists.txt file have been bumped up with respect to the previous version. 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)).

• Check that all public header files are included in the global header pagmo.hpp. If you need to modify pagmo.hpp, although it's tempting, DO NOT [skip ci] in the commit (see the pitfalls section below).

• 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. Also, double check the newly-created DOI on Zenodo (double check the authors especially)

• The conda web bots will detect the presence of a new release of pagmo, and they will automatically open a PR to the feedstock. If the pagmo conda recipe/scripts need updating (e.g., a new dependency has been added), 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.