Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
109 lines (83 loc) · 4.98 KB

CONTRIBUTING.md

File metadata and controls

109 lines (83 loc) · 4.98 KB

Contribution guide

Rust

  • Before you commit, make sure that you have pre-commit installed. This will ensure that the code is formatted correctly and that it compiles properly. Also, check if your changes introduce any new linter warnings by running cargo clippy.
  • Make sure to keep CHANGELOG.md up-to-date.
  • Make sure to follow the Rust API Guidelines

Increasing the minimum supported Rust version (MSRV)

Do not change the MSRV for releases with increased patch version number. When increasing the MSRV make sure to set it everywhere to the same value:

  1. first update the container file maintainer/Containerfile, by
    • adding the new MSRV to the variable RUST_V,
    • making sure the nightly version is the last entry and
    • leaving in the previous MSRV to not break the CI in between the transition from it
    • removing the oldest stable version
  2. commit the previous changes and manually run the Container GitHub action
  3. next, update the MSRV in the following files:
    • in the top-level Cargo.toml; all other projects in the workspace should inherit the setting in their respective Cargo.toml files
    • in README.md and docs/installation.md
    • in .readthedocs.yml update the value of the rust field and make sure RTD supports it
  4. commit the previous changes and push them after the container created by step 2 is ready

Coding guidelines

  • avoid the use of indices whenever possible; use Iterator instead.
  • use the unwrap methods whenever a panic would signal a bug in the program, and use Result instead if errors should be propagated down to the user. When using unwrap, document the nature of the bug if a panic happens with a comment of the form: // UNWRAP: ....
  • in APIs prefer unwrap_or_else(|| unreachable!()) over unwrap whenever this avoids the clippy warning that a Panic section is missing. Also document this with // UNWRAP: ...

Writing tests that need test data

  • if you write a test that needs test data (grids, EKOs, etc.) store them at https://data.nnpdf.science/pineappl/test-data/. Ask one of the maintainers to upload the data for you if you don't have access to this location. Then add a line to maintainer/download-test-data.sh that downloads the files and increase the version integer test-data-vXX in .github/actions/cache-test-data/action.yml. To make GitHub refresh the cached test data when running the CI, increase the integer XX in the line key: test-data-vXX by one.

Regression tests for GitHub Issues

If you're writing a regression test for a GitHub Issue, name the test issue_XXX, where XXX is the GitHub Issue number.

Git

  • When you commit, make sure the commit message is written properly. This blogpost explains it nicely: https://chris.beams.io/posts/git-commit/.
  • Whenever you have unpushed local commits that are behind origin/master, use git pull --rebase to rebase them
  • When editing GitHub workflow files, use a separate branch, because usually many commits are needed to get something working. When merging this branch into master (or any other branch), squash-merge the commits; the exact history in this case is not important

Making a new release

First make sure the release workflow works; since we've hard-coded runner image and action versions, it's possible that some workflows must be updated if these images don't exist anymore. To check whether that's the case, manually trigger the following workflows:

This will not upload anything. Wait for the actions to finish, and fix problems in a separate branch.

Next, go to the maintainers directory, run

./make_release 0.5.4

and replace 0.5.4 with a version string, not including v at the start. The version strings must adhere to Semantic Versioning.

This will take care of almost everything: the C, Python and Rust interfaces and their documentation. After some time also a new Conda package will be generated, for which the pull request will have to be accepted manually though.

Updating the CI's container

To update the software the CI runs with, modify maintainer/Containerfile maintainer/build-container.sh. See also maintainer/README.md for a description of what these files do. To generate a new container, you need to manually run the Container action from the branch in which you modified the container files. After the container has been generated, all following commits in every branch will use the new container.