---
applyTo:
  - "charts/**"
---

# Helm charts

## `charts/calico` is not a user-facing chart

Only three charts here are packaged and published: `tigera-operator`,
`crd.projectcalico.org.v1`, and `projectcalico.org.v3` (see the
`helm package` rules in the root `Makefile`).

`charts/calico` is never installed with Helm by anyone. It exists
only as the template source that `make gen-manifests` renders into
the `manifests/calico*.yaml` files, and those rendered manifests are
the only thing users consume. So when changing that chart, the
rendered output in `manifests/` is the entire contract. End-user
chart usability does not apply: there is no Helm upgrade path to
preserve, and there are no user-facing install instructions to keep
in sync. Review it by reading the diff in `manifests/`.

The `values.yaml` keys are an internal interface, not a user-facing
one, so they can be renamed or restructured as long as the same PR
updates every in-repo consumer:

- `manifests/generate.sh` reads `.version` and `.node.registry`, and
  passes several keys back in via `--set`.
- The root `Makefile` reads `.version` for the `helm package` and
  release targets.
- `hack/check-images-availability.sh` reads `.version` and
  `.node.registry`.
- The overlay files in `charts/values/` are merged over the defaults
  and reference keys by path.

## User-facing install instructions

The install and upgrade instructions users follow live in two
README files, not in a `DESIGN.md`:

- [`charts/tigera-operator/README.md`](../../charts/tigera-operator/README.md)
  — the Installing and Upgrading flows for the operator chart.
- [`charts/crd.projectcalico.org.v1/README.md`](../../charts/crd.projectcalico.org.v1/README.md)
  — install/upgrade for the separately shipped CRD chart.

These READMEs are hand-written, not generated. They drift silently
when a chart change alters the steps a user has to run but the doc
is left alone — that drift is what shipped a broken install in
v3.32 (CRDs moved to their own chart, but the operator README still
said `helm install` the operator chart directly). See #12860.

Before reviewing a PR (Copilot code review) that touches any file
matched by this instruction's `applyTo`, check whether the change
affects how a user installs or upgrades Calico via Helm, and if so
whether the two READMEs above still match. Things that change the
user-facing steps include: moving resources between charts (CRDs
especially), adding or removing a manual prerequisite step,
renaming a chart or the repo, changing the namespace handling, or
changing a documented values key or example command.

## Update rule

A chart PR that changes how a user installs or upgrades Calico via
Helm must update the matching install/upgrade instructions in the
same PR.

**Exemption.** No README update is needed if the change does not
alter any documented step — e.g. a values default that the README
never mentions, a templating-only refactor, or a generated-CRD
content bump. If in doubt, update the doc.

`charts/calico` is always exempt from this rule, for the reason
above: no user installs it, so no install instructions can drift. A
PR touching it does need the regenerated `manifests/` committed
alongside.

## Amending the PR

The Copilot automated code-review step is read-only with respect
to the PR branch — it cannot push the doc amendment itself. When
the review flags a missing update per the rule above, its comment
should include a ready-to-paste `@copilot` prompt naming the README
and the step that drifted, for example:

> `@copilot update charts/tigera-operator/README.md Installing section to cover the new CRD install step — users must apply the crd.projectcalico.org.v1 chart before installing the operator chart.`

The reviewer (or author) drops that into a new PR comment; the
Copilot coding agent picks it up and pushes a commit with the
amendment to the PR branch.