Contributing & Development Guidelines

We welcome contributions from researchers, ML systems engineers, and open-source developers. To maintain reproducibility, all contributions must satisfy strict verification standards.

1. Non-Negotiable Scientific Principles

Zero Fabricated Metrics: Never submit synthetic benchmarks, simulated energy labeled as measured, or unverified hardware speedups.
Strict Checkpoint Loading: Never introduce strict=False bypasses or silent fallbacks to random weights.
Canonical Project Name: Maintain the canonical name Q-TensorFormer. Do not introduce versioned forks (e.g. v2, v3).

2. Development Environment Setup

Fork the repository, clone locally, and create a clean Python virtual environment:

git clone https://huggingface.co/Premchan369/Q-TensorFormer
cd Q-TensorFormer
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Required Pre-Commit Verification Gate

Before submitting any Pull Request, you must verify that all automated checks pass locally:

# 1. Run full unit test suite (must report 0 failures)
pytest -v

# 2. Run deterministic smoke test
python scripts/smoke_test.py

# 3. Run scientific integrity auditor
python scripts/scientific_integrity_checker.py

4. Code Style & Engineering Standards

Python Version: Tested on Python 3.10 and 3.11. Avoid deprecated language features.
Docstrings & Comments: Preserve documentation integrity. Explain non-obvious mathematical rationale.
Tensor Operations: Ensure numerical stability. Avoid bare divisions and use masked_fill rather than mask * float("-inf").

5. How to Submit a Pull Request

Create a descriptive topic branch (e.g. git checkout -b feat/triton-fused-kernel).
Commit atomic, well-documented changes.
Push to your fork and open a Pull Request against main on the Hugging Face repository.