From e03cb76d4f50d214a6bbc3530237cc683b920de7 Mon Sep 17 00:00:00 2001 From: Robin Bowes Date: Wed, 14 Oct 2026 22:43:42 +0100 Subject: [PATCH] docs: record decision to accept uv.lock revision flapping Dependabot's bundled uv 0.12.18 writes lock revision 3; the release lockfile sync uses uv 0.12.22+ and writes revision 5. Accept the flip until dependabot-core ships a newer uv. Co-Authored-By: Claude Opus 5.5 --- .../2026-10-14-uv-lock-revision-flapping.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 decisions/2026-10-14-uv-lock-revision-flapping.md diff --git a/decisions/2026-10-14-uv-lock-revision-flapping.md b/decisions/2026-10-14-uv-lock-revision-flapping.md new file mode 100644 index 0000000..f899523 --- /dev/null +++ b/decisions/2026-10-14-uv-lock-revision-flapping.md @@ -0,0 +1,61 @@ +# uv.lock revision flapping + +## Decision: accept the `revision` flip in `uv.lock` until Dependabot ships uv 0.12.22+ + +Dependabot PRs set `uv.lock` to `revision = 3`; Release PRs set it back to +`revision = 5`. Merge both as they come. A `revision` line change in either is +expected and is not a reason to hold a PR or push a relock commit to it. + +## Context: why it came up + +Reviewing #60 and #64 (2026-10-14) showed both downgrading `revision = 5` to +`3`. The history shows the same flip in #36, #45 and #53. + +- uv 0.12.22 moved the lock format to revision 5. Re-locking the same tree + with each version from 0.12.18 to 0.12.22 (version bump forced, so the lock + is rewritten) gave 3 for 0.12.18–0.12.21 and 5 for 0.12.22. +- A `uv lock` with nothing to change leaves the existing revision alone; only a + rewrite stamps the running uv's revision. A plain relock therefore looks like + a fix and is not one. +- Dependabot uses its own uv, `uv==0.12.18` in + `dependabot-core/uv/helpers/requirements.txt`, and never reads + `tool.uv.required-version`. +- The `sync-lockfile` job in `release.yaml` installs the newest uv in + `required-version` (0.12.24 on the 0.1.5 Release PR), and the version bump + forces a rewrite. + +Both revisions pass `uv sync --locked`. The cost is one unrelated line in +every Dependabot and Release PR diff. + +## Alternatives considered + +- **Raise `required-version` to `>=0.12.22`.** Rejected: Dependabot's uv + 0.12.18 would refuse to run, failing every Python Dependabot PR. +- **A CI job that relocks Dependabot branches with the project's uv.** + Rejected: it runs `uv lock`, which executes build backends, on a branch it + must then push to, so the token and the untrusted tree meet in one job. + `2026-08-28-lockfile-sync-preconditions.md` keeps those apart on purpose. + Too much exposure for a cosmetic diff. +- **Move Python updates from Dependabot to Renovate.** Renovate already runs + here for other managers. Rejected as a fix for this alone; worth revisiting + only if Dependabot is being dropped for other reasons. + +## Reasoning + +The flip is harmless and has an upstream end date: dependabot-core has open +uv bumps (#16457 to 0.12.20, #16458 to the 0.12.22 image) and bumps uv +regularly. Every local fix either breaks Dependabot or widens the release +token's exposure. + +## Trade-offs accepted + +- Dependabot and Release PRs carry a `revision` line change until upstream + catches up. +- The same thing will recur at the next uv lock-format change, whenever + Dependabot lags uv. Check this record before investigating again. +- Revisit if the flip continues after dependabot-core ships uv 0.12.22 or + later; the cause would then be something else. + +## Supersedes + +Nothing.