miroir/CONTRIBUTING.md

Contributing to Miroir

Thank you for your interest in contributing to Miroir! This document covers the development workflow, code submission guidelines, and local testing instructions.

Development Workflow

Prerequisites

• Rust 1.87 or later (see rust-toolchain.toml)
• Docker and Docker Compose for local integration testing
• make for convenience targets
• clang and musl-tools for static binary builds

Getting Started

1. Clone the repository:

git clone https://github.com/jedarden/miroir.git
cd miroir

2. Install Rust toolchain:

rustup show
# If Rust is not installed, follow https://rustup.rs/

3. Build the project:

cargo build --all

4. Run tests:

cargo test --all

5. Start the development stack:

docker compose -f examples/docker-compose-dev.yml up -d

Project Structure

miroir/
├── crates/
│   ├── miroir-core/          # Core library (routing, merging, topology)
│   ├── miroir-proxy/          # HTTP proxy binary
│   └── miroir-ctl/            # Management CLI binary
├── tests/                     # Integration and chaos tests
├── benches/                   # Performance benchmarks
├── examples/                  # Docker Compose configs and SDK tests
├── charts/miroir/             # Helm chart
├── docs/                      # Documentation
└── k8s/                       # ArgoCD and Argo Workflow templates

Development Commands

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features -- -D warnings

# Run all tests
cargo test --all

# Run integration tests (requires dev stack running)
cargo test -p miroir-proxy --test docker_compose_integration -- --test-threads=1

# Run benchmarks
cargo bench

# Build static binaries
make build-static

Code Submission Guidelines

Pull Request Process

1. Fork the repository and create a branch for your work:

git checkout -b feature/your-feature-name

2. Make your changes following the coding standards below.

3. Ensure all checks pass:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all

4. Commit your changes with a clear message:

feat(scope): brief description

Detailed explanation of the change and why it was made.

Closes: #gh-issue-number

5. Push to your fork and create a pull request:

git push origin feature/your-feature-name

Coding Standards

• Follow Rust style guidelines enforced by cargo fmt
• No unwrap() or expect() in production code — all fallible operations must return Result<T>
• Add unit tests for new functionality in #[cfg(test)] modules
• Document public APIs with rustdoc comments
• Keep functions focused — single responsibility, clear names
• Error messages should be actionable and include context

Commit Message Conventions

Use conventional commit prefixes:

• feat: — new feature
• fix: — bug fix
• docs: — documentation changes
• test: — adding or updating tests
• refactor: — code refactoring (no behavior change)
• perf: — performance improvement
• ci: — CI/CD changes
• chore: — maintenance tasks

Local Testing

Unit Tests

Run unit tests for all crates:

cargo test --all

Run tests for a specific crate:

cargo test -p miroir-core
cargo test -p miroir-proxy

Integration Tests

Start the development stack first:

docker compose -f examples/docker-compose-dev.yml up -d

Run integration tests:

cargo test -p miroir-proxy --test docker_compose_integration -- --test-threads=1

Clean up after testing:

docker compose -f examples/docker-compose-dev.yml down -v

Chaos Tests

Chaos tests simulate node failures and network partitions:

# Ensure dev stack is running
docker compose -f examples/docker-compose-dev.yml up -d

# Run chaos tests
./tests/chaos/p4_topology_chaos.sh

# Clean up
docker compose -f examples/docker-compose-dev.yml down -v

SDK Compatibility Tests

Test SDK compatibility with Python, TypeScript, and Go:

cd examples/sdk-tests
./run_all_sdk_tests.sh

CI/CD Pipeline

Miroir uses Argo Workflows for CI/CD (GitHub Actions are disabled). See k8s/argo-workflows/miroir-ci.yaml for the full pipeline.

Pipeline Stages

1. Checkout — Clone repository
2. Lint — cargo fmt and cargo clippy
3. Test — cargo test --all --all-features
4. Build — Static musl binaries for miroir-proxy and miroir-ctl
5. Docker build — Push to ghcr.io/jedarden/miroir (tag-gated)
6. GitHub Release — Create release with binaries (tag-gated)

Manual CI Trigger

Trigger a CI run manually:

kubectl --kubeconfig=/home/coding/.kube/iad-ci.kubeconfig create -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
  generateName: miroir-ci-manual-
  namespace: argo-workflows
spec:
  workflowTemplateRef:
    name: miroir-ci
  arguments:
    parameters:
    - name: revision
      value: main
EOF

Release Process

See the Release Checklist in the runbooks for the complete release process.

Documentation

Plan Documentation

The authoritative design document is docs/plan/plan.md. All architectural decisions should reference specific sections of this document.

Code Documentation

Public APIs must be documented with rustdoc:

/// Assigns a shard to `rf` nodes within a single replica group.
///
/// # Arguments
///
/// * `shard_id` - The shard identifier to assign
/// * `group_nodes` - Nodes belonging to the target replica group
/// * `rf` - Replication factor (number of nodes to select)
///
/// # Returns
///
/// A vector of node IDs selected for this shard, sorted by score descending.
///
/// # Example
///
/// ```no_run
/// use miroir_core::router::assign_shard_in_group;
/// let nodes = vec!["node-0".to_string(), "node-1".to_string()];
/// let assigned = assign_shard_in_group(0, &nodes, 1);
/// assert_eq!(assigned, vec!["node-0".to_string()]);
/// ```
pub fn assign_shard_in_group(shard_id: u32, group_nodes: &[NodeId], rf: usize) -> Vec<NodeId> {
    // ...
}

User Documentation

User-facing documentation lives in:

• docs/onboarding/ — Production deployment guides
• docs/troubleshooting/ — Common issues and diagnostics
• docs/runbooks/ — Operational procedures
• docs/ctl/ — miroir-ctl command documentation
• examples/README.md — Quick start and local development

Getting Help

• Documentation: Start with README.md and docs/plan/plan.md
• Issues: Search GitHub Issues before creating a new one
• Discussions: Use GitHub Discussions for questions and design conversations
• Troubleshooting: See docs/troubleshooting.md for common issues

License

By contributing to Miroir, you agree that your contributions will be licensed under the MIT License.