Skip to content

Latest commit

 

History

History
149 lines (112 loc) · 4.53 KB

CONTRIBUTING.md

File metadata and controls

149 lines (112 loc) · 4.53 KB

scipy-stubs pull request guidelines

Pull requests are always welcome, and the SciPy community appreciates any help you provide. Note that a Code of Conduct applies to all spaces managed by the SciPy project, including issues and pull requests.

When submitting a pull request, we ask you to check the following:

  1. Tests, documentation, and code style are in order, and no errors are reported by type-checkers and stubgen. For details, see the Local development section.

    It's also OK to submit work in progress if you're unsure of what this exactly means, in which case you'll likely be asked to make some further changes.

  2. The contributed code will be licensed under scipy-stubs' license. If you did not write the code yourself, you must ensure the existing license is compatible and include the license information in the contributed files, or obtain permission from the original author to relicense the contributed code.

Local development

Ensure you have uv installed. Now you can install the project with the dev dependencies:

uv sync --python 3.10

By installing the lowest support Python version (3.10 in this example), it prevents your IDE from e.g. auto-importing unsupported typing features.

pre-commit

scipy-stubs uses pre-commit to ensure that the code is formatted and type-checked when committing the changes. Running this will be slightly faster if pre-commit-uv is additionally installed:

uv tool install pre-commit --with pre-commit-uv --force-reinstall
Output: 
Resolved 11 packages in 74ms
Prepared 11 packages in 1ms
Uninstalled 11 packages in 9ms
Installed 11 packages in 10ms
 ~ cfgv==3.4.0
 ~ distlib==0.3.9
 ~ filelock==3.17.0
 ~ identify==2.6.6
 ~ nodeenv==1.9.1
 ~ platformdirs==4.3.6
 ~ pre-commit==4.1.0
 ~ pre-commit-uv==4.1.4
 ~ pyyaml==6.0.2
 ~ uv==0.5.23
 ~ virtualenv==20.29.1
Installed 1 executable: pre-commit

Now to install the git hook script, make sure that you are in the root directory of the scipy-stubs repo, then run:

uvx pre-commit install

Output:

pre-commit installed at .git/hooks/pre-commit

Note

For performance reasons, pre-commit won't run mypy and stubtest. You could do this yourself with tox -e mypy and tox -e stubtest, as explained in the next section. That way you won't have to rely on the (slow) github actions workflow when you submit your PR.

Tox

The pre-commit hooks and stubtest can easily be run with tox. It can be installed as a uv tool:

uv tool install tox --with tox-uv --upgrade

To run all environments (in parallel), run:

uvx tox p
Output: 
lint: OK ✔ in 0.52 seconds
pre-commit: OK ✔ in 2.59 seconds
3.11: OK ✔ in 21.59 seconds
mypy: OK ✔ in 21.62 seconds
pyright: OK ✔ in 25.23 seconds
3.10: OK ✔ in 25.4 seconds
3.12: OK ✔ in 38.71 seconds
  pre-commit: OK (2.59=setup[0.03]+cmd[2.56] seconds)
  lint: OK (0.52=setup[0.04]+cmd[0.41,0.03,0.05] seconds)
  pyright: OK (25.23=setup[0.03]+cmd[25.20] seconds)
  mypy: OK (21.62=setup[0.03]+cmd[21.59] seconds)
  3.13: OK (53.28=setup[0.03]+cmd[53.25] seconds)
  3.12: OK (38.71=setup[0.03]+cmd[38.68] seconds)
  3.11: OK (21.59=setup[0.03]+cmd[21.55] seconds)
  3.10: OK (25.40=setup[0.03]+cmd[25.36] seconds)
  congratulations :) (53.35 seconds)

Documentation

All [documentation] lives in the README.md. Please read it carefully before proposing any changes. Ensure that the markdown is formatted correctly with markdownlint, by enabling pre-commit.

Testing

See the README.md in scipy-stubs/tests.

Code style

See https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#style-guide.

Commit message style

Scipy-stubs recommends using Gitmoji for commit messages and PR titles. For VSCode and VSCodium users, it is recommended to use the gitmoji-vscode extension for this.