Contributing

Getting Started for Local Development¶

We recommend using Tox to setup the development environment. This will create a new virtual environment with all of the required packages installed and ProxyStore installed in editable mode with the necessary extras options.

$ git clone https://github.com/proxystore/extensions
$ cd extensions
$ tox --devenv venv -e py311
$ . venv/bin/activate

Warning

Running Tox in a Conda environment is possible but it may conflict with Tox's ability to find the correct Python versions. E.g., if your Conda environment is Python 3.9, running $ tox -e p38 may still use Python 3.9.

To install manually:

$ git clone https://github.com/proxystore/extensions
$ cd extensions
$ python -m venv venv
$ . venv/bin/activate
$ pip install -e .[dev,docs]

Continuous Integration¶

ProxyStore uses pre-commit and Tox for continuous integration (test, linting, etc.).

Linting and Type Checking (pre-commit)¶

To use pre-commit, install the hook and then run against files.

$ pre-commit install
$ pre-commit run --all-files

Tests (tox)¶

The entire CI workflow can be run with $ tox. This will test against multiple versions of Python and can be slow.

Module-level unit-test are located in the tests/ directory and its structure is intended to match that of proxystore_ex/. E.g. the tests for proxystore_ex/x/y.py are located in tests/x/y_test.py; however, additional test files can be added as needed. Tests should be narrowly focused and target a single aspect of the code's functionality, tests should not test internal implementation details of the code, and tests should not be dependent on the order in which they are run.

Code that is useful for building tests but is not a test itself belongs in the testing/ directory.

# Run all tests in tests/
$ tox -e py311
# Run a specific test
$ tox -e py311 -- tests/x/y_test.py::test_z

Tests (docker)¶

The test suite mocks certain third-party programs that cannot be installed via pip (e.g., Margo, UCX, Redis). For Margo and UCX, a Docker image is provided at proxystore/images with the software pre-built and Python installed. The tox environments py{version}-dim can be run in the container to validate changes against the un-mocked software.

$ docker pull ghcr.io/proxystore/proxystore-dim:nightly
# Be sure to change the path to your proxystore repo directory
$ docker run --rm -it --network host -v /path/to/proxystore:/proxystore ghcr.io/proxystore/proxystore-dim:nightly
# Inside container
$ tox -e py311-dim

Docs¶

If code changes require an update to the documentation (e.g., for function signature changes, new modules, etc.), the documentation can be built using MKDocs.

# Manually
$ pip install -e .[docs]
$ mkdocs build --strict  # Build only to site/index.html
$ mkdocs serve           # Serve locally

# With tox (will only build, does not serve)
$ tox -e docs

Docstrings are automatically generated, but it is recommended to check the generated docstrings to make sure details/links/etc. are correct.