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
```bash
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):
```bash
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.