Skip to content

Latest commit

 

History

History
114 lines (91 loc) · 5.21 KB

CONTRIBUTING.md

File metadata and controls

114 lines (91 loc) · 5.21 KB
Raw

How to contribute

  • Found a bug? Check if it was reported yet as a GitHub issues by-label, if not then file an issue
  • Want a feature? Check if it's already proposed as an enhancement issues , if not then file an issue

Every newly created issue gets assigned the triage issues label. Once reviewed, I exchange it for go ahead issues to signal it is of value to the project and can be worked on (for a feature), or that it is indeed a bug that we need to fix (for a bug).

Code contributions

You want to write code for the crate? Great! First, you need an issue to contribute to, one marked as go ahead issues. You can also use help wanted issues, meaning "I'd be very happy if someone implemented this", or good first issue issues, meaning "I'd be happy if someone implemented this and it's relatively straightforward". Go to the issue and post a comment that you're going to work on it. Fork the repo, write your feature of fix, then create a PR.

Setting up local development

The only non-standard tool that you might need is cargo-hack and Python. You can install the former with

cargo install cargo-hack

To run the test suite locally use:

cargo hack test --feature-powerset --skip default

Note: this requires your machine to support AVX2, as it is the default set in .cargo/config.toml. There are two solutions if that doesn't work for you:

  • If your machine supports a different SIMD target feature that is supported by aligners, run the command with custom RUSTFLAGS environment variable set to -C target-feature=+<your-feature-here>..
  • If your machine doesn't have any supported SIMD extensions, test only without the simd feature:
cargo hack test --feature-powerset --skip default --skip simd

To test the SimdBlock size depending on target features, run ./tests/test_simd_sizes.py. It assumes that your default /bin/python is Python 3, if that's not the case you can manually ask Python to run the script with python3 ./tests/test_simd_sizes.py.

There is no automated way to locally run the Miri test suite. You need to get familiar with Miri, install it, and then manually run the test for a target triple of your choice.

MIRIFLAGS="-Zmiri-symbolic-alignment-check -Zmiri-strict-provenance" cargo +nightly miri test --target x86_64-unknown-linux-gnu --no-default-features

Note: Miri does not support SIMD, so currently we test only the code without the simd feature.

Guidelines

  1. Use standard rustfmt settings for formatting.
  2. Lint your code with clippy.
  3. Follow Conventional Commits, more on it below.
  4. Avoid adding new dependencies to Cargo.toml unless there is a good reason for them.

Commit messages

Your commit messages should look like this:

type: short description of changes

More detailed description of my change.
Potentially multiline.

Refs: #69

# This project follows Conventional Commits 1.0.0 (https://www.conventionalcommits.org/en/v1.0.0/)
#
# The first line should be a short description of the purpose of the commit.
# Allowed types are: build, ci, docs, feat, fix, perf, refactor, style, test, chore
#
###
# Note: If introducing a breaking change, add an exclamation mark after the type
# Example: fix!: removed `AsRef` impl in favour of `relax_alignment`
### 
# The second section contains a detailed description.
# Always give a description for features,
# omit only for real one-liners like dependency bumps.
# Footer are at the end. Most important are refs, 
# which tell us which GitHub issue the change is related to, if any.
###
# Example:
###
# feat: add `std::cmp` trait impls for `AlignedSlice`
#
# - Added implementations of `PartialEq` and `Eq`.
# - Added `PartialEq<Vec<u8>>`, `PartialEq<[u8]>`, `PartialEq<u8; N>`.
# - Added `PartialOrd` and `Ord`.
#
# Refs: #69