Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (80 loc) · 4.88 KB

CONTRIBUTING.md

File metadata and controls

130 lines (80 loc) · 4.88 KB

Contributing to AIF-Gen

Prerequisites

The project uses uv to manage and lock project dependencies for a consistent and reproducible environment. If you do not have uv installed on your system, visit this page for installation instructions.

Note: If you have pip installed globally you can just invoke:

pip install uv

Using uv

Background

uv manages a lockfile which maintains a consistent and fixed dependency graph for all AIF-Gen dependencies. These dependencies are bundled in a python virtual environment stored in a hidden .venv folder in the root project directory. The virtual environment is generated on the fly based on the lockfile and is created upon calling uv sync.

Running commands

uv bundles all dependencies (including Python itself) into the virtual environment. Most commands can be run by simply prepending uv run to the respective command.

For example:

  • Instead of running python <command>, you will run uv run python <command>
  • Instead of running pytest, you will run uv run pytest

Adding and Removing Dependencies

uv has a package resolver which will automatically resolve all packages to their most recent version at the time of installation while respecting the current dependencies.

To add or remove a core dependency, issue uv add <package> and uv remove <package>, respectively. For instance, to add numpy as a core dependency, we would issue:

uv add numpy

Note: this will automatically update the pyproject.toml and uv lock file with the new package which will be reflected in version control.

In order to facilitate modularity and avoid burdening users with dependencies they don't need, it's recommended to minimize core dependencies to those that all users will require for every release. To support this, uv has the notion of dependency groups, which facilitate auxilary dependencies. For instance, the dev group is the set of dependencies required for openDG development, but is not necessarily shipped to end-users of the library.

To add or remove a package from a dependency group, issue uv add --<group> <package> and uv remove --<group> <package>, respectively. For instance, to add hypothesis as a dev dependancy, we would issue:

uv add --dev hypothesis

Note, that auxilary dependency groups can be synced by running uv sync --group <group name>.

In general, any wheels published on pypi can be directly added, making uv a drop-in replacement for pip. For more complex use cases such as non-python dependencies, or installing specific package versions, consult the uv documentation.

Activating the virtual environment

Sometimes you will want to activate the virtual environment manually in order to access the dependencies explicitly (for instance, for integration with a language server for code completion). The virtual environment can be activated by invoking the appropriate activation file, dependencing on your shell. For instance, for bash, you can issue:

. .venv/bin/activate

to activate the environment.

Note: after doing so, you will have direct access to all executables (e.g. Python) as usual.

Dev Installation

Install AIF-Gen

From Source

# Clone the repo
git clone https://github.com/ComplexData-MILA/AIF-Gen.git
cd AIF-Gen

# Install core dependencies into an isolated environment
uv sync

Install pre-commit hooks:

AIF-Gen ships with a set of pre-commit hooks that automatically apply code formatting, linting, static type analysis, and more.

The hooks can be installed by issuing:

uv run pre-commit install

It is recommended to use these hooks when commiting code remotely but they can also be skipped by commiting with the --no-verify flag.

Unit Testing

The AIF-Gen test suite is located uner test/. Run the entire test suite with

uv run pytest

Continuous Integration

AIF-Gen uses Github Actions for continuous integration.

Everytime you send a Pull Request, your commit will be built and checked against the AIF-Gen guidelines:

  1. Ensure that your code is formatted correctly. We use the Ruff-Formatter.

    uv run ruff format .

    The pre-commit hooks will auto-format your code according to our style spec.

  2. Ensure that the entire test suite passes and that code coverage roughly stays the same.

    uv run pytest --cov

Building Documentation

To build the documentation:

  1. Build and install AIF-Gen from source.
  2. Generate the documentation via: 
    uv sync --group docs
uv run mkdocs serve