Contribution Guidelines

Thank you for your interest in contributing to Torch-Spyre! There are many ways to contribute — bug reports, documentation improvements, new operation support, and more.

For the full contribution guidelines, see the CONTRIBUTING.md file in the repository root.

Development Workflow

Torch-Spyre uses a fork-based PR model. All contributions come through a personal fork rather than pushing branches directly to the upstream repository.

1. Fork and clone

Fork the repository on GitHub, then clone your fork locally:

git clone https://github.com/<your-username>/torch-spyre.git
cd torch-spyre
git remote add upstream https://github.com/torch-spyre/torch-spyre.git

2. Keep your fork in sync

Before starting new work, sync your local main with upstream:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

3. Create a branch

Always branch off main:

git checkout -b my-feature-branch

4. Push to your fork and open a PR

Push your branch to your fork (not upstream):

git push origin my-feature-branch

Then open a PR on GitHub from <your-username>/torch-spyre:my-feature-branch targeting torch-spyre/torch-spyre:main.

5. After your PR is merged

git checkout main
git fetch upstream
git merge upstream/main
git push origin main
git branch -d my-feature-branch

Before You Start

Open an issue first for large PRs so the team can align on the approach before you invest significant effort.
Sign off your commits with git commit -s (Developer Certificate of Origin).

Code Quality Standards

Follow the Google Python Style Guide and Google C++ Style Guide.
Use import regex as re, never import re. The enforce-import-regex-instead-of-re pre-commit hook enforces this. Using the standard-library re module will fail pre-commit.
Line length is 88 characters, enforced by ruff.
Run pre-commit before submitting to make sure linting passes:
```
pip install pre-commit
pre-commit run --all-files
```
See the pre-commit docs if this is new to you. The configured hooks include ruff, clang-format, cpplint, mypy, pymarkdown, yamlfmt, and actionlint, plus local hooks for the import regex rule, DCO sign-off, filename checks, and pinned requirements/dev.txt validation.

Write tests, both unit and integration, to keep the project correct and robust. The test suite is organized into four tiers, all of which run in CI on every PR:

Tier	Where	What it covers
Upstream PyTorch compatibility	OpInfo-based tests instantiated against the `spyre` device via `instantiate_device_type_tests` (see `tests/test_spyre.py` and `tests/spyre_test_base_common.py`).	Confirms Spyre tensors behave correctly at the PyTorch API level. An allowlist tracks which test variants pass; update it with each PR.
Op-level	`tests/inductor/test_inductor_ops.py`	Each op compared against a CPU reference output.
Building blocks	`tests/inductor/test_building_blocks.py`	Composed transformer subgraphs such as attention heads, FFN, and normalization.
Model-level	`tests/models/test_model_ops.py`, `tests/models/test_model_ops_v2.py`	Full model forward passes with real Granite weights, validated against YAML-specified tolerance profiles.

Document user-facing changes. If your PR modifies how Torch-Spyre behaves from a user’s perspective, add or update the relevant page under docs/source/. See the section structure in this documentation site for guidance on where to place new content.
Dev environment setup — install development dependencies via:
```
pip install -r requirements/dev.txt
```

Building the Docs Locally

If your PR touches documentation, build and preview it locally before submitting:

pip install -r docs/requirements.txt
python -m sphinx docs/source docs/build/html -W --keep-going
python -m http.server 8080 --directory docs/build/html

Then open http://localhost:8080 in your browser.

Note: Do not open the HTML files directly from the filesystem (file://). Browsers block CSS and JavaScript when loading local files, resulting in an unstyled plain-text page. Always use the HTTP server above.

The -W flag turns Sphinx warnings into errors — the same check CI runs. Fix any warnings before opening your PR.

How to Extend the Compiler

The most common contribution is adding support for a new PyTorch operation. See the Spyre Inductor Operation Cookbook for step-by-step patterns.

Reporting Issues

Please open issues at github.com/torch-spyre/torch-spyre/issues.