Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (111 loc) · 5.28 KB

CONTRIBUTING.md

File metadata and controls

161 lines (111 loc) · 5.28 KB

Contributing to Apache Mahout

Thank you for your interest in contributing to Apache Mahout!

This document describes repository-wide setup and workflow. For subproject-specific build, test, and development details, see the Project-Specific Guides below.

Table of Contents

Quick Start

For QDP environment and command-level setup (including root .venv workflow), see qdp/DEVELOPMENT.md.

Prerequisites

  • Python 3.10 (>=3.10,<3.14)
  • uv package manager
  • Git

Installation

  1. Install uv:

    pip install uv

  2. Clone and install:

    git clone https://github.com/apache/mahout.git
cd mahout
uv sync --group dev              # Core Qumat (no GPU required)
# uv sync --group dev --extra qdp  # With QDP extension (requires CUDA GPU)

    Add --extra qdp if you need GPU-accelerated encoding or want to run QDP tests. QDP tests are auto-skipped if the extension is not installed.

  3. Set up pre-commit hooks:

    pre-commit install

Development Workflow

1. Open an Issue

Create a new issue on GitHub and discuss your idea with the community.

2. Create a Branch

git checkout -b your-feature-name

3. Make Changes

Make your changes, then commit (pre-commit hooks run automatically):

git add .
git commit -m "Description of your changes"
git push

4. Pre-commit Checks

Run pre-commit manually if needed:

pre-commit run              # Staged files only
pre-commit run --all-files  # All files

From the repo root you can also use:

make pre-commit

5. Create a Pull Request

Open a pull request on GitHub and follow the pull request template.

Testing

Tests are unified under pytest in the testing/ directory:

Directory Description
testing/qumat/ Qumat quantum computing library tests
testing/qdp/ Quantum Data Plane tests (GPU; auto-skipped if extension unavailable)
testing/utils/ Shared test utilities and fixtures

Run all tests:

make tests

You can also run subsets from the repo root:

Command Description
make test_rust QDP Rust unit tests via cargo-llvm-cov (requires NVIDIA GPU; skipped if none detected). HTML report: qdp/target/llvm-cov/html/index.html.
make test_python Python tests via pytest and pytest-cov (syncs dev deps; builds QDP extension if GPU present, then runs full suite). HTML report: htmlcov/index.html at repo root.

See testing/README.md for more options and details.

Project-Specific Guides

Apache Mahout includes several subprojects. Use the root workflow above for issues, branches, and pull requests; use the guides below for build, run, and test in each area.

Subproject Guide Description
Qumat (this document) Core Python library; use root Quick Start and Testing.
QDP (Quantum Data Plane) qdp/DEVELOPMENT.md GPU-accelerated pipeline: Rust/CUDA, DevContainer, build, install, benchmarks, profiling.
Website website/README.md Docusaurus site: docs source in /docs, sync, versioning, deployment.

Troubleshooting

  • Pre-commit fails: Run pre-commit run --all-files to see errors. Common fixes: cargo fmt (Rust), cargo clippy (Rust lint), and ensuring you use the repo venv (uv run pre-commit or make pre-commit).
  • Wrong Python or missing package: Ensure the virtual environment is activated and you ran uv sync --group dev from the repo root. For QDP, see qdp/DEVELOPMENT.md.

References