How-to make a release#

Use cases#

The release branch is the main branch, except for bug fix releases.

First, decide which kind of release is needed:

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 when not already done.

  • Merge relevant pull requests on the M.m branch.

  • Follow this release process, but with release branch M.m instead of main.

Pre-release testing#

Automated tests#

  • Run the release workflow called “Build and deploy” manually on the release branch (see manually running a workflow). This is to verify 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 does NOT publish artifacts to pypi.

  • Run the bob 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)

    These tests take a long time. You can move to the Prepare the release section in the meantime.

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. You can run tools/format_GH_release_notes.py first, that will format the GH release notes in CHANGELOG_new.rst.

Steps#

  • Create a branch from the release branch.

  • Update CHANGELOG.rst.

  • Bump the version number in src/silx/_version.py.

  • Create a pull request to the release branch 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. - Select the release branch as the target. - Combine the release notes manually edited from CHANGELOG.rst with github automatically generated release notes.

  • Press the “Publish release” button to push the new tag to the release branch and trigger the release workflow which builds the documentation, the source tarball, the wheels and the Windows “fat binaries” of the release. You should see them starting from the actions page.

Note

If any step in the release process (such as creating wheels or building documentation) fails, you can cancel the github workflow, delete the github release and the associated tag. Then add new PR(s) and repeat the release operation.

Publish Windows “fat binaries”#

Once Windows “fat binaries” are built and tested, the release workflow requests the approval from a reviewer of the “assets” deployment environment. Upon approval, the following files are added to the github release assets:

  • silx-<release_version>-windows-application.zip

  • silx-<release_version>-windows-installer-x86_64.exe

Publish to pypi#

Once build and tests are completed, the release workflow requests the approval from a reviewer of the “pypi” 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.