Contributing to CoLA

Thanks for contributing!

Development installation

To get the development installation with all the necessary dependencies for linting, testing, and building the documentation, run the following:

git clone https://github.com/wilson-labs/cola.git
cd cola
pip install -e ".[dev]"
pip install -r docs/requirements.txt

In order to properly develop for CoLA, you will need to have both JaX and PyTorch installed.

To easily and automatically follow the format used in CoLA (contained in setup.cfg), you can run pre-commit install. This command would create a list of pre-commit hooks which would run the format and linting automatically.

Our Development Process

Docstrings

We use Google-style docstrings. If you are not familiar with this style, look around the code base for examples.

Unit Tests

We use pytest to run unit tests:

pytest -m "not tricky and not big" tests/

The not big excludes tests of very large matrices, and not tricky excludes some known edge cases and situations that are not easy to solve right away. To isolate these tricky cases, just run pytest -m "tricky" tests/. There are also marks for torch and jax to isolate tests only for that framework.

Tests can be filtered with -k, such as

pytest -m "not tricky and not big" -k "trace" tests/

to get tests involving the trace.

You can also

  • run tests within a specific directory, run (e.g.) pytest tests/algorithms/.

  • run a specific unit test, run (e.g.) pytest tests/algorithms/test_cg.py::test_cg_vjp.

Documentation

CoLA uses sphinx to generate documentation, and ReadTheDocs to host documentation. To build the documentation locally, ensure that sphinx and its plugins are properly installed (see the development installation section for instructions). Then run:

cd docs
make html
cd build/html
python -m http.server 8000

The documentation will be available at http://localhost:8000. You will have to rerun the make html command every time you wish to update the docs.

Pull Requests

We greatly appreciate PRs! To minimze back-and-forward communication, please ensure that your PR includes the following:

  1. Code changes. (the bug fix/new feature/updated documentation/etc.)

  2. Unit tests. If you are updating any code, you should add an appropraite unit test.

    • If you are fixing a bug, make sure that there’s a new unit test that catches the bug. (I.e., there should be a new unit test that fails before your bug fix, but passes after your bug fix. This ensures that we don’t have any accidental regressions in the code base.)

    • If you are adding a new feature, you should add unit tests for this new feature.

  3. Documentation. Any new objects/methods should have appropriate docstrings.

Before submitting a PR, ensure the following:

  1. Unit tests pass. See the unit tests section for more info.

  2. Documentation renders correctly without warnings. Build the documentation locally to ensure that your new class/docstrings are rendered correctly. Ensure that sphinx can build the documentation without warnings.

Issues

We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.

We accept the following types of issues:

  • Bug reports

  • Requests for documentation/examples

  • Feature requests

  • Opportuntities to refactor code

  • Performance issues (speed, memory, etc.)

License

By contributing to CoLA, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.