dependency-update-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Dependency-update conventions

## On GitHub, Dependabot first

**Use Dependabot for every ecosystem it supports. Reach for Renovate only for
what it does not cover.** It is built into the platform: no app to install, no
token to rotate, no self-hosted runner, and its findings sit next to the
security alerts for the same repository. A second bot is a second thing to
configure, debug and explain.

- **Check what Dependabot supports today rather than assuming.** The list
  grows — read
  <https://docs.github.com/en/code-security/reference/supply-chain-security/supported-ecosystems-and-repositories>
  before concluding that something needs Renovate. Answering from memory is
  how a repo ends up running two bots for one job.
- **What Renovate is actually for**, once Dependabot has taken its share:
  - a version string **no manager knows about** — a chart version inside a
    jsonnet or YAML catalog, a pinned tool version in a `Makefile`, a CI
    script or a `Dockerfile` `ARG`. That is a custom manager, and Dependabot
    has no equivalent.
  - grouping or scheduling rules Dependabot cannot express.
- **Off GitHub — GitLab, Gitea, self-hosted — Renovate does the whole job.**
  There is no Dependabot to prefer.
- **"Dependabot first" is not "Dependabot for as much as possible".** In a repo
  where Renovate is already required for the bulk — a GitOps repo, where the
  `argocd`, `helm-values` and `crossplane` managers see chart and image
  versions Dependabot has no manager for — handing it back one ecosystem it
  covers coherently buys nothing and splits one review flow in two. The stable
  split there is **`github-actions` to Dependabot, everything else to
  Renovate**: Dependabot handles SHA pins and their trailing tag comments
  natively, which is the one thing worth keeping it for.

**Never point both bots at the same ecosystem or the same file.** Two PRs for
one bump, two lockfile updates that conflict with each other, and reviewers
who learn to skim. Make the split explicit rather than implicit: give Renovate
an `enabledManagers` list covering only what Dependabot does not, and say
where the line is drawn in the config's own `description` (and in
`CONTRIBUTING.md` if contributors need to know which bot opens what).

Two ways to draw it, and they are not equivalent:

```json
{
  "description": "Dependabot owns cargo, docker and github-actions; Renovate only handles the chart versions in the catalog, which no Dependabot ecosystem sees",
  "enabledManagers": ["custom.regex"]
}
```

```json
{
  "github-actions": { "enabled": false }
}
```

The **allowlist** is the safer default when Dependabot owns several ecosystems:
a manager Renovate gains in a future release cannot start racing. The
**blocklist** is right when Renovate owns everything but one — turning off the
single overlapping manager states exactly that, and an allowlist would need
editing every time the repo grows a new file type.

## Never automerge

**No automerge, in any form.** Not `automerge: true`, not an automerge preset
(`:automergeMinor`, `:automergeDigest`, …), not `platformAutomerge`, not
`@dependabot merge`, and not a workflow that runs `gh pr merge --auto` on a
bot PR.

The reason is not fear of breakage — it is that **a dependency bump is a
change to production that nobody read**. Green CI is not a review: it proves
the tests that already existed still pass, which is exactly the bar a
compromised release is built to clear. The supply-chain attacks that matter
all ship a version whose test suite is green.

**`platformAutomerge: false` does not disable automerge**, and reads as though
it does. It only chooses *who* merges: with `automerge: true` still set,
Renovate merges the PR itself instead of handing GitHub's auto-merge the job.
A config carrying `"platformAutomerge": false` next to `"automerge": true` is
an automerging config.

The cost is real and is paid deliberately: someone presses merge. Bring the
number of presses down with **grouping and scheduling**, never with automerge:

- group patch and minor updates per ecosystem into one PR; keep every major
  on its own, because that one needs the release notes read;
- **group what must move together** — a different reason, which prevents
  breakage rather than noise; see the next section;
- `minimumReleaseAge` (Renovate) / `cooldown` (Dependabot) so a release has to
  survive a few days in the wild before it is proposed;
- `prConcurrentLimit` / `open-pull-requests-limit` so the queue stays a queue
  and not a wall.

## Group what must move together

Some packages are released in lockstep: a core crate and its SDK and
exporters, a framework and its integrations, two charts version-locked
upstream, the chart and the CRD set that are two sources of one `Application`.
A bot opens **one PR per package**, and each of them is broken on its own —
either it fails to build, or it merges alone and runs a combination nobody
tested.

**Spot it on the PRs themselves.** Several bot PRs for the same family, opened
together, all red with type or trait mismatches between sibling packages
(`expected X, found X` naming two versions of one crate, a method or trait
impl that "does not exist" on a type from the sibling), are one lockstep
group, not N bugs. Bumping one member leaves two versions of the core in the
dependency graph; that is the whole error.

**Then, instead of patching each PR:**

1. Open one PR that bumps the whole family together, and fix the code there
   if the new release genuinely needs it — usually it does not.
2. Add the group to the bot config **in that same PR**, so the next release
   arrives as one PR.
3. Close the bot PRs it supersedes, each with a comment naming the PR that
   replaces them.

**The group takes every update type, majors included.** A lockstep family
breaks on a major exactly as on a minor, and `0.x` families bump the minor for
a breaking release anyway. Dependabot puts a dependency in the **first**

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude