Development workflow

Branching model

• main is the development branch. The current dev version is 1.20.0-dev (VERSION).
• v1.NN branches (v1.17, v1.18, v1.19) are stable release branches. The community supports the latest three minor releases (see README.rst).
• Backports are tracked via PR labels (needs-backport/1.19, etc.) and resolved with contrib/backporting/ scripts.
• Tags follow v1.NN.PP for stable releases and v1.NN.0-pre.X / v1.NN.0-rc.X for development releases.

PR cycle

1. Fork github.com/cilium/cilium to your account.

2. Branch from main (or the relevant stable branch for backports). Use pr/<your-handle>/<topic> or any descriptive name.

3. Commit with the DCO sign-off (git commit -s). One logical change per commit; rebase rather than merge.

4. Test locally:

   make unit-tests
   make -C bpf unit-test           # if you touched bpf/
   make checkpatch                 # commit message + go vet + gofmt

5. Update generated files if you changed CRDs, OpenAPI, Helm, or BPF struct layouts:

   make generate-api
   make generate-k8s-api
   make -C Documentation update-cmdref
   make -C Documentation check

6. Open the PR. Fill in the PR template, including a release-note block. CI runs immediately.

7. Iterate on review feedback. Force-push is fine and expected; reviewers use git range-diff.

8. Merge. A maintainer applies the ready-to-merge label; the merge bot squashes if you have configured it that way, otherwise commits are kept as-is.

Release notes

Every PR must include a release note in the description, formatted exactly:

```release-note
Short, user-visible description.

Possible "kinds" are inferred from PR labels: `release-note/major`, `release-note/minor`, `release-note/bug`, `release-note/misc`, `release-note/ci`, `release-note/dependency`, `release-note/release`, `release-note/none-required`.

## Backports

When a fix needs to land in a stable branch:

1. Apply `needs-backport/X.Y` to the merged PR.
2. A bot proposes a backport PR using `contrib/backporting/start-backport`.
3. Resolve any conflicts manually; commit messages preserve the original `Author` and add `Backport from #NNNN`.
4. Backports merge once they pass CI on the stable branch.

## Releasing

Releases are cut from the stable branches by maintainers using scripts under `contrib/release/`. The release process generates Helm charts, container images (pushed to `quay.io/cilium/...`), SBOM (`Documentation/configuration/sbom.rst`), and signed artifacts (FOSSA / SigStore).

## Continuous integration

CI is implemented in GitHub Actions (`.github/workflows/`). Highlights:

- **`build.yaml`** — Go build of every binary on Linux amd64 and arm64.
- **`golangci.yaml`** — `golangci-lint run` (config in `.golangci.yaml`).
- **`unit-test.yaml`** — `make unit-tests`.
- **`privileged-unit-tests.yaml`** — runs subset of tests as root with BPF maps.
- **`bpf-tests.yaml`** — `make -C bpf unit-test` plus complexity/verifier tests.
- **`conformance-*.yaml`** — connectivity-test against kind matrices for various Kubernetes and kernel versions.
- **`docs-builder.yaml`** — Sphinx docs build under `Documentation/`.

Failures from a "required" workflow block merge. Flaky tests are tracked via the `ci/flake` label.