Number versions after the Java version (#140)

* Number versions after the Java version, not after palantir's

Up to 2.98.0.6 the version was palantir-java-format's with a build
number appended. The bug fixes made the output differ from upstream, so
following its numbers lost its meaning. From here a version is
<java>.<minor>.<build>: the Java version the formatter is built for,
then a number that moves with every change to the output, then one that
moves with builds that leave the output alone.

The README gets a Versions section that says so, and the palantir
section stops promising a 2.x line and changes waiting for 3.0.

* Run CI on the release-line branches

The default branch is 21.X.X now, and a release line is named after the
Java version it is built for, so the workflows that watched main alone
also take '*.X.X': CI, CodeQL, the dependency graph, the SHA-pinning and
zizmor checks. The PR updater follows 21.X.X, the base of every pull
request, and dependabot loses its target-branch so that it opens its
pull requests against the default branch, whichever line that is.

Releases need nothing: release.yml runs on a tag, and JReleaser never
compares the branch.

* Watch the release lines only

main is the old line and gets nothing new, so the workflows stop
watching it: CI, CodeQL, the dependency graph, the SHA-pinning and
zizmor checks run on '*.X.X' alone. dependabot names 21.X.X outright
instead of following the default branch, and moves when the next line
starts.

* Say what the third number is for

It is not a build counter but the number of fixes that leave the output
alone: a crash, a regression, an internal bug, a dependency update. The
line between it and the second number is the output, not the kind of
change: a fix that changes the output raises the second, a fix that does
not raises the third.

Author: abashev

.github/dependabot.yml

@@ -1,19 +1,21 @@
 version: 2
 # A release is proposed only once it is a week old: a compromised or broken release is usually pulled
 # within days. The cooldown holds back version updates only; security updates still come at once.
+#
+# target-branch names the current release line; it moves when the next line starts.
 updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
-    target-branch: "main"
+    target-branch: "21.X.X"
     cooldown:
       default-days: 7
 
   - package-ecosystem: "gradle"
     directory: "/"
     schedule:
       interval: "weekly"
-    target-branch: "main"
+    target-branch: "21.X.X"
     cooldown:
       default-days: 7

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: CI
 on:
   push:
     branches:
-      - main
+      - '*.X.X' # a release line is named after the Java version it is built for: 21.X.X
   pull_request:
 
 permissions:
@@ -48,7 +48,7 @@ jobs:
   # jobs and nothing they build is kept. The code is still compiled for Java 21 by JDK 21, as in the
   # release; -PjavaRuntime moves only the test JVMs, and with them the javac whose internals the
   # formatter parses with. The IntelliJ plugin's tests stay on the runtime of the IDE they start.
-  # JDK 21 itself is `build`, the check the main branch requires.
+  # JDK 21 itself is `build`, the check the default branch requires.
   jdk:
     name: build (JDK ${{ matrix.jdk }})
     runs-on: ubuntu-latest

.github/workflows/codeql-analysis.yml

@@ -2,9 +2,9 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ 'main' ]
+    branches: [ '*.X.X' ]
   pull_request:
-    branches: [ 'main' ]
+    branches: [ '*.X.X' ]
   schedule:
     - cron: '33 9 * * 6'
 

.github/workflows/dependency-submission.yml

@@ -2,7 +2,7 @@ name: Submit dependency graph
 
 on:
   push:
-    branches: [ 'main' ]
+    branches: [ '*.X.X' ]
 
 permissions:
   contents: write

.github/workflows/sha-pinning-check.yml

@@ -2,9 +2,9 @@ name: Ensure SHA-pinned actions
 
 on:
   pull_request:
-    branches: [ 'main' ]
+    branches: [ '*.X.X' ]
   push:
-    branches: [ 'main' ]
+    branches: [ '*.X.X' ]
 
 permissions:
   contents: read

.github/workflows/update-pr-branch.yml

@@ -2,7 +2,7 @@ name: Update PR branches
 
 on:
   push:
-    branches: [ 'main' ]
+    branches: [ '21.X.X' ] # the default branch, the base of every pull request
   schedule:
     # Run every hour to catch stuck PRs
     - cron: '0 * * * *'
@@ -18,6 +18,6 @@ jobs:
       - uses: adRise/update-pr-branch@e96e796f4ab23ab388016fdaed7092de99bd71cf # v0.11.1
         with:
           token: ${{ secrets.BOT_PAT }}
-          base: 'main'
+          base: '21.X.X'
           required_approval_count: 1
           require_passed_checks: true

.github/workflows/zizmor.yml

@@ -2,7 +2,7 @@ name: GitHub Actions Security Analysis with zizmor 🌈
 
 on:
   push:
-    branches: ["main"]
+    branches: ["*.X.X"]
   pull_request:
     branches: ["**"]
 

README.md

@@ -85,16 +85,14 @@ private static void configureResolvedVersionsWithVersionMapping(Project project)
 
 ## Coming from palantir-java-format
 
-- **Same output, except for bug fixes.** 2.98.0.x is the code of palantir-java-format 2.98.0, renamed
-  and rebuilt in the open. Its output is the same except where it fixes a bug, and
-  [Migrate](https://openjavaformat.dev/migrate/) lists those fixes. The fourth number counts builds of
-  an upstream version.
-- **Identical Java packages.** `com.palantir.javaformat.*` stays for the whole 2.x line, so your code
-  and the SPI keep working.
+- **Same output, except for bug fixes.** The formatter is the code of palantir-java-format 2.98.0,
+  renamed and rebuilt in the open. Its output is the same except where it fixes a bug, and
+  [Migrate](https://openjavaformat.dev/migrate/) lists those fixes. Any later change to the output
+  comes with a new minor version, see [Versions](#versions).
+- **Identical Java packages.** `com.palantir.javaformat.*` stays, so your code and the SPI keep
+  working.
 - **One-line migration.** Change the coordinates below. Nothing else.
 
-Other changes to the formatter's output wait for 3.0.
-
 | | palantir-java-format | open-java-format |
 |---|---|---|
 | Maven group | `com.palantir.javaformat` | `dev.openjavaformat` |
@@ -109,8 +107,25 @@ Other changes to the formatter's output wait for 3.0.
 | CLI style flag | `--palantir`, `-palantir` | none: there is one style |
 | Formatter style | `PALANTIR` | `OJF` |
 | Native formatter Gradle property | `palantir.native.formatter` | `openjavaformat.native.formatter` |
-| Java packages | `com.palantir.javaformat.*` | **unchanged in 2.x** |
-| Version numbers | `2.98.0` | `2.98.0.1` |
+| Java packages | `com.palantir.javaformat.*` | **unchanged** |
+| Version numbers | `2.98.0` | `21.<minor>.<build>`, see [Versions](#versions) |
+
+## Versions
+
+A version is three numbers, `<java>.<minor>.<build>`, and each one answers a question of its own.
+
+- **The first is the Java version the formatter is built for**, 21 today. It moves when the minimum
+  Java version moves.
+- **The second moves with every change to the output**: a fix in wrapping or alignment, a new rule,
+  a new feature. A newer minor version can reformat code that the previous one left alone.
+- **The third moves with fixes that leave the output alone**: a crash, a regression, an internal
+  bug, a dependency update. A newer build formats every file exactly as the previous one did.
+
+The line between the last two numbers is the output, not the kind of change: a fix that changes
+the output raises the second number, a fix that does not raises the third.
+
+Up to 2.98.0.6 the version was palantir-java-format's with a build number appended. Once the bug
+fixes made the output differ from upstream, that numbering lost its meaning.
 
 ## Building and testing locally