How to contribute#

Development process#

This project follows the standard open-source project github workflow, which is described in other projects like scikit-image.

  1. Create your GitHub account and upload your SSH keys.

  2. Fork the silx project from silx-kit/silx.

  3. Clone your GitHub repository on yout local computer.

git clone git@github.com/<your_user_name>/silx
cd silx

  1. Install the dependencies defined in requirements-dev.txt.

pip install -r requirements-dev.txt

  1. Make sure the silx test suite pass on your computer using the python3 run_tests.py or python3 run_tests.py silx.gui.test.test_qt if you want to test only a subset of it. You can use python /path/to/silx/bootstrap.py script.py to test your scripts without installing silx, but the test suite is required to pass.

  2. Open an issue in https://github.com/silx-kit/silx/issues to inform the maintainers of your intentions.

  3. Create a local branch to start working on your issue git branch my_feature.

  4. Code, enjoy but ensure that the new code is tested and does not break the current test suite.

  5. Push your local branch to your GitHub account: git push origin my_feature.

  6. Create a pull request (PR) from your feature branch on GitHub to trigger the review process. Indicate this PR is related to the issue you opened in 6. Make sure to follow the Pull Request title format.

  7. Discuss with the maintainer who is reviewing your code using the GitHub interface.

If you encounter any problems or have any questions you can always ask on the Issues page.

Pull Request title format#

To ease release notes authoring, when creating a Pull Request (PR), please use the following syntax for the title:

<Subpackage/Module/Topic>: <Action> <summary of the main change affecting silx's users>

With:

  • Subpackage/Topic: One of:

    • A subpackage or a module: Use the fully qualified name of the subpackage or module of silx the PR is changing. For example: silx.gui.qt or silx.gui.plot.PlotWidget.

    • A topic: If changes do not affect a particular subpackage or module, provide the topic of the change. This can be for example: Build, Documentation, CI,… or the name of a silx application (e.g., silx view).

  • Action: How the changes affects the project from a silx user point of view. Prefer using one of the following actions:

    • Added: For new feature or new APIs

    • Deprecated

    • Removed

    • Changed

    • Improved

    • Refactored

    • Fixed

    • More: If none of the previous actions match your changes, please use another keyword.

  • Summary: A short description of the main change as you would like to read it from release notes.

Code formatting#

To format the code, use black.

How-to build the documentation#

To build the documentation, using Sphinx, run:

pip install .  # Make sure to install the same version as the source
sphinx-build doc/source/ build/html

Note

To re-generate the example script screenshots, build the documentation with the environment variable DIRECTIVE_SNAPSHOT_QT set to True.

How-to run the tests#

To run the tests of an installed version of silx, run the following on the python interpreter:

import silx.test
silx.test.run_tests()

To run the test suite of a development version, use the run_tests.py script at the root of the source project.

python ./run_tests.py

How-to make a release#

Use cases#

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

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)

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#

  • 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.

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.