werkregie/doc/prs/2026-10-14-PR#79-derived-version.md

PR#79: The Version Follows from the Order of the Merges

Version: minor

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.

Related Links

• werkregie PR#76, which took 0.46.1 while werkregie PR#74 was open with the same version.

Problem

Each PR raises the version in dashboard/build.gradle.kts before its merge. Two open PRs change the same line, and the second one to merge gets a conflict. Each such conflict needs the author session: rebase, find the next free version, push. When that session has ended, the PR stays stuck until a human wakes it. A CHANGELOG with an entry per version, as in werkcrappit, has the same problem at its top.

Non-Goals

• No change of werkcrappit or the other Werk repositories; each one takes the rule with its next PR.
• No Gradle plugin yet; the code moves into one when a second repository takes it.
• No change of the Werkbaum file or its conflicts.

Specification

Feature: the build derives the version and the release notes from the PR documents

Scenario#79.01: main has the base version raised by each merged PR document

… so that no two PRs change the same line for their version.

• Given the base version 0.48.0 at a commit of main, and after it the PR documents of two merges, the first with Version: minor, the second with Version: patch
• When the build of main runs
• Then the version is 0.49.1

Verified by

• build.gradle.kts, task checkReleases, part of check

Scenario#79.02: a branch has the version of main raised by its own PR document

… so that a branch build shows the version that its merge would get now.

• Given origin/main at version 0.49.1, and a branch with a PR document with Version: minor
• When the build of the branch runs
• Then the version is 0.50.0

Verified by

• build.gradle.kts, task checkReleases, part of check

Scenario#79.03: a PR document without a version line raises the patch version

… so that a PR opened before this rule still gets a version of its own.

• Given a merged PR document without a Version: line
• When the build runs
• Then that merge raises the patch version

Verified by

• build.gradle.kts, task checkReleases, part of check

Scenario#79.04: a wrong version line fails the build

… so that a typo does not give a wrong version.

• Given a PR document with Version: feature
• When the build runs
• Then it fails and names the document

Verified by

• build.gradle.kts, task checkReleases, part of check

Scenario#79.05: the changelog lists each version with its release notes

… so that a repository with release notes writes them once, in its PR document.

• Given two merged PR documents, the first with a section "Release Notes", the second without
• When the task changelog runs
• Then build/changelog/CHANGELOG.md lists the newer version first, as an internal change, and the older one with its release notes

Verified by

• build.gradle.kts, task checkReleases, part of check

Solution

• Each PR document states its raise in a line Version: major|minor|patch under its title. Its optional section "Release Notes" holds what users notice.
• dashboard/build.gradle.kts reads the PR documents that main added after the base commit, in the order of the merges. It reads them from the added lines of git log --first-parent, so that a later change of a document changes no version.
• A branch build adds the PR documents of the branch against the merge base with origin/main. Without origin/main the build fails, since a branch would otherwise miss what main added and get a version too low.
• The task changelog writes build/changelog/CHANGELOG.md, newest version first.
• checkReleases checks the derivation against a git repository in a temporary directory.
• The shared workflow, doc/prs/README.md and the template state the new rule.

Open Questions

None.