# Development and Testing
## Prerequisites
- Rust 1.85+ (install via [rustup](https://rustup.rs/))
- [just](https://github.com/casey/just) (recommended task runner - install via `cargo
install just`)
- Python 3.11+ (optional, for cross-validation)
## Quick Start Development Workflow
We use [just](https://just.systems/) as the task runner.
Install it with `cargo install just`.
This command auto-fixes all formatting (Rust code + docs), fixes clippy warnings, and
verifies all CI checks pass locally.
**Common workflows:**
```bash
# IMPORTANT: REQUIRED before every commit: auto-fix everything and verify
just precommit
# Run all CI checks locally (same as GitHub CI)
just check
# Auto-fix all formatting and clippy warnings
just fix
# Build release binary
just build
```
## Available Just Commands
**Auto-fix commands** (modify code):
```bash
just format # Auto-format everything (Rust code + docs)
just format-rust # Auto-format Rust code only
just format-docs # Auto-format documentation with flowmark
just lint-fix # Auto-fix clippy warnings where possible
just fix # Auto-fix everything (Rust + docs + clippy)
just precommit # Auto-fix everything then verify all checks pass
```
**Check commands** (verify only, no changes):
```bash
just check # Run all CI checks (format-check + lint + test)
just format-check # Verify formatting (CI check)
just lint # Run clippy with -D warnings (CI check)
just test # Run all tests
just test-no-default # Run tests without default features
```
**Build commands:**
```bash
just build # Build release binary
just clean # Clean build artifacts
```
## Using Cargo Directly
If you prefer not to use `just`, you can run commands directly:
```bash
# Auto-fix formatting and linting
cargo fmt --all
cargo clippy --fix --all-targets --all-features --workspace --allow-dirty --allow-staged
# Check formatting, linting, and tests (same as CI)
cargo fmt --all -- --check
cargo clippy --all-targets --all-features --workspace -- -D warnings
cargo test --all-features --workspace
# Build
cargo build --release
```
## Cross-Validation with Python Flowmark
Compare outputs with the Python implementation:
```bash
# Install Python flowmark
pip install -e python-repo
# Run cross-validation
./scripts/cross-validate.sh
```
This ensures byte-for-byte identical output across all formatting modes.
## CI/CD
This project uses modern GitHub Actions workflows with comprehensive checks:
### CI Workflow
Runs on every push and pull request.
View at [.github/workflows/ci.yml](.github/workflows/ci.yml).
**Quality checks:**
- **Format Check**: Verifies code formatting with `cargo fmt --check`
- **Clippy Lints**: Runs clippy with `-D warnings` (all warnings treated as errors)
- **Tests**: Cross-platform testing (Ubuntu, macOS, Windows)
- **MSRV Check**: Ensures compatibility with Rust 1.85+
- **Documentation**: Builds docs with `-D warnings`
**Security and dependencies:**
- **Security Audit**: Runs `cargo-audit` to check for known vulnerabilities
- **Dependency Check**: Uses `cargo-deny` for license and dependency validation
**Important:** CI only checks code - it does not auto-fix issues.
Always run `just precommit` locally before committing to auto-fix all formatting (Rust
code + docs) and clippy warnings.
### Release Workflow
Triggered by version tags (e.g., `v0.1.0`). View at
[.github/workflows/release.yml](.github/workflows/release.yml).
**Cross-platform builds:**
- Linux x86_64 (glibc)
- Linux x86_64 (musl/static)
- Linux ARM64
- macOS Intel (x86_64)
- macOS Apple Silicon (ARM64)
- Windows x86_64
**Automated release process:**
- Builds optimized binaries for all platforms
- Creates GitHub Release with binaries as artifacts
- Optional: publishes to crates.io (when configured)
## Release Process
Releases are automated using [cargo-release](https://github.com/crate-ci/cargo-release).
### Prerequisites
Install cargo-release (one-time setup):
```bash
cargo install cargo-release
```
### Creating a Release
Use the justfile command:
```bash
just release patch # 0.1.0 → 0.1.1
just release minor # 0.1.0 → 0.2.0
just release major # 0.1.0 → 1.0.0
```
This automatically:
1. Runs all tests and checks (`just check`)
2. Updates version in all Cargo.toml files
3. Creates a git commit with message “Bump version to X.Y.Z”
4. Creates and pushes a git tag (e.g., `v0.2.0`)
5. Pushes to remote repository
### What Happens Next
The GitHub Actions release workflow automatically:
- Creates a GitHub release
- Builds binaries for all platforms (Linux x86_64/ARM64, macOS x86_64/ARM64, Windows
x86_64)
- Uploads release assets
- Publishes to crates.io (requires `CARGO_REGISTRY_TOKEN` secret)
The workflow verifies that the git tag version matches the Cargo.toml version before
publishing.
### Configuration
Release behavior is configured in `release.toml`:
- Tag format: `v{{version}}` (e.g., v0.1.0)
- Pre-release checks: Runs `just check` before creating release
- Package: Single package `flowmark` with both library and binary
- Publishing: Disabled for local releases (handled by GitHub Actions)
### Cross-Validation Workflow
Ensures byte-for-byte parity with Python Flowmark.
View at
[.github/workflows/cross-validation.yml](.github/workflows/cross-validation.yml).
See [docs/project/ci-cd-publishing-plan.md](docs/project/ci-cd-publishing-plan.md) for
complete documentation.