CONTRIBUTING.md

Contributing to mini_transformer

Thanks for your interest in contributing! The project mirrors the published package, so keeping the repo healthy benefits everyone who installs mini-transformer.

1. Environment

make create-env        # creates/updates the conda env and installs extras
# or, if you prefer pip/venv:
python -m pip install -e .[dev,notebook,viz]
pre-commit install      # optional but recommended

2. Quality Checklist

Run these commands before opening a pull request (they are quick and automated):

make fmt            # ruff format + black
make lint-check     # ruff lint (no auto-fix)
make type           # mypy
make test           # pytest (currently 130+ unit tests)
pre-commit run --all-files

• Notebook edits: clear execution outputs or re-run cells so they execute top-to-bottom.
• If you touch attention introspection or training, add/extend tests under tests/units/.

3. Working Style

• Prefer existing helper utilities (mini_transformer.utils.*, model_loader, etc.) instead of re-implementing logic.
• Keep imports sorted/compact; ruff handles this automatically.
• Default to strict type hints. If you need Any, document why in a short comment.
• For new configuration values, update both the dataclass in mini_transformer/configs.py and the YAML in configs/.

4. Documentation

• Update README.md, relevant notebooks, or in-repo docs when behaviour or flags change.
• Add docstrings for new public APIs and CLI options.

5. Pull Requests

• Describe the motivation, summarize the change, and list the verification steps you ran.
• Link any related issues or design discussions.
• Large or speculative changes? Please open an issue or discussion first so we can align on direction.

Thanks again for helping keep mini-transformer robust! Feel free to open issues for questions, proposals, or clarifications.