# Skill — `bump-chart-version`

> **Layer:** Layer 1 — agent generates diff and opens PR; platform team reviews; per-cluster Sync is the deploy.
> **Scope:** updating `helm-templates/<chart>/Chart.yaml` `dependencies[].version` and refreshing `Chart.lock`.

This skill is the agent-callable form of [docs/platform/procedures/update-chart-version.md](../../docs/platform/procedures/update-chart-version.md).

---

## When to use

Triggers like:

- "Bump `<chart>` from `<old>` to `<new>`."
- "Upgrade `argo-cd` to 7.8.0."
- "Apply CVE patch to `<chart>` — bump to <new>."

Do **not** use this skill for:

- Major-version bumps with breaking template changes (use `blue-green-chart-migration` procedure).
- Forking a chart (use `fork-upstream-chart` procedure).
- Bumping a chart's local version when it's already a fork (the `version:` field at the top of `Chart.yaml`, not `dependencies[].version`).

---

## Input

Required:

```yaml
chart:        <chart-name>          # must exist in helm-templates/
old_version:  <semver>              # current dependencies[].version
new_version:  <semver>              # target
```

Optional:

```yaml
representative_cluster: <cluster-folder>   # for the test render; if omitted, skill picks one
sample_helm_diff:       <bool>             # if true, run helm diff against a live cluster (requires kube context)
```

---

## Steps (deterministic)

1. **Pre-conditions.**
   ```bash
   ls helm-templates/<chart>/Chart.yaml
   yq e '.dependencies[0].version' helm-templates/<chart>/Chart.yaml   # confirm == <old_version>
   ```

2. **Read the changelog.** Output a one-line note with the changelog URL or an explicit "READ THE CHANGELOG: <url>" message. The skill does not auto-fetch; the user must confirm they've read it. If the user hasn't, **stop**.

3. **Update `Chart.yaml`.**
   ```bash
   sed -i.bak "s/^    version: <old_version>$/    version: <new_version>/" \
     helm-templates/<chart>/Chart.yaml
   rm helm-templates/<chart>/Chart.yaml.bak
   ```
   (Or use `yq` with a path expression — depending on `dependencies[]` shape.)

4. **Refresh `Chart.lock`.**
   ```bash
   helm dependency update helm-templates/<chart>
   ```
   On failure: surface the error and stop. Common causes: new version doesn't exist, repo URL changed, network issue.

5. **Render against the representative cluster.**
   ```bash
   sibling=${representative_cluster:-$(find helm-overrides -maxdepth 2 -type d -name '<chart>' \
                                       | grep -v '^helm-overrides/db-' | head -1)}
   helm template <chart> helm-templates/<chart> -f "$sibling/custom-values.yaml" > /tmp/render.yaml
   ```
   On failure: surface the error and **roll back** (`git checkout helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock`); stop and report. The bump is incompatible with current values.

6. **(If `sample_helm_diff: true`)**
   ```bash
   helm diff upgrade <release> helm-templates/<chart> \
     -f helm-overrides/<sibling>/<chart>/custom-values.yaml \
     --kube-context=<context>
   ```
   Capture the diff and put it in the PR body.

7. **Open the PR.**
   ```bash
   git checkout -b chart-bump/<chart>-<new_version>
   git add helm-templates/<chart>/Chart.yaml helm-templates/<chart>/Chart.lock
   git add helm-templates/<chart>/charts/   # if subchart .tgz refreshed
   git commit -m "chart bump: <chart> <old_version> -> <new_version>"
   git push origin chart-bump/<chart>-<new_version>
   gh pr create --base main --title "chart bump: <chart> <old_version> -> <new_version>"
   ```

   PR body (heredoc):

   ```markdown
   ## Summary
   Bumps `<chart>` from `<old_version>` to `<new_version>`.

   - Upstream changelog: <url>
   - Procedure: `docs/platform/procedures/update-chart-version.md`
   - Skill: `skills/infra/bump-chart-version.md`

   ## Affected clusters
   <list from `grep -rl '<chart>' helm-overrides | sort -u`>

   ## Validation
   - `helm dependency update` succeeded
   - Render against `<representative_cluster>`'s overrides: clean
   - (if sample_helm_diff) diff against live: <one-line summary>

   ## Approver
   Platform team

   ## CMR
   <ticket if applicable>
   ```

---

## Output

A PR diff with:

- `helm-templates/<chart>/Chart.yaml` updated (version line)
- `helm-templates/<chart>/Chart.lock` refreshed
- `helm-templates/<chart>/charts/*.tgz` (if the subchart was re-pulled)

The skill does **not**:

- Sync any cluster (manual per-cluster Sync after merge).
- Update any `helm-overrides/<cluster>/<app>/custom-values.yaml` to handle a values-shape change. If the bump requires that, **stop and surface a follow-up task** — don't bundle.
- Open per-cluster Sync recommendations as separate work items.

---

## Gotchas

1. **`Chart.yaml` without `Chart.lock` is a no-op.** Argo CD reads the lockfile.
2. **The skill must roll back on render failure.** Otherwise a half-committed bump leaves the repo in a broken state.
3. **For wrapper charts whose `dependencies[]` has multiple entries**, the skill must operate on the right one. Don't bump the wrong dep.
4. **Major-version bumps are not this skill's job.** If `new_version` is a major increment (`7.x → 8.x`), refuse and recommend [blue-green-chart-migration](../../docs/platform/procedures/blue-green-chart-migration.md).

---

## Layer constraint

Layer 1. Open the PR; do not merge it; do not click Sync on any cluster.

---

## Related

- Procedure: [update-chart-version.md](../../docs/platform/procedures/update-chart-version.md).
- Procedure: [blue-green-chart-migration.md](../../docs/platform/procedures/blue-green-chart-migration.md).
- ADR: [ADR-A1-cache-vs-upstream-charts.md](../../wiki/analyses/ADR-A1-cache-vs-upstream-charts.md).