Pantheon/CONTRIBUTING.md

Contributing to Pantheon

Thanks for your interest in Pantheon. This document covers the basics.

Licensing of contributions — read this first

Pantheon ships under AGPL-3.0 (see LICENSE).

Contributions are made under the Contributor License Agreement in CLA.md, which grants me a broad copyright and patent license, including the right to sublicense your contribution under any terms and to transfer that right along with the project.

You keep your copyright. The CLA is a license, not an assignment — nothing is transferred away from you. Your contribution stays yours to use, publish, sell, or license to anyone else, anywhere, forever.

Signing takes one commit: add your entry to .cla/signatures.md in your first pull request. Nothing to print, scan, or email. Organizations whose employees contribute on company time sign CLA-CORPORATE.md by email instead.

If you would rather not sign, open an issue describing the change instead of a pull request. An idea costs nothing to accept.

Sign your commits (DCO)

Every commit must carry a Signed-off-by line certifying the Developer Certificate of Origin — that you wrote the code, or otherwise have the right to submit it:

git commit -s -m "your message"

which appends:

Signed-off-by: Your Name <your.email@example.com>

Use your real name and a working email address — the same address as your CLA roster entry, since that is what CI matches on. If you are contributing work your employer owns, confirm you actually have the right to do so before you sign off.

Both checks run in CI on every pull request, and you can run them yourself first:

./scripts/check-dco.sh     # every commit signed off, matching its author
./scripts/check-cla.sh     # every author on the CLA roster
./scripts/check-headers.sh # every source file you ADD has SPDX + the @file block

License header on new files

Every source file starts with:

/* SPDX-License-Identifier: AGPL-3.0-or-later */
/* Copyright (C) 2026 David (Corey) Herrera */

Add it to new files you create. Do not edit the copyright line on existing files — you keep your copyright in what you contribute without needing a line in the header, and a per-file list of names becomes unmaintainable fast. git log and .cla/signatures.md are the authoritative record of who wrote what.

Getting Started

Pantheon builds on Foundry, a git submodule at ./foundry. Clone with git clone --recursive https://git.teamide.dev/David/Pantheon.git, or run git submodule update --init in an existing clone. The Makefile uses, in order, FOUNDRY=<path>, then ./foundry (the submodule or a symlink), then ../foundry (a sibling checkout).

make USE_BLAS=1 pantheon     # build the CLI
make USE_BLAS=1 test         # build + run the test suites
make DEBUG=1 USE_BLAS=1 pantheon
make clean

Flag	What	When
USE_BLAS=1	SGEMV/SGEMM via Accelerate or OpenBLAS	always
USE_THREADS=1	pthread pool for parallel ops	multi-core inference
USE_METAL=1	Metal GPU compute	macOS / Apple Silicon
USE_CUDA=1	CUDA via dlopen (cuBLAS + embedded PTX)	Linux + NVIDIA

Code Style

• C11 (-std=c11); no dependencies beyond Foundry, libc, libm, pthreads and libdl (BLAS and accelerator frameworks are opt-in build flags)
• pn_ prefix on all Pantheon symbols
• Errors: return NULL or an error code — no exit() in library code
• Opaque types in the public API (include/pantheon.h); concrete structs stay internal
• Callers free returned objects via pn_free()
• snprintf, never sprintf
• No warnings under -Wall -Wextra

Broader conventions live in coding-best-practices.md.

Testing

Tests use Foundry's lib/test.h framework and live in tests/. Add a matching target in the Makefile.

If you change a forward pass or a kernel, show numerical parity. The bar is argmax-exact against the reference path (CPU, or an existing oracle) on a real model — not "it produces plausible text." Include how you measured it in the PR.

Pull Requests

Code is reviewed against docs/coding-best-practices.md, cited by rule number. This section covers the PR itself.

One logical change per PR.

Size. Reviewable lines = added + deleted, excluding generated files, pure renames, and vendored imports.

Reviewable lines
≤ 400	normal
400–1,000	expect a request to split
> 1,000, or > 15 files	state in one line why it can't be split

Exempt from the size limits — but must be alone in their own PR:

1. Generated sources. State the regeneration command, toolchain version, and target arch. Reviewed by rebuilding, not by reading.
2. Pure moves and renames. No content change in the same commit.
3. Mechanical sweeps. Include the command that reproduces the diff.
4. Vendored or backend imports.

Evidence.

• Performance claim — the command, the device, before/after in tok/s, and the noise floor. A multiplier on its own is not a result.
• Forward pass or kernel — parity against the reference path, argmax-exact or ulp-0, naming the model and quantization.
• A test you call green — show it can go red (rule 8). Delete the .o and the test binary first, or you may be running the old one.
• Untested — say so plainly rather than leaving it implied.

Keep it short. Title is scope: imperative summary, lowercase scope, ≤72 characters. The body says what changed and why in a few lines. Commit messages the same: a subject line, and a body only when the reason isn't visible in the diff. Long rationale belongs in a spec file, not a commit message. No tool, assistant, or generator attribution anywhere — title, body, or comments.

Review comments carry a severity prefix:

• blocker: — must change before merge
• question: — answer before merge
• nit: — optional, never blocks

Unprefixed reads as nit:. The author does not resolve a blocker: thread — the reviewer does. Approval goes stale when new commits land, unless they are a rebase or a fixup.

Merge bar: builds clean with zero warnings, tests pass, DCO and CLA checks green, and the code meets the practices doc.

Reporting Bugs

Open an issue with:

• what you expected, and what actually happened
• minimal reproduction steps
• the model and quantization involved (many bugs are format-specific)
• your platform, compiler version, and GPU + driver if relevant

Bugs that only appear at a particular context depth, batch size, or concurrency level are common here — please say which, since it is usually the whole clue.