# 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](https://git.javagil.de/mi/werkregie/pulls/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`](../../dashboard/build.gradle.kts), 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`](../../dashboard/build.gradle.kts), 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`](../../dashboard/build.gradle.kts), 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`](../../dashboard/build.gradle.kts), 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`](../../dashboard/build.gradle.kts), 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.