How to contribute

Envoy is one of the most heavily reviewed C++ projects in the open-source world. Pull requests are merged by maintainers — see OWNERS.md — and there is more process than in most projects, because the proxy runs on the data path of large parts of the internet. This section is the contributor's lens; the user-facing documentation lives at envoyproxy.io.

The canonical contributor docs

You should read these in addition to (or before) this wiki:

• CONTRIBUTING.md — communication norms, breaking-change policy, code review expectations, and the inclusive language policy (no whitelist/blacklist/master/slave).
• STYLE.md — the C++ style guide, with the deltas from Google C++ style.
• PULL_REQUESTS.md — what each section of the PR template means.
• PULL_REQUEST_TEMPLATE.md — the template itself.
• REPO_LAYOUT.md — where things live.
• EXTENSION_POLICY.md — rules for new extensions.
• GOVERNANCE.md — how decisions are made.
• SECURITY.md — security release process.
• api/API_VERSIONING.md — xDS API versioning.

What this section covers

Page	Topic
Development workflow	Branch, code, test, PR, review, merge — and runtime guards for risky changes.
Testing	Unit tests, integration tests, fuzz tests, mocks. The test/ tree in detail.
Debugging	What goes wrong and how to find out — log levels, gdb, stack decoder, admin endpoints.
Patterns and conventions	The in-house C++ idioms: *_impl.cc, factory registration, smart-pointer aliases, error handling.
Tooling	What lives in tools/ — formatter, proto-format, dependency manager, release scripts.

DCO and CLA

Every commit must be signed off (git commit -s) per the Developer Certificate of Origin. The DCO bot will reject PRs without it. There is no separate CLA; the DCO is the contribution agreement.

Definition of done

Before a PR can be merged it generally needs:

1. CI green on Azure Pipelines: format checks, all sanitizer builds, full test matrix. CI is gated on every PR.
2. Code formatted by tools/code_format/check_format.py and clang-format.
3. Tests added for any behavioural change. Unit tests for code in source/, integration tests for anything visible from outside the process (see Testing).
4. Release note in changelogs/current.yaml for any user-visible or filter-API-visible change.
5. API review if you touched anything in api/ (see api/review_checklist.md).
6. Runtime guard if the change is a behavioural modification (per CONTRIBUTING.md).
7. Two approvals including at least one from a CODEOWNER for the affected code (see CODEOWNERS and maintainers).

What gets rejected

Common reasons PRs stall, drawn from the contributor docs and the bot's standard messages:

• Adding a new feature with > 100 LOC altered (excluding tests) without a tracking issue.
• Adding a new extension without following the extension policy.
• Touching the data plane in a way that introduces or relies on C++ exceptions.
• Adding using namespace ... or non-PoD globals.
• A user-visible behavioural change without a runtime guard.
• A configuration change without a release note.
• Drive-by AI review comments without engagement.

AI policy

The project's generative AI policy allows AI-assisted code and review with two non-negotiable conditions: the human submitter understands the change, and the human responds to review comments. Review comments produced by an AI agent must be vetted by the reviewer; "drive-by" AI comments that the reviewer will not follow up on are not allowed.

Releases and backports

The release cycle is documented in RELEASES.md: a quarterly cadence with backports controlled by BACKPORTS.md. Release branches live as release/v1.X and currently span four supported lines simultaneously.