Contributing to Vector Inference¶

Thank you for your interest in contributing to Vector Inference! This guide will help you get started with development, testing, and documentation contributions.

Development Setup¶

Prerequisites¶

Python 3.10 or newer
uv for dependency management

Setting Up Development Environment¶

Clone the repository:

git clone https://github.com/VectorInstitute/vector-inference.git
cd vector-inference

Install development dependencies:
```
uv sync --all-extras --group dev
```
Install pre-commit hooks:
```
pre-commit install
```

Using Virtual Environments

If you prefer using virtual environments, you can use uv venv to create one:

uv venv
source .venv/bin/activate

Development Workflow¶

Code Style and Linting¶

We use several tools to ensure code quality:

ruff for linting and formatting
mypy for type checking

You can run these tools with:

# Linting
uv run ruff check .

# Type checking
uv run mypy

# Format code
uv run ruff format .

Pre-commit Hooks

The pre-commit hooks will automatically run these checks before each commit. If the hooks fail, you will need to fix the issues before you can commit.

Testing¶

All new features and bug fixes should include tests. We use pytest for testing:

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=vec_inf

Documentation¶

Documentation Setup¶

Install the documentation dependencies:

uv sync --group docs

Building Documentation¶

Build and serve the documentation locally:

# Standard build
mkdocs build

# Serve locally with hot-reload
mkdocs serve

Versioned Documentation¶

Vector Inference uses mike to manage versioned documentation. This allows users to access documentation for specific versions of the library.

Available Versions¶

The documentation is available in multiple versions:

latest - Always points to the most recent stable release
Version-specific documentation (e.g., 0.5.0, 0.4.0)

Versioning Strategy¶

Our versioning strategy follows these rules:

Each release gets its own version number matching the package version (e.g., 0.5.0)
The latest alias always points to the most recent stable release
Documentation is automatically deployed when changes are pushed to the main branch

Working with Mike Locally¶

To preview or work with versioned documentation:

# Build and deploy a specific version to your local gh-pages branch
mike deploy 0.5.0

# Add an alias for the latest version
mike deploy 0.5.0 latest

# Set the default version to redirect to
mike set-default latest

# View the deployed versions
mike list

# Serve the versioned documentation locally
mike serve

Automatic Documentation Deployment¶

Documentation is automatically deployed through GitHub Actions:

On pushes to main, documentation is deployed with the version from pyproject.toml and the latest alias
Through manual trigger in the GitHub Actions workflow, where you can specify the version to deploy

When to Update Documentation

When adding new features
When changing existing APIs
When fixing bugs that affect user experience
When improving explanations or examples

Pull Request Process¶

Fork the repository and create your branch from main
Make your changes and add appropriate tests
Ensure tests pass and code meets style guidelines
Write clear documentation for your changes
Submit a pull request with a clear description of the changes

Checklist Before Submitting PR

[ ] All tests pass
[ ] Code is formatted with ruff
[ ] Type annotations are correct
[ ] Documentation is updated
[ ] Commit messages are clear and descriptive

Release Process¶

Update version in pyproject.toml
Update changelogs and documentation as needed
Create a new tag and release on GitHub
Documentation for the new version will be automatically deployed

License¶

By contributing to Vector Inference, you agree that your contributions will be licensed under the project's MIT License.