How do you set the versioning policy for a Helm chart that many teams install?

## What the number has to mean A chart version is the only communication channel you have with people who install your chart. Everything else — the README, the migration note, the chat announcement — is optional reading. So policy starts by deciding what a consumer may infer from a bump, and the useful inference is about *their* risk, not your release process: can they take this upgrade without editing their values file or expecting a restart? ## The two coherent models **Chart version tracks the application.** The chart is packaging for one service, the same team owns both, and every application release publishes a chart. Often chart `version` and `appVersion` are simply equal. This is genuinely good when the chart is deployed only by its own pipeline: one number, no ambiguity, and the chart version answers "which build is this?". It breaks down as soon as the chart is a product: a template-only fix has no application version to borrow, so you either invent one or break the equality you promised; and a consumer reading a jump from 1.14.3 to 1.15.0 learns something about your application and nothing about their values file. **Chart version tracks the chart's contract.** Major when the values interface or the rendered topology breaks, minor when you add optional values or new optional objects, patch when you fix a template without changing output for anyone. `appVersion` floats independently and simply records what is inside. This is the right default for a chart many teams install, because the number now answers the question the consumer actually has. Its cost is that two numbers must be read together, and that you have to be disciplined about what "changes output for anyone" means — changing a default is not a patch. The choosing factors are concrete: how many consumers, whether you can migrate them yourself, whether the same team owns the application and the chart, how often the application releases, and whether the chart is published to a shared repository at all. A chart living in the application's own repository and deployed only by its own pipeline barely needs a policy — the pipeline pins a commit and the version is decoration. The moment a second team installs it, everything above applies. ## Budgeting majors The expensive fact is that a major is not an event in your repository; it is a piece of work in every consumer's. With seventeen consuming teams, one values rename is seventeen pull requests, seventeen review queues and seventeen deploys, spread over however long the slowest team takes. That drives real policy. Batch breaking changes rather than trickling them: hold a `next-major` branch of intended changes and ship them together. Budget majors explicitly — at most one or two a year for a widely installed chart — and treat wanting a third as a design smell in the values interface. Announce before publishing, with a before-and-after values snippet. And keep a bridge where you can: accept the old and new key for one minor line, warn through `NOTES.txt`, then remove in the next major. A bridge with no removal date is just a permanent second interface. ## Channels and retirement Prerelease versions give you a canary lane inside the same repository. Publishing `3.0.0-rc.2` is invisible to ordinary installs and upgrades — prerelease versions are excluded from matching unless a consumer opts in — so one friendly team can validate a major before the rest of the world sees it. Promote by publishing `3.0.0` as a new version; never re-push a candidate with different content, and never re-push any published version, because a chart version that means two things destroys the only guarantee you sell. Retirement is a version too. `deprecated: true` in `Chart.yaml` marks a chart as deprecated, and if the *latest* published version carries it the chart as a whole is treated as deprecated: ```yaml apiVersion: v2 name: invoice-worker version: 4.0.0 appVersion: "2.3.1" deprecated: true ``` What that flag does not do is matter to anyone already running the chart: existing releases keep running, and the chart can still be installed. So the flag is the announcement mechanism, not the migration; you still owe consumers a replacement and a path to it, and you still need to know who is on it — which is what `helm list` across your clusters tells you, since the CHART column carries the chart name and version of every live release. ## What a principal answer sounds like It does not recite version-number rules. It says what the number promises, admits the tradeoff between the two models rather than declaring one correct, prices a major in other teams' time, and names the mechanisms Helm actually gives you: a version consumers resolve, an appVersion that is metadata, prerelease exclusion as a channel, a deprecation flag as an announcement, and nothing else. Everything more — knowing who is installed, chasing migrations — you have to build.