Contributing

Contributing

Use Python 3.12 on Windows or Linux. Detailed methods and guidance remain in the wiki.

Submit changes through an issue-linked fd/<issue-number>_Description branch and a pull request to main. All paths are owned by @Farhad-Davaripour; their approval is required, and new commits dismiss previous approvals. Direct pushes, force pushes, and deletion of main are blocked. The repository owner retains a pull-request-only bypass, allowing them to merge their own PRs or override review requirements. GitHub does not permit authors to approve their own PRs; the owner's explicit bypass merge is the exception to the review requirement.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check src tests
python -m ruff format --check src tests

Bare pytest runs light tests. Put new tests in tests/unit/ (no tensor packages), tests/reproduction/ (NumPy/XGBoost). Tests outside these directories fail collection. --suite all requires all test dependencies.

• Reproduction: install reproduce/requirements-core.txt; run pytest --suite reproduction, then python -m sp_lense.reproduction verify and python -m sp_lense.reproduction replay.
• Paper: no additional dependencies; run python -m sp_lense.reproduction tables, audit, and paper.
• Security: install bandit pip-audit; run bandit -r src -ll and pip-audit.

Maintain reusable code in the reproduction, steering, and reporting packages under src/sp_lense/. Saved replay inputs stay in reproduce/. New modules, configs, docs and tests must be visible to Git without force-add. Keep longer guidance in the wiki.

Release archives use committed HEAD, never uncommitted files. Run python -m sp_lense.reporting.release; use --overwrite explicitly to replace an archive. Outputs must be ZIPs directly under ignored release/. The embedded manifest records the commit and content hashes. Commit generated paper changes before packaging them. ZIP byte identity is not promised.

src/sp_lense/steering/recorded_vector_fit.py preserves the original gradient-fitting source for inspection; it requires a caller-provided native model adapter. The quick start does not execute it. reproduce/layout_manifest.json records original paths, checksums, and the pre-reorganization commit. Historical development files remain available in Git history, outside the current reproducible study layout.

Protected main branch

The active ruleset permits only @Farhad-Davaripour to bypass reviews through a PR. Credentials acting as that account have the same permissions. No direct or force pushes to main are permitted.