Development workflow

Branches

main is the only long-lived branch. Releases are tagged on main (0.7.0, 0.8.0, etc.) and version bumps live in commits to main. There's no dev or next branch.

Cloning and a first build

git clone https://github.com/cloudflare/pingora.git
cd pingora
cargo build

A no-feature build compiles every crate in the workspace but produces a pingora binary that won't do TLS. To build something that resembles a typical proxy:

cargo build -p pingora --features "proxy lb cache openssl"

Other useful feature combinations are listed in pingora/Cargo.toml. The umbrella crate's features turn on the right pieces of pingora-core, pingora-proxy, etc.

The iteration loop

# Pick a crate to work on
cd pingora-proxy

# Fast feedback
cargo check
cargo clippy
cargo test

# When touching the proxy state machine, run the integration tests too
cargo test --features openssl

For changes that span crates, run from the workspace root:

cargo test --workspace

Common file layout

Each crate has src/lib.rs plus optional submodules. The bigger crates (pingora-core, pingora-cache, pingora-proxy) split logic across many files. tests/ directories contain integration tests; examples/ contains runnable example binaries (the load-balancer example is in pingora-proxy/examples/load_balancer.rs).

Documentation

Inline /// doc comments are the source of truth. The CI workflow .github/workflows/docs.yml builds rustdoc with --cfg docsrs so feature-gated modules show their gating. To preview locally:

cargo doc --no-deps --features "proxy lb cache openssl"

Then open target/doc/pingora/index.html.

The narrative documentation under docs/user_guide/ is hand-written Markdown, not extracted from doc comments.

Cargo workspace conventions

• All crates declare version = "0.8.0" in lockstep. When the workspace bumps, every crate bumps.
• Path dependencies use both path = "..." and version = "0.8.0" so the published crates work without the workspace.
• Workspace-level dependencies (tokio, bytes, etc.) are pinned in the root Cargo.toml [workspace.dependencies] table. Member crates use tokio = { workspace = true }.

Pre-commit checks

There's no enforced pre-commit hook, but the CI in .github/workflows/build.yml runs:

• cargo build on stable, beta, and the MSRV (1.84)
• cargo test --workspace
• cargo clippy --workspace -- -D warnings
• cargo fmt --check
• A docs build (cargo doc)
• A Semgrep OSS scan (.github/workflows/semgrep.yml, added 2026-04)
• A cargo-audit security check (.github/workflows/audit.yml)

Run those four locally before pushing and you'll match what CI does:

cargo fmt
cargo clippy --workspace -- -D warnings
cargo test --workspace
cargo doc --no-deps

Linting config

• clippy.toml (14 bytes — minimal config, mostly default rules)
• .rustfmt.toml (17 bytes — tiny override over default rustfmt)

The repo trusts the upstream lint/format defaults.

Submitting a PR

1. Rebase onto current main.
2. Reference the issue you filed in the PR description.
3. CI will run automatically. Wait for green.
4. Address review feedback.
5. After acceptance, your commits will be picked up in a batched rebase onto main (see How to contribute).