From 99c483c95d46601c0b77bf9d9abb4c9e98057975 Mon Sep 17 00:00:00 2001 From: Laurent Farvacque Date: Fri, 16 Jun 2023 21:30:46 +0200 Subject: [PATCH] Release 0.4.0 (#616) * Update of the Developer documention for describing the procedure to release a new version * Release procedure corrected according to MJGaughran's remarks. * Corrected typo * Clarified the specification of numpy versions used in GitJub actions * Added the ## Main modifications section * corrected typo --- pyat/developers.rst | 85 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 74 insertions(+), 11 deletions(-) diff --git a/pyat/developers.rst b/pyat/developers.rst index 964542709..4ef571464 100644 --- a/pyat/developers.rst +++ b/pyat/developers.rst @@ -105,6 +105,14 @@ To do this, we use the continuous integration service Github Actions. When a tag of the form pyat-* is pushed to Github, wheels for each supported platform will be built and automatically uploaded as an 'artifact'. +We use `Semantic Versioning `_ for this project. As documented +by the full specification, we use a version number with three dot-separated +numbers: ``MAJOR.MINOR.PATCH``. Increment the: + +* MAJOR version when you make incompatible API changes +* MINOR version when you add functionality in a backward compatible manner +* PATCH version when you make backward compatible bug fixes + Release procedure ----------------- @@ -114,24 +122,79 @@ To upload a release to PyPI, you will need to be a 'maintainer' of For testing any version that you have installed, the simple snippet in ``README.rst`` is sufficient. -* Decide the Python versions that should be supported in the release - * Set these Python versions in ``python_requires`` in ``setup.cfg`` - * Set at least these Python versions as ``python-version`` in ``.github/workflows/python-tests.yml`` -* Determine the minimum Numpy version that is required for those Python versions - * Set this numpy version in ``install_requires`` in ``setup.cfg`` -* Push a tag ``pyat-x.y.z`` to Github +Decide the Python versions that should be supported in the release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Set these Python versions in ``requires-python`` in ``pyproject.toml`` +* Set at least these Python versions as ``python-version`` in ``.github/workflows/python-tests.yml`` + +Determine the minimum ``numpy`` and ``scipy`` versions: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* the version ensuring the requirements necessary to **run** PyAT is set in the + ``dependencies`` item of the ``[project]`` section of ``pyproject.toml`` +* The version required to **build** PyAT is set in the ``requires`` item of the + ``[build-system]`` section of ``pyproject.toml``. It depends on the python version + and must be higher or equal to the "run" version. +* To avoid ABI compatibility issues, the pre-compiled binaries are built with the + earliest possible version of numpy for the given Python version. This ensures that + the user's libraries are more recent than the one AT has been compiled with. For + that, a copy of ``pyproject.toml`` named ``githubproject.toml`` is used for + compilation. In this copy, the numpy version specifications are set using ``~=`` + instead of minimum (``>=``). Apart from these lines, the 2 files + should be strictly identical. + +Prepare the "Release notes" +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A draft can be obtained by creating a new tag on GitHub. Click "Draft a new release" +in the releases page, choose a new tag in the form ``pyat-x.y.z`` with the correct +incremented version number. The ``pyat-`` prefix is necessary to identify python releases. +Select the master branch as target. In the description area, choose the current +release in the "previous tag" pull-down, and press "Generate release notes". + +The generated notes can now be copied and edited. You can then either cancel or +save the release as a draft while editing the release notes. + +The ``## What's changed`` section should be split into ``## Bug fixes`` and +``## New features``. It must be filtered to keep only the python changes, ignoring +the Matlab ones. The tags on each pull request are there to help in this filtering. + +The release notes should start with a ``## Main modifications`` section summarising +the important points of the new release. + +They must end with a section pointing out ``## Incompatibilities`` and mentioning the +necessary actions before upgrading to this release. + +Open a Pull Request for the new release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The goal is to make all contributors aware of the new release, to check that no pending +modifications are worth being included and to review the release notes. + +There should be no code modifications except updates of version informations in the +documentation. Once the pull request is approved and merged, the release may be built. + + +Build the release +~~~~~~~~~~~~~~~~~ + +Now either go back to the draft release saved above, or start again the procedure, +but now finalising with the ``Publish`` button. If all goes well, there will be a build of "Build and upload wheels and sdist" associated with the tag ``pyat-x.y.z``: on the `Github Actions page `_. This build will have 'tar.gz' and 'wheels' downloads available. +Upload the release to ``pip`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * Download the tar.gz and wheels files and unzip them into a directory ```` * Manually install at least one wheel to make sure that it has built correctly -* Install Twine for uploading the files to PyPI. One way to do this is to create a new virtualenv:: +* Install Twine for uploading the files to PyPI. One way is to use + `pipx `_. Once pipx installed, use:: - $ python3 -m venv venv - $ source venv/bin/activate - $ pip install twine + $ pipx install twine # or: + $ pipx upgrade twine * Use Twine to upload the files to PyPI. You will be prompted for your PyPI credentials:: @@ -145,4 +208,4 @@ associated with the tag ``pyat-x.y.z``: on the `Github Actions page