Merge pull request #4112 from t20100/doc-release-process

Documentation: Added how-to make a release

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
 How to contribute to *silx*
----------------------------
+===========================
 
 This document describes how to contribute to the *silx* project.
 The process is similar to many other open-source projects like *numpy*, just lighter as the project is smaller, so you won't be surprised with the pipeline.
@@ -49,7 +49,7 @@ If you encounter any problems or have any questions you can always ask on the `I
 
 
 Pull Request title format
-.........................
+-------------------------
 
 To ease release notes authoring, please use the following syntax for the title of your Pull Requests (PR)::
 
@@ -79,6 +79,117 @@ With:
 
 - **Summary**: A short description of the main change as you would like to read it from release notes.
 
-
 .. _their own CONTRIBUTING guide: https://github.com/scikit-image/scikit-image/blob/3736339272b9d129f98fc723b508ac5490c171fa/CONTRIBUTING.rst
 .. _Issues page: https://github.com/silx-kit/silx/issues
+
+How-to make a release
+---------------------
+
+Use cases
++++++++++++++
+
+Release candidates
+..................
+
+Use this release process and make sure only bug fix pull requests are merged on the ``main`` branch until the final release is published.
+
+Major/minor releases
+....................
+
+Follow this release process.
+Bug fix releases
+................
+
+- For ``vM.m.1``, first create a ``M.m`` branch from the ``vM.m.0`` tag.
+- Merge relevant pull requests on the ``M.m`` branch.
+- Follow this release process, but for the branch ``M.m`` instead of ``main``.
+
+Pre-release testing
++++++++++++++++++++
+
+Automated tests
+...............
+
+- Run the `release workflow`_ manually (see `manually running a workflow`_) to check that the release artifacts are built correctly.
+  The wheels generated by the workflow can be downloaded from the release workflow run web page.
+  *Note: Running the workflow manually do NOT publish artifacts to pypi.*
+
+- Run the `previous release workflow`_ with the following variables:
+  - ``REPOSITORY``: ``https://github.com/<user>/silx`` (default: ``https://github.com/silx-kit/silx``)
+  - ``TAG``: branch or tag to test (default: ``main`` branch)
+
+Manual testing
+..............
+
+Download wheels generated by the github release workflow from the github action release workflow web page and install silx from those wheels locally for manual testing.
+
+Prepare the release
++++++++++++++++++++
+
+Write the release notes
+.......................
+
+- Generate the list of pull requests included in the release with github's automatically generated release notes (see `github automatically generated release notes`_) between a new tag and the previous release.
+- Copy the generated changelog to ``CHANGELOG.rst`` and close github's release web page.
+  **Warning: DO NOT publish the release yet!**
+- Sort, curate and fix the list of PRs and match the styling of previous release notes.
+
+Steps
+.....
+
+- Update ``CHANGELOG.rst``.
+- Bump the version number in ``src/silx/_version.py``.
+- Create a pull request with those changes, wait for reviews and merge it.
+
+Publish the release
++++++++++++++++++++
+
+Create the release
+..................
+
+* Draft a new release from `github new release page`_ using similar conventions as previous releases:
+  - Create a new tag which **MUST** be named ``v<release_version>`` and match the version in ``src/silx/_version.py``.
+  - Combine the release notes manually edited from ``CHANGELOG.rst`` with `github automatically generated release notes`_.
+* Press the "Publish release" button to trigger the release workflow which builds the documentation, the source tarball and the wheels.
+
+Publish Windows "fat binaries"
+..............................
+
+* Generate the Windows "fat binaries":
+  - Run the `previous release workflow`_ with the variable ``TAG`` defined to ``v<release_version>``.
+  - Download the 2 Windows fat binaries (``.zip`` and ``.exe``) generated by this pipeline.
+  - Rename the downloaded files to ``silx-<release_version>-windows-application.zip`` and ``silx-<release_version>-windows-installer-x86_64.exe``.
+    Note: This is important since the documentation links to those files.
+*  Edit the freshly created release on github and upload the renamed Windows fat binaries as release artifacts.
+
+Publish to pypi
+...............
+
+Once build and tests are completed, the release workflow requests the approval from a reviewer of the `deployment environment`_.
+Upon approval, the release artifacts are published to `pypi`_.
+
+Deploy the documentation
+........................
+
+Skip this step for **release candidates**.
+
+- Download the ``documentation`` artifact from the release workflow run web page.
+- Unzip it in the ``doc/silx/M.m.p`` folder on www.silx.org/doc/silx.
+- Update the ``doc/silx/latest`` symbolic link.
+
+Publish on conda-forge
+......................
+
+Skip this step for **release candidates**.
+
+Shortly after the publication on `pypi`_, conda-forge bot opens a PR on the `silx feedstock`_ to add this version to the conda-forge channel.
+Once this PR is merged, the new version is published on conda-forge.
+
+.. _release workflow: https://github.com/silx-kit/silx/actions/workflows/release.yml
+.. _manually running a workflow: https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow
+.. _github new release page: https://github.com/silx-kit/silx/releases/new
+.. _github automatically generated release notes: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#creating-automatically-generated-release-notes-for-a-new-release
+.. _previous release workflow: https://gitlab.esrf.fr/silx/bob/silx/-/pipelines/new
+.. _deployment environment: https://github.com/silx-kit/silx/settings/environments
+.. _pypi: https://pypi.org/project/silx/
+.. _silx feedstock: https://github.com/conda-forge/silx-feedstock