.. # define a hard line break for HTML
.. |br| raw:: html

   <br />

.. _howto_release:

Release a new version
---------------------

Here is a short list of the actions to do for each new release.

1. Update the :ref:`release notes <release_notes>`

2. Make sure :file:`VERSION` file version matches the name of the working
   version to be released.
   Do **not** include suffixes like `alphaA`, `betaB`, `rcX` …

  Version format is expected to follow the following convention:
  ``M.m(.p)`` See
  https://packaging.python.org/guides/distributing-packages-using-setuptools/#standards-compliance-for-interoperability

3. Make sure version number is up-to-date in :file:`CITATION.cff` and
   :file:`.zenodo.json` files.

4. Handle all the issues associated for the related milestone, and close it.

5. Push ``develop`` branch.

   .. code:: bash

       git checkout develop && git push

6. Wait for its pipeline to succeed. Go back and fix what needs fixing
   otherwise.

7. Merge ``develop`` branch into ``master``

   .. code:: bash

       git checkout master && git pull && git merge develop

8. Push ``master`` branch.

   .. code:: bash

       git push

9 Create a git tag matching the desired version number.
  This time, the tag version can include suffixes like `alphaA`, `betaB`, `rcX` …

  If it doesn't match the content of :file:`VERSION` file, tagging shall be
  rejected by the :file:`reference_transaction` git hook.

   .. code:: bash

       # in the case of pre-release versions:
       git tag -a "${version}rc1"
       # or the case the final versions:
       git tag -a "${version}"
       # Plus fill-in version information

10. Push the tag

   .. code:: bash

       git push --tags


   .. note::

       From there on, the CI will automatically take care of registering the
       source distribution (only; and not the wheel!) on PyPi as if we had
       manually run

       .. code:: bash

           # Prepare the packets for PyPi
           python3 setup.py sdist

           # Push to PyPi
           python3 -m twine upload --repository pypi dist/S1Tiling-${version}*

11. For major and minor versions, create a branch named after this version. It
    will help to track issues patching of that version independently of work
    done on the next version, tracked in ``develop``.

   .. code:: bash

       git checkout -b release-${version}
       git push --set-upstream origin release-${version}

12. Go to `github mirror <https://github.com/CNES/S1Tiling>`_, once the
    repository has been mirrored, to create a new release. This will
    automatically generate a new DOI on zenodo.

13. Go to the new `zenodo release <https://doi.org/10.5281/zenodo.17237358>`_
    and update project metadata that cannot be set in :file:`CITATION.cff`
    file.

14. Eventually, update :file:`VERSION` file to the next expected
    version number. **Never** use any suffix in that file.

15. Announce the new release to the World.


A note on the management of version numbering
+++++++++++++++++++++++++++++++++++++++++++++

Version numbers are extracted as described in :func:`get_version` function.

.. autodata:: s1tiling.libs._version.template
.. autodata:: s1tiling.libs._version.dev_template
.. autodata:: s1tiling.libs._version.dirty_template

.. autofunction:: s1tiling.libs._version.get_version