Skip to content

Contributing to Linax¤

Thank you for your interest in contributing to Linax! 🎉

We welcome contributions of all kinds: bug reports, feature requests, documentation improvements, and code contributions.

Table of Contents¤

Getting Started¤

Before contributing, please:

  1. Check existing issues to see if someone is already working on it
  2. Open an issue to discuss major changes before implementing them
  3. Read our Code of Conduct and follow community standards

Development Setup¤

Prerequisites¤

  • Python 3.12
  • uv package manager

Installation Steps¤

  1. Fork and clone the repository:
git clone git@github.com:camail-official/linax.git
cd linax
  1. Install dependencies (including dev tools):
uv sync --extra dev
  1. Install pre-commit hooks:
uv run pre-commit install

This will automatically run linters and formatters before each commit.

Optional: CUDA Support¤

If you have a CUDA capable GPU:

uv sync --extra cu12 --extra dev

Code Style¤

We use the following tools to maintain code quality:

  • Ruff - Linting and formatting
  • Pre-commit hooks - Automatic checks before commits

Running Code Quality Checks¤

# Run all pre-commit hooks manually
uv run pre-commit run --all-files

# Run ruff linter
uv run ruff check src/ tests/

# Run ruff formatter
uv run ruff format src/ tests/

Style Guidelines¤

  • Follow PEP 8 conventions
  • Use Google-style docstrings
  • Maximum line length: 99 characters
  • Type hints are required for all public functions
  • Use jaxtyping for array shape annotations

Example:

from jaxtyping import Array, Float

def my_function(x: Float[Array, "batch features"]) -> Float[Array, "batch"]:
    """Brief description of the function.

    Args:
        x: Input array with shape (batch, features).

    Returns:
        Processed array with shape (batch,).
    """
    return x.sum(axis=-1)

Testing¤

We use pytest for testing.

Running Tests¤

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_smoke.py

# Run with coverage
uv run pytest --cov=linax

Writing Tests¤

  • Place tests in the tests/ directory
  • Name test files test_*.py
  • Name test functions test_*
  • Include docstrings explaining what the test validates

Submitting Changes¤

Pull Request Process¤

  1. Create a feature branch:
git checkout -b feature/your-feature-name
  1. Make your changes:
  2. Write clear, concise commit messages
  3. Add tests for new functionality

  4. Update documentation as needed

  5. Ensure all checks pass:

uv run pre-commit run --all-files
uv run pytest
  1. Push to your fork:
git push origin feature/your-feature-name
  1. Open a Pull Request:
  2. Use a clear, descriptive title
  3. Fill out the PR template completely
  4. Link any related issues

Commit Message Guidelines¤

Write clear, descriptive commit messages that explain what changed:

Good: 

Add LRU sequence mixer implementation
Fix gradient computation in LinOSS
Update README installation instructions
Add tests for S5 model

Not so good: 

fix
update
wip
changes

Tips: - Use the imperative mood ("Add feature" not "Added feature") - Be specific about what changed - Reference issue numbers if applicable (e.g., "Fix #123")

Community¤

Questions?¤

If you have questions about contributing, feel free to:

Thank you for contributing to Linax! 🚀