108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# 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.
|