Contributing to Sprig

Want to contribute with Codex / Claude / ChatGPT? You can help build a programming language without being a compiler expert. Pick an agent-friendly issue, give your coding agent the issue and AGENTS.md, then review its patch. AI-assisted contributions are welcome. The submitter remains responsible for understanding the change, tests, licensing and correctness.

First contribution

1. Install JDK 17+, Python 3.12+, Node.js 20+ / npm, and Git.

2. Fork and clone the repository; create a focused branch.

3. Pick a scoped issue. good first issue means small and reviewed; agent-friendly means it has a mechanically testable contract.

4. Read the issue, AGENTS.md, and the nearest passing fixture. Ask the compiler about capabilities and APIs before guessing language behavior.

5. Make the patch and run the canonical contributor gate from the repository root:

   ./scripts/verify.sh

   On Windows (PowerShell or Command Prompt; no Bash required):

   py -3 scripts/verify.py

   python3 scripts/verify.py is equivalent on Linux/macOS. This builds the compiler, runs all compiler/JVM regressions and the independent grammar harness, executes documentation snippets, builds/checks the website, and runs VS Code tokenization/CLI/package checks. First use downloads pinned build libraries and npm dependencies.

6. Review the diff yourself. Keep regression evidence, remove unrelated edits, and explain which commands actually passed.

7. Open a PR using the template and disclose material AI assistance.

Query → check → repair

After the build, use bin/sprig (bin\sprig.cmd on Windows):

./bin/sprig capabilities --json
./bin/sprig help generics --json
./bin/sprig api java.time.LocalDate --json
./bin/sprig check --json path/to/example.spr
./bin/sprig explain SPR-TYPE-NULLABLE --json

Grammar and compiler implementation are authoritative for current behavior. docs/language/feature-status.md records implementation status; docs/history/design-kit/ preserves retired target semantics and may differ. Report disagreements with a reproducer. Do not improvise a language feature.

Focused checks and release checks

During an edit, use the subsystem commands in AGENTS.md; before opening a PR, run verify. For editor changes, also run npm run test:host in editors/vscode/; see its README for isolated real-host testing. State separately whether evidence is parser acceptance, static checking, generated Java compilation, or JVM runtime behavior. Never change a golden output or weaken an assertion merely to remove a failure.

Release validation additionally packages the SDK, verifies checksums/legal notices, extracts and exercises each showcase from the archive, and runs the Linux/macOS × JDK17/26 hosted matrix; Windows preview runs separately and is non-blocking. Maintainers record those results in the milestone validation record. A local contributor gate does not establish release or platform validation.

Generated lockfiles

Tracked sprig.lock files are generated artifacts. Never hand-merge or hand-edit a lock conflict; which side Git shows as ours or theirs does not matter. Take either complete side for the lockfile, then regenerate:

git checkout --ours -- path/to/sprig.lock   # or --theirs; either is temporary
python3 scripts/refresh-locks.py
git add path/to/sprig.lock

scripts/refresh-locks.py rewrites every Git-tracked lock with sprig resolve --offline (never online) and fails clearly if the launcher or the local cache is missing. The regenerated sprig resolve output is the only authority.

Where code examples live

Location	Purpose
website/snippets/	Teaches Sprig: executable documentation. Every .spr file has an explicit role in website/snippets/snippets.json: executable compares runtime output, import-only performs static checking, and compile-fail checks the stable diagnostic codes in a sibling .expect.json.
examples/	Programs or projects with an independent user-facing purpose.
tests/	Proves Sprig behavior: regression fixtures, goldens and harnesses.

Syntax demonstrations and tutorial programs belong under website/snippets/ and must be executable documentation. examples/ is reserved for programs or projects with an independent user-facing purpose; regression fixtures belong under tests/. Deleting an executable snippet's .out oracle fails the documentation gate instead of silently downgrading it to a static check.

Scope and review

• docs, tests-only, tooling, stdlib, and compiler describe the area.
• design-required means syntax, type/effect/numeric/nullability/generic semantics need an explicit design decision before implementation. A motivating program belongs in a design issue; an unrelated PR must not add syntax.
• Fix correctness with a regression test and preserve existing oracles.
• Treat docs/history/ as historical evidence, not current specification.
• Edit root reference docs; website/generated/ contains generated copies.
• Do not commit build/, bin/, downloaded JARs, node_modules/, caches, generated site output, personal paths, credentials or private trial logs.
• Justify new dependencies and update LICENSE, NOTICE and THIRD_PARTY_NOTICES.md for third-party material. Contributions use Apache-2.0.

See docs/contributing/ai-disclosure.md for review responsibilities and docs/contributing/trial.md for the concise contributor evaluation protocol. Neither a model's confidence nor passing compilation replaces review of user-visible behavior.

Protected main

Main requires a PR, an up-to-date branch, resolved review conversations and Linux/macOS × JDK17/26 plus Documentation site checks. Rules also apply to administrators; force pushes and deletion are disabled. Required approval count is currently zero for this small maintainer team; this does not replace patch review or the submitter's AI-disclosure responsibility. Windows preview is not a required status check. Submit semantic changes for design review explicitly.