Contributing Guide & Code of Conduct
Relevant source files
The following files were used as context for generating this wiki page:
Sploosh is a spec-first, AI-native programming language project where the documentation serves as the authoritative definition of the language. The contributing process is strictly governed by the "Spec-first rule," ensuring that any behavioral change in the compiler is preceded or accompanied by a corresponding update to the language specification. This process ensures that Large Language Models (LLMs) can generate accurate code by relying on a stable and concise set of rules.
The project fosters a professional and inclusive environment through its Code of Conduct, which applies to all community spaces and official representations of the project. Contributions are expected to follow specific technical standards, including strict token budgets for prompt-sized spec mirrors to maintain LLM portability.
Sources: CONTRIBUTING.md:3-7, VISION.md:4-9, AGENTS.md:38-40
Contribution Workflow
The Sploosh development process revolves around a "Spec-first" philosophy. No behavioral changes are permitted without an accompanying update to the LANGUAGE_SPEC.md.
The Spec-First Rule
When the compiler implementation and the specification disagree, the compiler is considered bugged unless a spec amendment is merged first. This ensures the documentation remains the single source of truth for both human developers and AI agents.
Sources: CONTRIBUTING.md:3-7, AGENTS.md:38-40
Git and Branching Strategy
The project enforces strict Git rules to maintain a clean and verifiable history:
- Main Branch Protection: Direct commits to
mainare prohibited and branch-protected. - Branch Naming: Branches must use specific prefixes:
spec/,docs/,feature/, orfix/. - Commit Requirements: Commits must have short descriptive titles and explain the why in the body. AI-generated footers (e.g.,
Co-Authored-By,Claude-Session) are strictly forbidden. - Rebase Workflow: Branches must be kept up to date with
mainvia rebasing; merge commits frommaininto topic branches are disallowed.
Sources: CONTRIBUTING.md:47-56, AGENTS.md:27-36
Pull Request (PR) Lifecycle
The following flowchart illustrates the mandatory steps for a successful PR submission.
The diagram shows the sequential dependency between specification updates and code implementation.
Sources: CONTRIBUTING.md:60-70, AGENTS.md:42-53
Technical Requirements and CI
Contributions must pass a suite of automated checks, including Rust toolchain validation and specific token budget enforcement for AI context windows.
Development Environment
Contributors are required to use stable Rust 1.91+. For Windows users, the project recommends using a specific Docker-based check to ensure parity with the GitHub Actions environment.
| Command | Purpose |
|---|---|
cargo fmt --all -- --check | Validates code formatting |
cargo clippy --workspace | Runs linting and static analysis |
cargo test --workspace | Executes the test suite |
.\scripts\docker-check.ps1 -Build | Parity check for Windows users |
Sources: CONTRIBUTING.md:38-45, AGENTS.md:14-20
Prompt Budget Enforcement
A unique requirement for Sploosh is the enforcement of token limits on spec mirrors to ensure they remain "prompt-loadable" for LLMs. The scripts/check_prompt_budget.py script uses the cl100k_base encoding to validate these limits.
| Mirror Target | Token Ceiling | Purpose |
|---|---|---|
LANGUAGE_SPEC_PROMPT_CORE.md | 5,600 tokens | Core language rules for LLM system prompts |
LANGUAGE_SPEC_PROMPT_WEB3.md | 1,500 tokens | On-chain/Web3 specific extensions |
Sources: CONTRIBUTING.md:79-82, scripts/check_prompt_budget.py:27-31, VISION.md:45-48
Code of Conduct
The Sploosh community adheres to the Contributor Covenant to ensure a harassment-free experience for all participants.
Standards of Behavior
- Positive: Demonstrate empathy, accept constructive feedback, and focus on community benefit.
- Negative: Sexualized language/imagery, trolling, personal or political attacks, and publishing private information.
Sources: CODE_OF_CONDUCT.md:12-28
Enforcement Responsibilities and Procedures
Community leaders have the authority to remove or reject contributions not aligned with these standards. Moderation follows a structured escalation path:
The escalation ladder is inspired by Mozilla's enforcement guidelines.
Sources: CODE_OF_CONDUCT.md:52-85
Security Policy
Security vulnerabilities should not be reported via public issues.
Reporting Process
- Contact: Email
revenantpulse@gmail.comwith the subject prefix[SECURITY]. - Disclosure: The team commits to an acknowledgment within 72 hours and initial triage within 7 days.
- Scopes: Reports should cover compiler crates, design-level spec unsoundness, and on-chain design flaws (e.g., reentrancy guards, storage layouts).
Sources: SECURITY.md:36-54, SECURITY.md:63-65
Definition of Done (DoD)
A contribution is considered complete only when it meets the following checklist:
-
LANGUAGE_SPEC.mdupdated if behavior changed. - All prompt-sized mirrors (
CORE,WEB3) are synced and within budget. - Appendix D changelog entry added for material spec changes.
- CI is green (fmt, clippy, tests, and prompt-budget).
- PR template fields (Summary, Spec Sections, Test Plan) are fully populated.
- Branch is rebased against
main.
Sources: CONTRIBUTING.md:60-72, AGENTS.md:66-74
The contributing and conduct guidelines ensure that Sploosh remains a high-integrity, safety-first language project suitable for both human-driven and agent-driven development. By maintaining a spec-first approach and strict technical constraints, the project ensures long-term portability and correctness across native and web3 targets.