Claro/CONTRIBUTING.md

Contributing to Claro

Claro is a learning tool first. Read 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 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:

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:

./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 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.