Debian Codegraph @

guide/src/contributing.md

raw
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 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](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.