e07ab74082
werkator build succeeded after 01:23
The version was bumped per deployment, and build.gradle.kts said so: "bump at least the patch version for every deployment — and only then, not per commit". PR#50 and PR#51 were merged and deployed while both calling themselves v1.7.0, so the running instance reported a version that named neither of them. A version that cannot tell two deployments apart is not identifying what runs, which was the point of having one. 1.8.0 is a minor because the most significant thing it carries is new behaviour: werkdock's import verb and the stale-binary rebuild of PR#50. Its release-notes entry covers PR#50 and PR#51 together and says that this is the last release assembled that way. The rule lived in four places — build.gradle.kts, AGENTS.md, docs/prs/README.md and the pr-doc skill — so all four now say the same thing: every PR bumps the version, patch for a fix and minor for new behaviour, and brings its own release-notes entry. The comment above `version` names the failure that produced the rule, so the reason stays next to the line it governs. The pure-release exception survives as the rare case rather than the normal one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: mhoennig <michael@hoennig.de> Reviewed-on: #52
75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
> **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"](../../src/test/kotlin/de/hoennig/werkator/ReleaseVersionConsistencyTest.kt)
|
|
|
|
#### 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.
|