# Contributing to Claro

Claro is a learning tool first. Read [`docs/LEARNING_FIRST.md`](docs/LEARNING_FIRST.md)
before proposing learner-facing changes. Keep each change small and predictable,
teach one recommended syntax per concept, preserve supported compatibility
syntax, and prioritize runnable examples and plain-language diagnostics over
feature breadth. Do not claim accessibility validation without testing with
intended learners.

For behavior changes, add a focused regression before implementation and verify
that it fails for the intended reason. Then build and run the affected examples
and the repository validation gates. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for
how the current charter relates to older planning documents.

## Repository layout

- `src/claro.c` — C89 interpreter.
- `lessons/` — ordered beginner lessons.
- `examples/` — programs to try and change.
- `docs/` — learning guides, reference, and historical notes.
- `tests/` — regression fixtures and expected output.
- `tools/` — validation and release helpers.
- `lib/` — existing library helpers.
- `support/` — optional editor support.

## Build and verify

At the beginning of a development/release run, stamp its UTC version once:

```bash
python3 tools/stamp_version.py
make -s all
```

Ordinary rebuilds use `make -s all` without changing the run timestamp.
Validation helpers also require Python 3. Run:

```bash
./claro test
./claro doctor
./claro validate
python3 tools/validate_v1_17.py
```

The last command is the current full validation entry point; its filename is
historical. Use focused sanitizer checks for relevant C runtime changes and
report known failures explicitly.

Execute teaching examples with suitable input and assert their expected output;
syntax checking alone is not enough. Update the relevant guide, rerun checks
after the final edit, and finish with `git diff --check`. Preserve unrelated
local work; exclude generated binaries, caches, and unverified experiments
from commits. See [versioning](docs/VERSIONING.md) for the timestamp convention.


The runtime must remain a single C89 implementation file. The full gate runs
`python3 tools/validate_c89.py` to compile it independently with strict C89 flags
and test formatting, numeric boundaries, and simple functions. Do not introduce
C99 syntax or depend on generated project headers. See [C89 notes](docs/C89.md).