How to contribute

This section is the day-one reference for working in the istio/istio codebase. It assumes you have already cloned the repo and read Getting started for build/test prerequisites.

In this section

• Development workflow — branch naming, PR review, CI, release notes, the working-group / WG-maintainer routing model.
• Testing — unit, integration, and benchmark suites; how to run them; how to scope a run to your code.
• Debugging — istiod debug endpoints, istioctl proxy-config/proxy-status, log scopes, control-plane / data-plane troubleshooting.
• Patterns and conventions — coding standards, error handling, metrics naming, log scopes, krt vs informers, generated code rules.
• Tooling — Makefile structure, build container, generated code, release tooling.

Picking up work

Issues are organized by working group (see the categories in the PR template: Ambient, Configuration Infrastructure, Networking, Security, …). Each WG has maintainers in CODEOWNERS (istio/wg-<area>-maintainers). Good pickup patterns:

• Open issues labeled help wanted and good first issue.
• Issues filed under your WG's project board.
• The WG meeting notes (linked from istio/community) often track loose ends nobody has claimed.

For larger features, the convention is to communicate intent first — open a tracking issue, attend the WG meeting, or open a WIP PR. The repo's Project Conventions page on the GitHub wiki documents this in detail.

PR process at a glance

graph TD
    A[Open PR] --> B[CI: lint + unit + integration]
    B --> C{Passes?}
    C -->|No| D[Fix and push]
    D --> B
    C -->|Yes| E[WG maintainer review]
    E --> F{LGTM?}
    F -->|Changes requested| D
    F -->|approved + lgtm| G[Tide auto-merges]
    G --> H[Cherry-pick bot mirrors to release-1.x branches if labeled]

The Istio project uses Prow (configured under prow/) for CI orchestration. PR commands include:

• /lgtm — approve. Required from a WG reviewer.
• /approve — pre-merge approval. Required from a WG approver.
• /retest — rerun failed CI jobs.
• /hold — block merge.
• /cherry-pick release-1.27 — request automated backport after merge.

Tide, the Prow merge bot, takes care of merging once the right combination of labels is present (lgtm, approve, no do-not-merge). You should not push directly to master.

Release-note YAMLs

Almost every user-visible change requires a release note. Add a YAML file under releasenotes/notes/ named after your PR or topic (releasenotes/notes/<short-name>.yaml). The schema lives in releasenotes/template.yaml; the most important fields are kind (feature, bug-fix, security-fix, …), area, releaseNotes, upgradeNotes, and securityNotes.

The PR template's last checkbox — "Does not have any user-facing changes" — is the only way to opt out. CI will warn if the PR is missing a release note and that box is unchecked.

Filing bugs and feature requests

The repo's BUGS-AND-FEATURE-REQUESTS.md explains where to file issues. The TL;DR:

• Bugs/feature requests for the codebase → here, in istio/istio.
• Documentation issues → istio/istio.io.
• API definition issues → istio/api.
• Ztunnel issues → istio/ztunnel.

For security issues, follow .github/SECURITY.md. Do not file public issues for security bugs.

Definition of done

Before requesting review:

1. make precommit (format + lint).
2. make gen-check (regenerate code, ensure no diffs).
3. make test PKG=./<your-area>/... for fast feedback; make test for the whole tree.
4. Add unit tests with the new code. The convention is co-located: a function in foo.go is tested in foo_test.go.
5. Add or update a release note in releasenotes/notes/.
6. If you touched APIs (CRDs, MeshConfig, generated code), run make gen and commit the generated files.
7. Sign-off is enforced by the DCO bot. Use git commit -s.