Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (74 loc) · 3.32 KB

CONTRIBUTING.md

File metadata and controls

115 lines (74 loc) · 3.32 KB

Contributing to OpTree

Before contributing to OpTree, please follow the instructions below to setup.

  1. Fork OpTree (fork) on GitHub and clone the repository.

    git clone git@github.com:<your username>/optree.git  # use the SSH protocol
cd optree

git remote add upstream git@github.com:metaopt/optree.git

  2. Setup a development environment via conda:

    conda env create --file conda-recipe.yaml

conda activate optree

  3. Setup the pre-commit hooks:

    pre-commit install --install-hooks

Then you are ready to rock. Thanks for contributing to OpTree!

Install Develop Version

To install OpTree in an "editable" mode, run:

make install-editable  # or run `pip3 install --no-build-isolation --editable .`

in the main directory. This installation is removable by:

make uninstall

Lint Check

We use several tools to secure code quality, including:

  • Python code style: ruff, isort, pylint
  • Type hint check: mypy
  • C++ code style: cpplint, clang-format, clang-tidy
  • License: addlicense
  • Documentation: pydocstyle, doc8, xdoctest

To make things easier, we create several shortcuts as follows.

To automatically format the code, run:

make format

To check if everything conforms to the specification, run:

make lint

Test Locally

This command will run automatic tests in the main directory:

make test

Build Wheels

To build compatible manylinux2014 (PEP 599) wheels for distribution, you can use cibuildwheel. You will need to install docker first. Then run the following command:

python3 -m pip install --upgrade cibuildwheel

python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

It will build wheel binaries for all supported CPython versions. The outputs will be placed in the wheelhouse directory.

To build a wheel for a specific CPython version, you can use the CIBW_BUILD environment variable. For example, the following command will build a wheel for Python 3.9:

CIBW_BUILD="cp39*manylinux*" python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

You can change cp39* to cp312* to build for Python 3.12. See https://cibuildwheel.readthedocs.io/en/stable/options for more options.

Documentation

Documentation is written under the docs/source directory as ReStructuredText (.rst) files. index.rst is the main page. A Tutorial on ReStructuredText can be found here.

API References are automatically generated by Sphinx and should be modified when any code changes.

To compile documentation into webpage, run

make docs

The generated webpage is located under directory docs/build and will open the browser after building documentation.

Detailed documentation is hosted online at https://optree.readthedocs.io.