Contributing

Contributing overview

The rules every change must follow, the quality gates and the CI jobs.

Postguy is developed in the open at github.com/zuramai/postguy. Bug reports, fixes, documentation and features are welcome. Report bugs and propose changes through GitHub issues.

The binding rules live in AGENTS.md. They apply to every human and AI contributor. This page summarises them. If the two differ, AGENTS.md wins.

Ways to contribute

Pick work from the ranked list in Known gaps before you add new low-priority features.
Fix or extend a feature: follow Adding a feature.
Improve these pages: see Writing the documentation.
Report a bug with the steps to reproduce it. Use synthetic data only. Never paste real tokens, API keys or responses into an issue.

Before you start:

Read the README of the crate you will touch.
Read Architecture.
Set up your machine with Development and Build from source.

The binding rules in brief

Area	Rule	AGENTS.md
Assets	Nothing from a Postman product. Only allowed licences. Every asset has an `ATTRIBUTION.toml` entry. Poppins is the one approved embedded font.	section 1
Clean-room	Behaviour comes from public specifications and documentation, not from reading other implementations. No copyleft code.	section 2
Agent control	Every feature is reachable headlessly through a tool in `crates/automation`, with an end-to-end test. The control channel and the MCP server are opt-in.	section 3
Never crash	No `unwrap`, `expect`, `panic!` or `unsafe` outside tests. Cap and check every input-derived value. Every crash fix ships a regression test.	section 4
Privacy	No request the user did not start: no telemetry, no crash upload, no update check, no cloud sync. Never log secret values or the control-channel token.	section 5.2
Rust only	No handwritten JS/TS in the product or the build. The documentation site in `docs/` is the one exception, and it is limited to config and Markdown.	section 5.2
Layering	Nothing below L7 depends on egui, winit, eframe or rfd. `cargo xtask layers` enforces this.	section 5.2
Dependencies	Permissive licences only (`deny.toml`), `default-features = false`, no internal `craft-*` repositories.	section 5.2

More detail: Assets and clean-room, Adding a feature, Writing the documentation.

Maintainers review external pull requests in this order:

Provenance: no Postman-derived asset, no committed font, no copied GPL/AGPL code, no behaviour taken from reading another implementation.
Safety.
Completeness.
Style.

Provenance comes first because you cannot undo it after a merge.

Branches, commits and pull requests

main is the only integration branch. Never push to it directly.
Branch from an up-to-date main as <type>/<slug>. The type is feat, fix, docs, chore or refactor (for example docs/docus-site).
Use conventional commit messages, for example feat(http): follow redirects with cookie capture. Commit only green states.
Open a pull request into main with the PR template. Merge only when CI is green.
Rebase your own branch the day main moves under it.

The PR template has these sections:

Section	Content
What	What changes, in one paragraph. Link the issue and any parity entry it affects.
Context	Why: the problem and the observed behaviour.
Changes	Bulleted list of real changes: crates touched, public API deltas, migration notes.
Rules check	The five checks below.
Evidence	The exact commands you ran and their results (scoped `-p` builds).
Screenshots	For UI changes only, from the app's own UI with demo data.

The Rules check has five items:

Provenance: no Postman-authored assets, no code ported from other implementations, no font files committed.
Safety: no new panic path or unsafe. Every input-sized value is checked or capped. Last-resort guards wrap places where untrusted input runs.
Automation: the feature is reachable headlessly (a tool in crates/automation) with an end-to-end test.
Parity: parity/postman-features.toml is updated honestly (shipped only with cited tests).
Layering and budgets: cargo xtask layers is clean, there is no repaint loop, there is no UI-thread I/O, and the release profile is untouched.

Quality gates

Before every commit, run:

cargo fmt --check
cargo clippy -p <crate> -j 2 --all-targets -- -D warnings
cargo test -p <crate> -j 2
cargo xtask layers
cargo xtask assets

Scope clippy and tests to the crates you touched (-p <crate>, -j 2) and wrap them in timeout. A full --workspace build can lock up a development machine. CI runs the full sweep on every pull request.

cargo xtask ci runs the whole bundle and stops at the first failure: fmt --check, clippy with -D warnings, tests, layers, assets, parity and deny.

Other cargo xtask commands:

Command	Purpose
`layers`	Enforce the crate dependency layering.
`assets`	Enforce the asset policy against `ATTRIBUTION.toml`. `--write` regenerates `ATTRIBUTION.md`.
`parity`	Validate `parity/postman-features.toml` against the registry, tools and tests, and report progress (`--json`, `--partial`).
`deny`	Check dependency licences and sources with `deny.toml` (delegates to cargo-deny when installed).
`size`	Measure the release binaries against the size budgets.
`bench`	Capture headless frame times. `--check` enforces the budgets.
`icons`	Regenerate `crates/ui-egui/src/icons_gen.rs` from `assets/icons/*.svg`. `--check` verifies.
`logo`	Rasterise `assets/logo/postguy.svg` into the packaging PNG sizes. `--check` verifies.
`fuzz`	Mutation-fuzz the parsers and importers. Findings go to `fuzz-out/` (`--time 300`).
`screenshots`	Regenerate screenshots from the app's own UI with demo data (`--out DIR`).
`version`	Print the workspace version, or `version set X.Y.Z` to change it.
`ci`	The full gate bundle described above.

Continuous integration

.github/workflows/ci.yml runs on pushes to main, on pull requests, on manual dispatch and nightly at 03:17 UTC.

Job	Runs on	What it does
`test`	`ubuntu-latest`, `windows-latest`	`cargo clippy --workspace --all-targets -- -D warnings` and `cargo test --workspace --no-fail-fast`. On Linux only, it also runs `cargo fmt --all -- --check`, `cargo xtask layers`, `cargo xtask assets`, `cargo xtask parity` and `cargo xtask deny`.
`test-macos`	`macos-latest`	`fmt --check`, clippy and tests. Only on pushes to `main`, not on pull requests.
`deny`	`ubuntu-latest`	`cargo-deny check` for advisories. Not on pull requests.
`fuzz`	`ubuntu-latest`	`cargo xtask fuzz --time 900`. Only on the nightly schedule or manual dispatch. Findings are uploaded as the `fuzz-findings` artifact.

Two more workflows exist:

Docs builds and publishes this site. See Writing the documentation.
Release builds the packages. See Releasing.

Edit this pageorReport an issue

Feature status

What is shipped, partial, planned or out of scope in each area, from the parity file, plus the known limitations in plain terms.

Development

Toolchain, everyday commands, working rules and the CI gates.