Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
These guidelines outline the standards for contributing to the Jazz programming language project. They define the governance model, the authority of various directories, and the workflows required for both semantic and non-semantic changes to the compiler and language specification.
The project operates under a "Spec Authority" policy where the canonical definition of the language resides in dedicated specification documents and the active compiler implementation. Contributors must adhere to workspace policies to ensure that legacy reference code remains untouched while new features are developed in the active path.
Sources: README.md:21-25, AGENTS.md:3-7
Repository Governance and Workspace Policy
The Jazz repository is divided into specific workspaces, each with a defined role in the project's lifecycle. Understanding these boundaries is critical for any contribution.
Workspace Definitions
| Directory | Status | Role |
|---|---|---|
docs/spec/ | Canonical | The normative source of truth for language behavior. |
jazz-next/ | Active | The only target for new compiler implementation work. |
jazz-hs/ | Legacy | Read-only historical reference implementation. |
jazz2/ | Legacy | Read-only experimental reference and non-normative design source. |
Sources: README.md:21-25, AGENTS.md:3-7, jazz-next/README.md:3-8
Implementation Rules
All net-new compiler behavior, including APIs, runtimes, parsers, analyzers, or codegen changes, must be implemented exclusively in jazz-next/. Contributors must not modify files in jazz-hs/ or jazz2/ unless explicitly performing legacy maintenance.
Sources: AGENTS.md:9-13, jazz-next/README.md:3-5
Change Control Workflow
The project distinguishes between changes that affect the language's semantics and those that are purely internal or non-semantic.
Semantic vs. Non-Semantic Changes
This diagram illustrates the requirement for formal decision-making before altering language behavior.
Sources: README.md:26-28, scripts/check-spec-authority.sh:22-22
- Semantic Changes: Require a formal Request for Comments (RFC) or a decision record before any implementation begins. These changes affect the language's "normative" behavior as defined in
docs/spec/. - Non-Semantic Changes: Includes internal refactoring, performance optimizations, or bug fixes that do not change intended behavior. These may be "implementation-first" but must include updated documentation and tests within the same commit or PR.
Sources: README.md:26-28, scripts/check-spec-authority.sh:22-22
Documentation and Verification Standards
Contributions are not considered complete until they pass automated policy and documentation checks. The project uses specialized scripts to enforce the authority hierarchy and documentation coverage.
Documentation Requirements
The project maintains a strict "Docs Contract." Every feature must be reflected in the status matrix and language state summaries.
- Feature Status: Must be verified against specific commits in
docs/feature-status.md. - Language State: High-level implementation details must be recorded in
docs/jazz-language-state.md. - Formatting: Markdown files are subject to
prettierenforcement to avoid tool-version drift.
Sources: scripts/check-docs.sh:21-30, README.md:18-19
Automated Policy Checks
The following automated checks are performed to ensure compliance:
| Script | Purpose |
|---|---|
check-spec-authority.sh | Verifies that no normative claims are made about legacy jazz2 paths and that authority is correctly anchored to docs/spec and jazz-next. |
check-docs.sh | Ensures required headings (e.g., "Implemented Today") and links to the feature status matrix exist in the README. |
check-clarification-specs.sh | Validates that core specifications (If-expressions, Operators, Runtime) contain required sections like "Typing Rules" or "AST Contract." |
Sources: scripts/check-spec-authority.sh:1-40, scripts/check-docs.sh:1-35, scripts/check-clarification-specs.sh:1-40
Testing Standards
New work in jazz-next/ must be accompanied by comprehensive tests. The test suite is organized by compiler phase and semantic category.
This structure ensures that every part of the active compiler path is verified.
Sources: jazz-next/README.md:27-33
Contributors should execute tests using the provided wrapper script:
# From repository root
bash jazz-next/scripts/test-warning-config.sh
Sources: jazz-next/README.md:37-41
Conclusion
Contributing to Jazz requires a disciplined approach to repository boundaries and documentation. By ensuring that all active development occurs in jazz-next/ and that all semantic changes are preceded by an RFC, the project maintains a clear distinction between its historical references and its future evolution as a functional language.