Skip to content

Latest commit

 

History

History
195 lines (130 loc) · 7.77 KB

CONTRIBUTING.rst

File metadata and controls

195 lines (130 loc) · 7.77 KB
Raw

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.

scikit-image provides a nice tutorial in their own CONTRIBUTING guide.

  1. Create your GitHub account https://help.github.com/categories/setup/ and upload your SSH keys.
  2. Fork the silx project from https://github.com/silx-kit/silx/. The button is on the top right of the page.
  3. Clone your GitHub version locally on the computer you intend to work on.
git clone git@github.com/<your_user_name>/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.
  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, please use the following syntax for the title of your Pull Requests (PR):

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

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, the wheels and the Windows "fat binaries".

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.