:orphan:

.. _docs/contrib/07_release_guide/publishing-a-new-release-(for-maintainers-only):

Publishing a new release (for maintainers only!)
================================================

.. _docs/contrib/07_release_guide/base-conventions:

Base conventions
----------------

For each version update (a.k.a **releases**\ ), we use `semantic versioning <https://semver.org/>`_\ :


* **patch** (from ``*.*.{i}`` to ``*.*.{i+1}``\ ): minor modifications, bugfixes, code reformating, small new features, new projects or playgrounds, new tests
* **minor** (from ``*.{i}.*`` to ``*.{i+1}.0``\ ): addition of new major features, minor code structure changes without too much impact on the API (backward compatible)
* **major** (from ``{i}.*.*`` to ``{i+1}.0.0``\ ): major changes in code structure, design, and API, with changes potentially breaking backward compatibility 

.. _docs/contrib/07_release_guide/release-pipeline:

Release Pipeline
----------------

First, create a ``new-release`` branch (or choose a similar name), either on your fork or on the main ``pySDC`` repo. Then, on commit:


#. modify the project version number and, if necessary, the list of authors in ``pyproject.toml``
#. modify the documentation release number in ``docs/source/conf.py``\ , and the version number for minor and major release. Also, if necessary, adapt the list of authors.
#. modify the version number, release date and, if necessary, the list of authors  in ``CITATION.cff``
#. (for minor and major release **only**\ ) add the release description in the ``CHANGELOG.md`` file, following the level of details you can find there

Commit with the message: ``bump version to x.x.x`` where ``x.x.x`` is the new version. 
Then create a pull request, and once all tests passed, you can ``Merge and Squash``\ ,
possibly adding your initials as prefix of the final commit message.

..

   🔔 Don't forget to delete the ``new-release`` branch both locally and on your fork (or the main repo):


.. code-block:: bash

   git push -d origin new-release  # delete on remote
   git branch -D new-release       # delete locally

Finally, `draft a new release <https://github.com/Parallel-in-Time/pySDC/releases/new>`_ associated to a new tag 
``v*.*.*`` (with ``*.*.*`` the new version, and the ``+ Create new tag: ... on publish`` button).
Add a comprehensive summary of the main changes, with appropriate thanks to all the contributors (cf previous releases), and publish it. This will trigger automatically a release update on `Zenodo <https://zenodo.org/doi/10.5281/zenodo.594191>`_.
For uploading the new release on `PyPI <https://pypi.org/project/pySDC/>`_\ , this is done manually so you'll have to ask `Robert Speck (@pancetta) <https://github.com/pancetta>`_ for support (ideally send him a quick email).

|:arrow_left:| :doc:`Back to adding Project <./06_new_project>` ---
|:arrow_up:| :doc:`Contributing Summary <./../../CONTRIBUTING>` ---
|:arrow_right:| `Next to a cute picture of cat <https://www.vecteezy.com/photo/2098203-silver-tabby-cat-sitting-on-green-background>`_