Skip to content

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 21+, 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:

    bash
    ./scripts/verify.sh

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

    powershell
    py -3 scripts/verify.py

    python3 scripts/verify.py is equivalent on Linux/macOS. This builds the compiler, runs all compiler/JVM regressions (in parallel) and the independent grammar harness, executes documentation snippets, builds/checks the website, and runs VS Code tokenization/CLI/package checks. While iterating, run python3 scripts/test-affected.py instead, which selects the gates your change touches (see "Focused checks" below). 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):

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

While iterating, run the gates your change affects:

bash
python3 scripts/test-affected.py          # --list shows the selection without running

It diffs against the merge base with origin/main (plus staged, unstaged and untracked files), maps the paths to gates through tests/test-map.json, always adds a smoke set (the build and a handful of goldens), and runs the selection through the same parallel runner as the full gate. A path no rule covers, or a change to the runner or the map, runs everything. The subsystem commands in AGENTS.md remain the way to run one suite by hand.

Before opening or updating a PR, run the full gate, which is parallel:

bash
python3 scripts/test.py                   # --jobs N; default CPU count capped at 8

--jobs 1 keeps the sequential order for debugging; SPRIG_TEST_JOBS changes the default. Gates that share state (Gradle's cache, the SDK archive under dist/, the tracked lock files, the acceptance results directory) are marked serial in the map, with the reason, and run alone after the parallel group. A failure that appears only in parallel is a bug in the test (shared state, a port collision): fix its cause, never add a retry. CI keeps running the full gate on every required check; nothing about required CI changes.

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 × JDK21/26 hosted matrix; the Windows preview job runs the same gates separately and is not a required check. 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:

bash
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 ​

LocationPurpose
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, resolved review conversations and Linux/macOS × JDK21/26 plus Documentation site checks; a branch does not need to be up to date with main before it merges. 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.

Sprig is licensed under Apache-2.0 · v0.7.1-beta.1 published as a prerelease