Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 8 additions & 20 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,32 +11,20 @@ updates:
- dependencies
- github-actions
schedule:
interval: weekly
interval: cron
cronjob: "0 9 * * 1,3,5"
timezone: Europe/Oslo
cooldown:
default-days: 7
groups:
# Bundle low-risk minor and patch bumps into one PR; majors arrive alone
# so they can be reviewed by hand.
actions-minor-and-patch:
patterns:
- "*"
update-types:
- minor
- patch
default-days: 3 # zizmor: ignore[dependabot-cooldown] Three days is the approved organizational cooldown.

- package-ecosystem: pip # Build toolchain pinned in requirements.txt
directory: /
labels:
- dependencies
- python
schedule:
interval: weekly
interval: cron
cronjob: "0 9 * * 1,3,5"
timezone: Europe/Oslo
cooldown:
default-days: 7
groups:
python-minor-and-patch:
patterns:
- "*"
update-types:
- minor
- patch
default-days: 3 # zizmor: ignore[dependabot-cooldown] Three days is the approved organizational cooldown.
35 changes: 7 additions & 28 deletions src/docs/Capabilities/dependency-updates/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,8 @@ lands pull requests outside the hours anyone triages them.

```yaml
schedule:
interval: weekly
day: monday
time: "09:00"
interval: cron
cronjob: "0 9 * * 1,3,5"
timezone: <the organization's working timezone>
```

Expand All @@ -66,11 +65,10 @@ bad now, and waiting for a schedule window or a cooldown would be waiting on pur

## The updater

Dependabot opens **one PR per outdated or vulnerable dependency** — or one per
configured **group** of related dependencies — carrying the bump and the
upstream release notes. SHA-pinned dependencies get the new commit SHA with the
version as a trailing comment. Ecosystems, directories, schedule, cooldown,
grouping, and the static labels all live in `.github/dependabot.yml`.
Dependabot opens **one PR per outdated or vulnerable dependency**, carrying the
bump and the upstream release notes. SHA-pinned dependencies get the new commit
SHA with the version as a trailing comment. Ecosystems, directories, schedule,
cooldown, and the static labels all live in `.github/dependabot.yml`.

