werkator/docs/prs/2026-09-11-PR#52-version-per-pull-request.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

The version was bumped per deployment, not per pull request — build.gradle.kts said so in as many words: "bump at least the patch version for every deployment — and only then, not per commit".

It does not hold up. PR#50 and PR#51 were both merged and both deployed while calling themselves v1.8.0's predecessor, v1.7.0. The running instance reported a version that named neither of them, so the footer, --version and the release notes agreed with each other and with nothing else. A version that does not distinguish two deployments is not identifying what is running, which was the whole reason for having one.

The rule also had no home: it was stated in four places — build.gradle.kts, AGENTS.md, docs/prs/README.md and the pr-doc skill — and a new one would have had to be changed in all four to take effect.

Non-Goals

• No change to the release-notes format, the page, or ReleaseVersionConsistencyTest, which already enforces that the version and the top entry agree.
• No retroactive versions for PR#50 and PR#51: they are released together as v1.8.0 rather than invented as 1.7.1 and 1.7.2 after the fact, because neither was ever deployed under a version of its own.
• No automation of the bump. Choosing patch or minor is a judgement about what changed.

The Scenarios

Feature: a version per pull request

Background

• version in build.gradle.kts is what BuildProperties feeds to the UI footer and --version.
• The top <h2>vX.Y.Z</h2> of src/main/resources/templates/releases.html is the release-notes entry for it.
• ReleaseVersionConsistencyTest fails the build when the two disagree.

Scenario#52.01: Every PR brings its own version

So that a running instance names the change it contains.

• Given a pull request that changes behaviour or fixes a defect
• When it is prepared for merging
• Then it bumps version — patch for a fix, minor for new behaviour
  • and adds its own entry at the top of the release notes
  • and the build fails if the two disagree

Verified by

• ReleaseVersionConsistencyTest "the top release-notes entry names the current project version"

Scenario#52.02: The rule reads the same wherever it is stated

So that the next change does not follow a copy that was left behind.

• Given the four places that state when the version is bumped
• When any of them is read
• Then all four say per pull request, patch for a fix and minor for new behaviour

The Solution

version goes to 1.8.0 — minor, because the highest-significance change it now carries is new behaviour: werkdock's import verb and the stale-binary rebuild of PR#50. The v1.8.0 release-notes entry covers PR#50 and PR#51 together and says, in its last bullet, that this is the last release assembled that way.

The comment above version is rewritten to the new rule and names the failure that produced it, so the reason survives next to the line it governs. AGENTS.md, docs/prs/README.md and the pr-doc skill get the same sentence. The pure-release exception stays: a PR of nothing but a bump and its notes still needs no PR-doc — it is now the rare case rather than the normal one.

Open Questions

• Nothing enforces that a PR bumped anything; only the consistency of version and notes is enforced. A check comparing the version against origin/main would be possible and is deliberately not added here — it would fail every branch that is merely out of date.

Additional Changes

• None.

Prerequisite PRs

• PR#50 and PR#51 — this PR releases them.