Pin contributor uv version to CI and document deliberate uv upgrades

[Copilot]

uv.lock was being rewritten by contributors using a newer uv than CI, causing large non-semantic lockfile diffs and avoidable merge/review churn. This makes the required uv version part of the project, so that it is enforced where the damage is done rather than caught in review.

Note (updated after review): this PR pins uv to 0.12.7, not to CI's previous 0.10.9. That is a deliberate upgrade — 0.10.9 is from March and two minor releases behind, and pinning it would have frozen every contributor, plugin developer, self-hoster and CI job to it. All uv pins move together to 0.12.7 here.

What it does

• Enforce the version at the source (pyproject.toml):

  [tool.uv]
  required-version = "==0.12.7"

  uv then refuses to run on a mismatch, with an actionable message.

• Pin every place uv runs, since required-version gates every uv invocation and not just uv lock:

  • the version input of astral-sh/setup-uv in lint-and-test.yml, docker-build.yml, docker-qa.yml, pypi-publish.yml and actions/setup-test-env/action.yml
  • ARG UV_VERSION in the Dockerfile (it used the floating 0.10 image tag, which now ships a different patch release)
  • the asdf commands in .readthedocs.yaml (they installed 0.10.3)

• Regenerate uv.lock with the pinned uv, in its own commit. 0.12.7 writes markers in a more compact canonical form, so the first write under the new pin reformats the file. Doing it here means it does not land on top of the next real dependency change — which is exactly the churn Pin uv for contributors too, and make upgrading it a deliberate step #2449 is about. No package is added, removed or re-versioned in that commit: git show ee9c2ea68 -- uv.lock | grep -E '^[+-](name|version) = ' is empty.

• Run pre-commit without tox-dev/action-pre-commit-uv. That action runs pre-commit as uv run --with pre-commit-uv ..., and pre-commit-uv depends on uv>=0.9.1, so the overlay environment put the latest uv ahead of the pinned one on PATH — where our entry: uv run black hooks picked it up. All our hooks are language: system, so it had no hook environments to speed up anyway. pre-commit itself now comes from the locked dev group, so CI does not follow its latest release either.

• Document it: dependency-management.rst lists every place the version is pinned so a bump moves them together, notes that uv self update is unavailable for pip/brew installs, and the deploy guide notes that servers running uv sync --frozen need the pinned version too.

Trade-off to be aware of

The pin reaches beyond contributors: anyone running uv in a FlexMeasures checkout needs that exact version, including plugin developers and self-hosters following automated-deploy-via-GHActions.rst. The changelog entry says so. A range like >=0.12,<0.13 would be softer, but lets patch-level marker churn back in, which is the thing being prevented.

• Fixes Pin uv for contributors too, and make upgrading it a deliberate step #2449

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #34318397 | 📁 Comparing 1a6afff against latest (c33bc71)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

• changelog.html
• api/v3_0.html
• dev/automated-deploy-via-GHActions.html
• dev/dependency-management.html
• dev/setup-and-guidelines.html

[Copilot]

Pull request overview

Aligns contributor tooling with CI by pinning an exact uv version at the source (pyproject.toml) and documenting the workflow for deliberate uv upgrades, reducing noisy/non-semantic uv.lock diffs.

Changes:

• Enforce an exact uv version via [tool.uv].required-version and update Docker/RTD/CI to match
• Update contributor and dependency-management docs to explain the pin and how to upgrade uv deliberately
• Add a changelog entry describing the new uv pinning behavior for reproducible lockfile output

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Enforces exact uv version via [tool.uv].required-version
documentation/dev/setup-and-guidelines.rst	Adds contributor guidance to pin uv locally
documentation/dev/dependency-management.rst	Documents the enforced uv version and the coordinated upgrade procedure
documentation/dev/automated-deploy-via-GHActions.rst	Notes server-side uv must match the pinned version
documentation/changelog.rst	Adds Infrastructure / Support changelog entry for uv pinning
Dockerfile	Pins the uv base image tag to the exact required version
.readthedocs.yaml	Pins uv version in Read the Docs build environment
.github/workflows/lint-and-test.yml	Runs pre-commit without action-pre-commit-uv to avoid overriding the pinned uv

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Flix6x]

Reviewed and pushed corrections. Two things worth deciding on explicitly before merge.

1. The pin reaches further than contributors. [tool.uv].required-version gates every uv invocation in a checkout, not just uv lock — I verified that uv venv, uv pip list and uv sync all refuse to run on a mismatch. So it applies to:

• contributors (the intent),
• plugin developers who clone FlexMeasures and use uv in it,
• self-hosters: the deploy hook in documentation/dev/automated-deploy-via-GHActions.rst runs uv sync --frozen in a checkout, so those servers need the pinned version too (there is now a note in that doc),
• every build surface: the Docker image, Read the Docs, and all five astral-sh/setup-uv pins.

The issue framed the strict-vs-range trade-off around lockfile writers only. It is wider than that, so the changelog entry now says so. If that reach is unwanted, >=0.12,<0.13 would still stop the big jumps while letting patch releases through — but then patch-level marker churn can slip back in, which is the thing we are trying to prevent.

2. The version is now 0.12.7, not 0.10.9. 0.10.9 is from March and two minor releases behind, and pinning it would have frozen everyone above to it. uv.lock is unchanged: 0.12.7 accepts it as up to date (uv lock --check passes) and uv lock rewrites nothing, so there is no lockfile churn in this PR.

What was broken. The pin as originally proposed only covered the place the lock is written, so every build that ran a different uv failed — all four red checks had the same root cause:

Where	uv it ran	Fix
Dockerfile	floating ghcr.io/astral-sh/uv:0.10 tag, i.e. 0.10.12	ARG UV_VERSION, exact tag
.readthedocs.yaml	asdf install uv 0.10.3	bumped
lint-and-test.yml check job	0.12.7	see below
changelog	—	PR #XXXX placeholder filled in

The CI one is the subtle one: tox-dev/action-pre-commit-uv@v1 runs pre-commit as uv run --with pre-commit-uv ..., and pre-commit-uv depends on uv>=0.9.1, so the overlay environment puts the latest uv ahead of the pinned one on PATH — which is what our entry: uv run black hooks then pick up. Verified directly: with --with pre-commit-uv, uv resolves into the ephemeral cache; with plain --with pre-commit, it stays the pinned binary. All our hooks are language: system, so pre-commit-uv had no hook environments to speed up here anyway.

All checks are green now. Also documented every place the version is pinned, so a future bump moves them together, and noted that uv self update is unavailable for pip/brew installs (uv's own error message suggests it unconditionally).

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pre-commit@​4.6.2

View full report

[Flix6x]

@nhoening there seems to be a tradeoff that I'd like a second opinion on from you.

[nhoening]

If one can have multiple uv versions on a system, then I guess the inconvenience to others isn't a big problem. Can one?

Also, I'd like to know if @TeaDrinkingProgrammer has an opinion here.