Skip to content

Latest commit

 

History

History
147 lines (100 loc) · 4.74 KB

CONTRIBUTING.md

File metadata and controls

147 lines (100 loc) · 4.74 KB
Raw

Contributing to Polars

We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Adding/Proposing new features

We Develop with GitHub

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

  1. Fork the repo and create your branch from master.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes: 
    # For Rust code in ./polars in subdir
cd ./polars
make test

# For Python code and Rust code in ./py-polars subdir.
cd ./py-polars
make test
  5. Make sure your code lints: 
    # For Rust code in ./polars subdir.
#   - cargo clippy: Lint Rust code (./polars/).
#   - cargo fmt: Format Rust code (./polars/).
#   - dprint fmt: Format TOML files.
cd ./polars
make clippy
make fmt

# For Python code and rust code in ./py-polars subdir:
#   - isort: Sort Python imports.
#   - black: Format Python code.
#   - blackdoc: Format Python doctests.
#   - mypy: Type checking of Python code.
#   - flake8: Enforce Python style guide.
#   - dprint fmt: Format TOML files.
#   - cargo fmt: Format Rust code (./py-polars/src).
cd ./py-polars
make pre-commit
  6. Issue that pull request!

Want to discuss something?

I can imagine that some questions don't fit an issue. Therefore there is also a Polars Discord server.

Any contributions you make will be under the MIT Software License

In short, when you submit code changes, your submissions are understood to be under the same MIT License that covers the project. Feel free to contact the maintainers if that's a concern.

Report bugs using GitHub's issues

We use GitHub issues to track public bugs. Report a bug by opening a new issue.

Great Bug Reports tend to have:

  • A quick summary and/or background
  • Steps to reproduce
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

Code formatting

We test the code formatting in the CI pipelines. If you don't want these to fail, you need to format:

  • Rust code with:

    • cargo fmt
      • In ./polars subdir: $ cargo fmt --all
      • In ./py-polars subdir for Rust Python-bindings: $ cargo fmt --all

  • Python code with:

    • isort (version 5.9.2):
      • Sort Python imports.
      • isort .
    • black (version 21.6b0):
      • Format Python code.
      • black .

  • Python code in doctests:

  • TOML files with:

    • dprint (version 0.18.2):
      • $ dprint fmt

See 5. Make sure your code lints for running it easily.

Linting

We use linters to enforce code quality. This will be checked in CI.

  • Rust:

  • Python:

See 5. Make sure your code lints for running it easily.

Type checking

For Python, type hints are enforced using mypy. This will be checked in CI.

See 5. Make sure your code lints. for running it easily.

Testing

See 4. Ensure the test suite passes for running it easily.

Python setup

If you want to contribute to the Python code, you also have to setup a Rust installation to be able to test your changes. You have to follow these steps:

  • Install Rust nightly via rustup
  • run $ rustup override set nightly from the root of the repo.
  • from ./py-polars run $ make venv
  • tests: from ./py-polars run $ make test
  • formatting + linting: from ./py-polars run $ make pre-commit before committing.
  • docs: from ./py-polars/docs run $ pip3 install -r requirements-docs.txt followed by make html

make test installs a (slow) development build in your current environment and runs pytest.

License

By contributing, you agree that your contributions will be licensed under its MIT License.