```mermaid
flowchart TD
Expand Down Expand Up @@ -133,24 +131,6 @@ The `skip-release` workaround sometimes suggested for this is a **no-op on hoste
Dependabot**; the labelling behavior cannot be configured from the repository. Which label
names exist is the only control, which is why both dimensions are namespaced.

## Grouping

Grouping trades review granularity for review cost, and the trade is only worth
making where the granularity carries no information:

| Group | Contents | Rationale |
| --- | --- | --- |
| Per-ecosystem minor and patch | Every minor and patch update within one ecosystem, in one pull request | Twelve patch bumps reviewed separately cost twelve reviews and reveal no more than one |
| Isolated major | One pull request per major update | This is the diff a reviewer has to read; batching it hides it |

A group MUST NOT span ecosystems. Reviewing an ecosystem's updates requires knowing
that ecosystem's conventions, and a pull request mixing several leaves no reviewer
qualified for the whole diff.

Grouping also bounds the blast radius of a failure. When a grouped pull request goes
red, the failure is attributable to one ecosystem; when a cross-ecosystem batch goes
red, isolating the cause means splitting the pull request by hand.

## Review posture

| Update level | Handling |
Expand Down Expand Up @@ -179,9 +159,8 @@ and the same release path as any other update.
| --- | --- | --- |
| Native ecosystems and directories | `.github/dependabot.yml` | Generated from supported manifests |
| Unsupported ecosystems | Central exception register | Centrally managed shared mechanism |
| Schedule interval, day, time, timezone | `.github/dependabot.yml` | Organization configuration |
| Schedule (`interval`, `day` and `time`, or `cronjob`) and `timezone` | `.github/dependabot.yml` | Organization configuration |
| Cooldown | `.github/dependabot.yml` | Organization configuration |
| Grouping | `.github/dependabot.yml` | Generated: per-ecosystem minor/patch groups, majors isolated |
| Static labels (`dependencies` + ecosystem) | `.github/dependabot.yml` | Generated |
| `update:*` labels | Update metadata → labelling step | Derived per pull request |
| Automatic-merge policy | Branch protection and merge automation | Organization configuration |
Expand Down
15 changes: 5 additions & 10 deletions src/docs/Capabilities/dependency-updates/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,18 +66,13 @@ Management](../release-management/spec.md).
- **FR8 — Freshly published versions wait.** A version MUST NOT be proposed the moment it appears. A cooldown between publication and proposal lets an upstream project withdraw or supersede a bad release before every consumer has a pull request open against it.
- **FR9 — Security advisories bypass the schedule.** An advisory affecting a pin raises an update on disclosure, out of band, and MUST be prioritised over scheduled currency updates.

### Batching

- **FR10 — Low-risk updates MAY be grouped; breaking ones MUST NOT be.** Minor and patch updates within one ecosystem MAY share a pull request, because reviewing twelve patch bumps separately costs twelve reviews and yields no more information than one. A major update MUST be isolated, because it is the update whose diff has to be read.
- **FR11 — Grouping never crosses ecosystems.** A group's review requires knowing one ecosystem's conventions; mixing ecosystems in one pull request means no single reviewer is qualified for the whole diff.

### Review and labelling

- **FR12 — One reviewed pull request per update or group.** Each update is a pull request that passes the full check suite before merge. Nothing is applied unreviewed, and no update takes a side channel around the gate.
- **FR13 — Update level is labelled.** Every update pull request MUST carry the category, the ecosystem, and the dependency's own version-change level, so review routing and triage do not require opening the diff.
- **FR14 — Update labels MUST NOT reuse the release bump vocabulary.** The label that signals the *dependency's* version level MUST be namespaced away from the release-bump labels ([automation labels](../../Ways-of-Working/Automation-Labels.md#every-set-is-namespaced)). A dependency update is artifact-affecting and therefore produces a release; one shared vocabulary across the two dimensions would set this repository's version from the upstream project's decision.
- **FR15 — Review posture follows update level.** Patch and minor updates MAY merge automatically once every required check passes. A major update MUST require human review and MUST NOT merge automatically. A repository MAY tighten this and MUST NOT loosen it.
- **FR16 — Automatic merge is never a bypass.** Where an update merges without review, it does so because the checks passed, not because the checks were skipped.
- **FR10 — One reviewed pull request per update.** Each dependency update is a pull request that passes the full check suite before merge. Nothing is applied unreviewed, and no update takes a side channel around the gate.
- **FR11 — Update level is labelled.** Every update pull request MUST carry the category, the ecosystem, and the dependency's own version-change level, so review routing and triage do not require opening the diff.
- **FR12 — Update labels MUST NOT reuse the release bump vocabulary.** The label that signals the *dependency's* version level MUST be namespaced away from the release-bump labels ([automation labels](../../Ways-of-Working/Automation-Labels.md#every-set-is-namespaced)). A dependency update is artifact-affecting and therefore produces a release; one shared vocabulary across the two dimensions would set this repository's version from the upstream project's decision.
- **FR13 — Review posture follows update level.** Patch and minor updates MAY merge automatically once every required check passes. A major update MUST require human review and MUST NOT merge automatically. A repository MAY tighten this and MUST NOT loosen it.
- **FR14 — Automatic merge is never a bypass.** Where an update merges without review, it does so because the checks passed, not because the checks were skipped.

### Non-functional

Expand Down
6 changes: 2 additions & 4 deletions src/docs/Coding-Standards/GitHub-Actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,9 +53,7 @@ stale, unpatched code.
- **Enable automated updates for the `github-actions` ecosystem** in
`.github/dependabot.yml`. The updater opens a pull request that rewrites the
pin to the new commit SHA and refreshes the trailing version comment.
- **Apply a cooldown** before adopting a freshly published version, and
**group** low-risk action bumps so routine updates arrive as one reviewable
pull request rather than many.
- **Apply a cooldown** before adopting a freshly published version.
- **Label the update PR** with `dependencies` + `github-actions`, plus the
dependency's own level (`update:major` / `update:minor` / `update:patch`).
These update-level labels are deliberately **distinct from the release-bump
Expand All @@ -65,7 +63,7 @@ stale, unpatched code.
- **Review `update:major` by hand** — a major action bump can change inputs,
outputs, or behaviour. Lower levels may auto-merge once checks pass.

The full mechanism — schedule, grouping, labels, and auto-merge policy — is the
The full mechanism — schedule, cooldown, labels, and auto-merge policy — is the
[Dependency Updates](../Capabilities/dependency-updates/design.md) capability;
this section is the Actions-specific view of it.

Expand Down
Loading