Contributing to Nomos

Prerequisites

• JDK 11+ — the build targets Java 8 bytecode via --release 8. CI verifies the build on Java 11 and Java 17.
• Maven 3.9+
• Scala 2.12.21 — managed by the build; no separate install needed.

Build & test

# build, test, verify, and install all reactor modules
mvn clean install -Dgpg.skip=true

# rebuild the example end-to-end against the locally installed artifacts
mvn -f nomos-example/pom.xml clean test

Coverage

Statement coverage for nomos-runtime and nomos-core runs via scoverage:

mvn -pl nomos-runtime,nomos-core scoverage:report scoverage:check
# HTML reports: nomos-runtime/target/site/scoverage/index.html
#               nomos-core/target/site/scoverage/index.html

CI enforces a 97% runtime floor and an 80% core floor.

Test-driven workflow

Changes are developed test-first: add a failing spec under nomos-core/src/test/scala/dev/cjfravel/nomos/, implement until it passes, then prove anything user-visible end-to-end in nomos-example. A feature that changes generated code should have both a content test (what's emitted) and an example test (that it compiles and runs).

Docs & release

User docs live under docs/ and are the source for the project site. The site itself is built, never checked in: dev/scripts/build-site.sh [out] copies the pages, replaces every {{NOMOS_VERSION}} placeholder with the reactor version, and generates the core and runtime Scaladoc into api/ and runtime-api/. The Pages workflow publishes that output on every push to main, and CI builds it on every pull request — so a version bump or an API change never needs a regenerated file in the diff. Two build-time gates keep the hand-written pages honest: dev/scripts/readme-has-version.sh fails the build unless the README, changelog, and every consumer POM reference the current version (and the templated pages still carry the placeholder), and dev/scripts/docs-no-stale-refs.sh fails it if any doc or comment names a third-party JSON library or a removed symbol.

A published GitHub Release runs the protected Maven Central workflow, which builds, signs, publishes, waits for Central resolution, and tests a clean consumer. See the release runbook.

Code style

• Wrap if/else branch bodies in braces.
• Comments describe present behavior — not history, removed code, or session notes.
• Prefer order-preserving ListMap where field/variant order matters.

Pull requests

• Keep changes focused; update the relevant docs page when behavior changes.
• Ensure mvn -pl nomos-core test and the example build are green.
• Describe the user-visible effect of the change.

See Architecture for how the modules and the generation pipeline fit together.