| 1 |
# Contributing |
| 2 |
|
| 3 |
Contributions are welcome, and they are greatly appreciated! |
| 4 |
|
| 5 |
You can contribute in many ways: |
| 6 |
|
| 7 |
## Types of Contributions |
| 8 |
|
| 9 |
### Report Bugs |
| 10 |
|
| 11 |
Report bugs at [https://github.com/PyO3/maturin/issues](https://github.com/PyO3/maturin/issues). |
| 12 |
|
| 13 |
### Fix Bugs |
| 14 |
|
| 15 |
Look through the GitHub issues for bugs. Anything tagged with `bug` |
| 16 |
and `help wanted` is open to whoever wants to implement it. |
| 17 |
|
| 18 |
### Implement Features |
| 19 |
|
| 20 |
Look through the GitHub issues for features. |
| 21 |
|
| 22 |
### Write Documentation |
| 23 |
|
| 24 |
Maturin could always use more documentation, whether as part of the official |
| 25 |
guide, in docstrings or even on the web in blog posts, articles and such. |
| 26 |
|
| 27 |
### Submit Feedback |
| 28 |
|
| 29 |
The best way to send feedback is to start a new discussion |
| 30 |
at [https://github.com/PyO3/maturin/discussions](https://github.com/PyO3/maturin/discussions). |
| 31 |
|
| 32 |
## Get Started! |
| 33 |
|
| 34 |
Ready to contribute? Here's how to setup maturin for local development. |
| 35 |
|
| 36 |
1. Fork the maturin repository on GitHub. |
| 37 |
2. Clone your fork locally: |
| 38 |
```bash |
| 39 |
$ git clone [email protected]:your_name_here/maturin.git |
| 40 |
``` |
| 41 |
3. [Install a stable Rust toolchain](https://www.rust-lang.org/tools/install) |
| 42 |
and of course [Python 3.6 or later is also required](https://realpython.com/installing-python/). |
| 43 |
4. Create a branch for local development: |
| 44 |
```bash |
| 45 |
$ cd maturin |
| 46 |
$ git checkout -b branch-name |
| 47 |
``` |
| 48 |
Now you can make your changes locally. |
| 49 |
5. When you're done making changes, ensure the tests pass by running |
| 50 |
```bash |
| 51 |
$ cargo test |
| 52 |
``` |
| 53 |
Note that in order to run tests you need to install `virtualenv` (`pip install virtualenv`). |
| 54 |
6. make sure your changes are well formatted and pass the linting checks by |
| 55 |
installing [pre-commit](https://pre-commit.com/) and running |
| 56 |
```bash |
| 57 |
$ pre-commit run --hook-stage manual --all |
| 58 |
``` |
| 59 |
running `pre-commit install` will enable running the checks automatically before every commit |
| 60 |
(except for the slow checks: `cargo check` and `cargo clippy` which are only run manually). |
| 61 |
You can also look at `.pre-commit-config.yaml` and run the individual checks yourself if you prefer. |
| 62 |
7. Commit your changes and push your branch to GitHub: |
| 63 |
```bash |
| 64 |
$ git add . |
| 65 |
$ git commit |
| 66 |
$ git push origin branch-name |
| 67 |
``` |
| 68 |
8. Submit a pull request through the [GitHub website](https://github.com/PyO3/maturin/pulls). |
| 69 |
|
| 70 |
We provide a pre-configured [dev container](https://containers.dev/) that could be used in [Github Codespaces](https://github.com/features/codespaces), [VSCode](https://code.visualstudio.com/), [JetBrains](https://www.jetbrains.com/remote-development/gateway/), [JuptyerLab](https://jupyterlab.readthedocs.io/en/stable/). |
| 71 |
|
| 72 |
[](https://codespaces.new/pyo3/maturin?quickstart=1&machine=standardLinux32gb) |
| 73 |
|
| 74 |
## Pull Request Guidelines |
| 75 |
|
| 76 |
Before you submit a pull request, check that it meets these guidelines: |
| 77 |
|
| 78 |
1. The pull request should include tests if it adds or changes functionalities. |
| 79 |
2. Add a [changelog](https://github.com/PyO3/maturin/blob/main/Changelog.md) |
| 80 |
entry. |
| 81 |
3. When command line interface changes, run `python3 test-crates/update_readme.py` to update related documentation. |
| 82 |
|
| 83 |
## Guide |
| 84 |
|
| 85 |
To build the guide for local viewing, install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and |
| 86 |
run `mdbook watch guide` from the repository root. The output can then be found at `guide/book/index.html`. |
| 87 |
|
| 88 |
## Code |
| 89 |
|
| 90 |
The main part is the maturin library, which is completely documented and should be well integrable. The accompanying `main.rs` takes care username and password for the pypi upload and otherwise calls into the library. |
| 91 |
|
| 92 |
The `sysconfig` folder contains the output of `python -m sysconfig` for different python versions and platform, which is helpful during development. |
| 93 |
|
| 94 |
You need to install `cffi` and `virtualenv` (`pip install cffi virtualenv`) to run the tests. |
| 95 |
|
| 96 |
You can set the `MATURIN_TEST_PYTHON` environment variable to run the tests against a specific Python version, |
| 97 |
for example `MATURIN_TEST_PYTHON=python3.11 cargo test` will run the tests against Python 3.11. |
| 98 |
|
| 99 |
There are some optional hacks that can speed up the tests (over 80s to 17s on my machine). |
| 100 |
1. By running `cargo build --release --manifest-path test-crates/cargo-mock/Cargo.toml` you can activate a cargo cache avoiding to rebuild the pyo3 test crates with every python version. |
| 101 |
2. Delete `target/test-cache` to clear the cache (e.g. after changing a test crate) or remove `test-crates/cargo-mock/target/release/cargo` to deactivate it. |
| 102 |
3. By running the tests with the `faster-tests` feature, binaries are stripped and wheels are only stored and not compressed. |