From 4a55e0f59e9eb06f647b2b11015528d3dc58895b Mon Sep 17 00:00:00 2001 From: Thomas VINCENT Date: Thu, 18 Apr 2024 15:02:57 +0200 Subject: [PATCH 1/3] add release documentation --- CONTRIBUTING.rst | 113 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 110 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a9c719ba38..b4ca44340f 100644 --- a/CONTRIBUTING.rst +++ b/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,113 @@ 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 +--------------------- + +Special 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. + +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//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`` 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``. + - Download the 2 Windows fat binaries (``.zip`` and ``.exe``) generated by this pipeline. + - Rename the downloaded files to ``silx--windows-application.zip`` and ``silx--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 From 96657cbf15ea191e6e37f4a76e11a1de107f5df3 Mon Sep 17 00:00:00 2001 From: Thomas VINCENT Date: Thu, 13 Jun 2024 15:51:27 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: payno --- CONTRIBUTING.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b4ca44340f..73260e4e3b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -108,7 +108,7 @@ 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. + *Note: Running the workflow manually do NOT publish artifacts to pypi.* - Run the `previous release workflow`_ with the following variables: - ``REPOSITORY``: ``https://github.com//silx`` (default: ``https://github.com/silx-kit/silx``) @@ -127,7 +127,7 @@ 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! + **Warning: DO NOT publish the release yet!** - Sort, curate and fix the list of PRs and match the styling of previous release notes. Steps @@ -144,7 +144,7 @@ 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`` and match the version in ``src/silx/_version.py``. + - Create a new tag which **MUST** be named ``v`` 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. From e71bf5ac13e1756d64aee6d84e60c2376375270e Mon Sep 17 00:00:00 2001 From: Thomas VINCENT Date: Thu, 13 Jun 2024 15:53:55 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: payno --- CONTRIBUTING.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 73260e4e3b..cbb63781fc 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -85,7 +85,7 @@ With: How-to make a release --------------------- -Special cases +Use cases +++++++++++++ Release candidates @@ -93,6 +93,10 @@ 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 ................