Docker-based Development Parity
Relevant source files
The following files were used as context for generating this wiki page:
Docker-based Development Parity in the Sploosh project ensures that local development environments, particularly on Windows, match the Ubuntu-based environment used in GitHub Actions CI. This parity is critical for avoiding platform-specific issues such as Windows Cargo lock or cache quirks that might lead to inconsistent build or test results between a developer's machine and the project's automated pipelines.
The primary mechanism for achieving this parity is a PowerShell-based utility script that orchestrates a Docker container to run the standard Rust validation suite (formatting, linting, and testing) within a Linux context. This approach provides a "Windows-stable path" for compiler bootstrap work, ensuring that all Pull Requests (PRs) have been validated against the same environment that will eventually execute the CI workflows.
Sources: AGENTS.md:16-20, CONTRIBUTING.md:46-50, crates/AGENTS.md:63-65
Validation Workflow and Orchestration
The project utilizes a specific orchestration script, scripts/docker-check.ps1, to bridge the gap between local development and the containerized CI environment. The script automates the process of building a development image and executing the standard workspace checks.
The Docker Check Process
The following sequence diagram illustrates how the docker-check.ps1 script manages the lifecycle of the validation environment.
The diagram shows the transition from local host environment to the containerized Rust toolchain execution.
Sources: scripts/docker-check.ps1:1-38, crates/AGENTS.md:63-75
System Components
Achieving parity involves several key components across the repository, ranging from scripts to documentation guidelines for contributors and AI agents.
Key Components for Parity
| Component | Path | Description |
|---|---|---|
| Orchestration Script | scripts/docker-check.ps1 | PowerShell script that builds the image and runs validation commands inside a container. |
| Development Image | sploosh-dev | The default Docker image tag used for local Linux-based validation. |
| Validation Commands | $check variable | A chained command string: cargo fmt, cargo clippy, and cargo test. |
| Volume Mapping | -v "${workspace}:/workspace" | Ensures local code changes are reflected and tested inside the Ubuntu container. |
| CI Parity Guidelines | AGENTS.md / CONTRIBUTING.md | Mandates the use of Docker for PR validation to match GitHub Actions. |
Sources: scripts/docker-check.ps1:12-30, AGENTS.md:20-25, CONTRIBUTING.md:46-50
Script Configuration and Parameters
The docker-check.ps1 script accepts specific parameters to control the build and execution flow:
- -Image: Specifies the Docker image name (defaults to
sploosh-dev). - -Build: A switch that triggers a
docker build --pullcommand to refresh the development environment before running checks. - CARGO_INCREMENTAL: Set to
0within the container to ensure clean, non-incremental builds for maximum reliability.
Sources: scripts/docker-check.ps1:1-25
Role in the Development Lifecycle
Docker-based parity is integrated into the "Definition of Done" for all contributions. Before a Pull Request is considered ready for review, it must pass these checks to ensure consistency across the dual-target (Native, WASM, EVM, SVM) nature of the Sploosh language.
Integration with CI/CD
The local Docker check mirrors the rust.yml GitHub Actions workflow. This prevents common failure scenarios where code passes on a Windows machine but fails in the Linux-based CI runner due to file path differences, line endings, or compiler behavior variations between OS targets.
This flowchart illustrates how the Docker check serves as a pre-flight layer that replicates the CI environment on the developer's machine.
Sources: AGENTS.md:20-30, CONTRIBUTING.md:65-72, README.md:9-15
Conclusion
Docker-based development parity is a cornerstone of the Sploosh project's stability strategy. By providing a unified validation path through scripts/docker-check.ps1, the project mitigates environment-induced bugs and ensures that the compiler bootstrap remains consistent across diverse contributor environments. This technical architecture is mandatory for all material changes to the language specification and compiler crates.
Sources: AGENTS.md:20, crates/AGENTS.md:63-65