Development workflow

The full lifecycle of a change: local checkout, branch, code, test, push, review, merge, backport.

Active branches

• master — the integration branch. All new development lands here first.
• release-1.X — long-lived stable branches, one per minor version. Patch releases are cut from these. Backports happen via /cherry-pick release-1.X comments on merged PRs.
• experimental-* — short-lived branches used for feature experiments.

The release branch policy is documented in RELEASE_BRANCHES.md: the project supports the latest three minor releases, plus a brief LTS-ish window for the previous one.

Local setup

# Fork on GitHub, then:
git clone git@github.com:<you>/istio.git
cd istio
git remote add upstream git@github.com:istio/istio.git

# Keep your fork in sync
git fetch upstream
git checkout master
git rebase upstream/master

Most contributors keep master clean and develop on topic branches:

git checkout -b fix/eds-cache-invalidation

Build and test

The fastest inner loop is package-scoped:

# Build everything
make build

# Run only the package(s) you touched
go test -race -tags=assert ./pilot/pkg/networking/core/...

# Or via make
make test PKG=./pilot/pkg/networking/core/...

The full pre-PR sweep:

make precommit       # format and lint
make gen-check       # ensure all generated code is up to date
make test            # full unit-test run with -race -tags=assert

make build writes binaries to out/<os>_<arch>/. If you want to test istiod against a real cluster, build, push to a registry, and reuse Helm charts:

HUB=docker.io/<you> TAG=dev make docker.push
istioctl install --set hub=docker.io/<you> --set tag=dev

For end-to-end validation against KIND clusters, the integration framework (in pkg/test/framework/ and tests/integration/) handles cluster setup. See Testing.

Commit conventions

• One logical change per commit. Reviewers expect to be able to walk through a PR commit-by-commit.
• Subject line ≤ 72 chars, imperative mood: pilot: don't push EDS for headless services without selectors.
• Sign off all commits with -s. The DCO bot will block merges otherwise.
• Mention the GitHub issue if there is one (Fixes #59001). Keep the body to a few paragraphs; longer rationale belongs in the release-note YAML or a doc.

The repo does not require Conventional Commits format. Subject prefixes (pilot:, cni:, istioctl:) are common but not enforced.

Opening the PR

Push to your fork and open a PR against istio/istio:master. Fill out the PR template:

1. Description — why, not just what. Link related issues.
2. Affected areas — check every box that applies. This determines who Prow auto-assigns.
3. User-facing change checkbox — drives whether a release note is required.

The first time you open a PR, the CLA bot will ask you to sign the Istio CLA. Do that before requesting review.

Review and merge

Each affected area has a working-group team in CODEOWNERS. Prow auto-assigns reviewers from the relevant teams. Typical sequence:

1. CI runs (lint, unit tests, integration smoke).
2. A WG reviewer leaves comments. Push fixups; do not squash before approval.
3. WG reviewer leaves /lgtm.
4. WG approver leaves /approve.
5. Tide merges automatically once labels are right.

Common labels:

Label	Meaning
lgtm	A reviewer signed off.
approve	An approver signed off.
do-not-merge/work-in-progress	Block merge.
release-notes-required	The release-note YAML is missing.
kind/bug, kind/cleanup, kind/feature	Categorization for the changelog.
cherrypick-approved	Auto-cherry-pick has been approved by a maintainer.

PRs that touch many areas can need approvals from multiple WGs. The bot will leave a comment listing the outstanding teams.

Backports

After merge, comment /cherry-pick release-1.X to request an automatic cherry-pick to a release branch. The bot will open a follow-up PR, run CI, and assign maintainers. If the cherry-pick has merge conflicts, you'll be asked to do it manually:

git fetch upstream
git checkout -b backport-fix-1234-1.27 upstream/release-1.27
git cherry-pick -x <sha-on-master>
# resolve conflicts, then push

Cherry-picks of bug fixes are usually accepted; new features generally are not. The release branch maintainers (istio/wg-test-and-release-maintainers) make the call.

Release cadence

Minor releases are cut roughly quarterly (see the cadence in Lore). The release process is automated by prow/release-commit.sh and the scripts under release/. Release notes for a given version are aggregated from the YAML files under releasenotes/notes/ and rendered via the tooling in releasenotes/.

If you're working on a feature that needs to land in a specific release, check the release-tracking issue for that minor (filed by the wg-test-and-release-maintainers) and align with the WG.