Add the Maven plugin to Get started

dev.openjavaformat:fmt-maven-plugin 2.27.0.1 is on Maven Central: our
fork of spotify/fmt-maven-plugin, released from
openjavaformat/fmt-maven-plugin. The new page adds it to a build with the
format goal, checks formatting in CI with the check goal and runs either
goal from the command line. Every snippet was run against the published
2.27.0.1 with open-java-format 2.98.0.4: the plugin's output is
byte-identical to the command line's, check fails on an unformatted file
and passes after format, and a build without the open-java-format
dependency stops with the message that names it.

The plugin has version numbers of its own, so zensical.toml gets
maven_plugin_version next to ojf_version, to bump on each plugin
release. The overview gets a card and names that version. Spotless and
Migrate now point Maven builds at the plugin instead of saying Maven has
no way, and About lists the plugin among the Maven Central artifacts,
with its own repository and release workflow.

Author: abashev

docs/about.md

@@ -9,14 +9,15 @@ project exists is in the [manifesto](manifesto.md).
 
 | Where | What |
 | --- | --- |
-| [Maven Central](https://central.sonatype.com/namespace/dev.openjavaformat) | `dev.openjavaformat:open-java-format`, with `-spi`, `-native` and `-jdk-bootstrap` |
+| [Maven Central](https://central.sonatype.com/namespace/dev.openjavaformat) | `dev.openjavaformat:open-java-format`, with `-spi`, `-native` and `-jdk-bootstrap`, and the Maven plugin `dev.openjavaformat:fmt-maven-plugin` |
 | [Gradle Plugin Portal](https://plugins.gradle.org/plugin/dev.openjavaformat.java-format) | `dev.openjavaformat.java-format` |
 | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/34359-open-java-format) | the IntelliJ IDEA plugin |
 | [GitHub Releases](https://github.com/openjavaformat/open-java-format/releases/latest) | native binaries, the runnable jar, the Gradle, IntelliJ IDEA and Eclipse plugins |
 
 The Maven Central artifacts, the Gradle plugins and the files of a GitHub release are built by the
 [release workflow](https://github.com/openjavaformat/open-java-format/blob/main/.github/workflows/release.yml)
-from the tag of the version.
+from the tag of the version. The Maven plugin has a repository and a release workflow of its own,
+[openjavaformat/fmt-maven-plugin](https://github.com/openjavaformat/fmt-maven-plugin).
 
 ## Verify a download
 

docs/get-started/index.md

@@ -6,7 +6,8 @@ the same formatter, so they all produce the same files. Set up the ones your pro
 !!! info "Requirements"
 
     The current version is **{{ ojf_version }}**. Everything except the native binaries needs Java 21 or
-    later, and the Gradle plugin needs Gradle 9.
+    later, and the Gradle plugin needs Gradle 9. The Maven plugin has version numbers of its own; the
+    current one is **{{ maven_plugin_version }}**.
 
 <div class="grid cards" markdown>
 
@@ -23,6 +24,12 @@ the same formatter, so they all produce the same files. Set up the ones your pro
 
     Works with Gradle through our plugin. Maven waits for a pull request in Spotless.
 
+-   :simple-apachemaven:{ .lg .middle } __[Maven plugin](maven.md)__
+
+    ---
+
+    Formats the sources in every build, or fails the build in CI when they are not formatted.
+
 -   :lucide-terminal:{ .lg .middle } __[Command line](command-line.md)__
 
     ---

docs/get-started/maven.md

@@ -0,0 +1,68 @@
+# Maven plugin
+
+The plugin formats the Java sources of a Maven build, or fails the build when they are not
+formatted. Maven has to run on Java 21 or later.
+
+## Add the plugin
+
+``` xml title="pom.xml"
+<build>
+    <plugins>
+        <plugin>
+            <groupId>dev.openjavaformat</groupId>
+            <artifactId>fmt-maven-plugin</artifactId>
+            <version>{{ maven_plugin_version }}</version>
+            <executions>
+                <execution>
+                    <goals>
+                        <goal>format</goal>
+                    </goals>
+                </execution>
+            </executions>
+            <dependencies>
+                <dependency>
+                    <groupId>dev.openjavaformat</groupId>
+                    <artifactId>open-java-format</artifactId>
+                    <version>{{ ojf_version }}</version>
+                </dependency>
+            </dependencies>
+        </plugin>
+    </plugins>
+</build>
+```
+
+The `format` goal runs in the `process-sources` phase, so `mvn compile`, `mvn test` and every later
+phase format `src/main/java` and `src/test/java` first.
+
+The dependency is not optional. The plugin does not bring a formatter of its own: it runs the
+open-java-format version named there, and without it the build stops with a message that says what
+to add. Name the same version as in your IDE and your other builds.
+
+## Check in CI
+
+Use the `check` goal instead of `format`. It changes no file, and in the `verify` phase it fails the
+build when a file is not formatted:
+
+``` text title="mvn verify"
+[ERROR] Found 1 non-complying files, failing build
+[ERROR] To fix formatting errors, run "mvn dev.openjavaformat:fmt-maven-plugin:format"
+```
+
+## Run a goal from the command line
+
+``` sh
+mvn dev.openjavaformat:fmt-maven-plugin:format
+mvn dev.openjavaformat:fmt-maven-plugin:check
+```
+
+The plugin still has to be in the `pom.xml` with its dependency: Maven reads the dependencies of a
+plugin from the POM, never from the command line.
+
+## Options
+
+The plugin is a fork of [spotify/fmt-maven-plugin](https://github.com/spotify/fmt-maven-plugin) with
+open-java-format in place of google-java-format. Its options, such as extra source directories, file
+name patterns and skipping a directory, are listed in
+[its README](https://github.com/openjavaformat/fmt-maven-plugin#options). There is nothing to set for
+the formatting itself: imports are always sorted and cleaned up, and long strings are always
+reflowed, as on every other route.

docs/get-started/spotless.md

@@ -65,7 +65,7 @@ org.gradle.jvmargs=--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAME
 
 The Maven plugin of Spotless has no step for open-java-format. Its `palantirJavaFormat` step always
 downloads `com.palantir.javaformat:palantir-java-format`, and it cannot be pointed at another
-artifact.
+artifact. Until that changes, a Maven build formats with our [Maven plugin](maven.md).
 
 The pull request [diffplug/spotless#3084](https://github.com/diffplug/spotless/pull/3084) adds an
 `openJavaFormat` step to both Spotless plugins, for Gradle and for Maven:

docs/migrate.md

@@ -96,7 +96,8 @@ In a `pom.xml` it is the same change of `groupId`, `artifactId` and `version`.
 ### Spotless
 
 With Gradle, remove `palantirJavaFormat()` from the `spotless` block and apply our plugin, which adds
-its own step. Maven has no way yet. [Spotless](get-started/spotless.md) has both.
+its own step. With Maven, Spotless has no step for open-java-format yet: remove `palantirJavaFormat`
+and add our [Maven plugin](get-started/maven.md). [Spotless](get-started/spotless.md) has both.
 
 ### IntelliJ IDEA
 

zensical.toml

@@ -20,6 +20,7 @@ nav = [
     "get-started/index.md",
     { "Gradle plugin" = "get-started/gradle.md" },
     { "Spotless" = "get-started/spotless.md" },
+    { "Maven plugin" = "get-started/maven.md" },
     { "Command line" = "get-started/command-line.md" },
     { "IntelliJ IDEA" = "get-started/intellij-idea.md" },
     { "Eclipse" = "get-started/eclipse.md" },
@@ -106,6 +107,9 @@ toggle.name = "Switch to system preference"
 # extra.version: the theme reads that one as the switch for a version selector.
 [project.extra]
 ojf_version = "2.98.0.4"
+# The Maven plugin is released from its own repository, openjavaformat/fmt-maven-plugin, with version
+# numbers of its own. Bump it on each release of the plugin.
+maven_plugin_version = "2.27.0.1"
 
 # Renders every page as a Jinja template, for {{ ojf_version }}. A misspelt variable or a stray {{
 # fails the build instead of leaving a gap or the raw text on the site.