feat: Add versions-maven-plugin and convenient scripts

And use VERSION as generic to not have to update docs on each release.

Author: jeffjensen

README.adoc

@@ -11,9 +11,10 @@ the archetype builds the full module tree and wires up all POMs.
 mvn archetype:generate \
   -DarchetypeGroupId=io.github.jeffjensen \
   -DarchetypeArtifactId=java-service-archetype \
-  -DarchetypeVersion=1.0.0
+  -DarchetypeVersion=VERSION
 ----
 
+Replace `VERSION` with the archetype release you want to use.
 See the https://jeffjensen.github.io/java-service-archetype/[project site] for the full prompts reference, module structure, examples, and build instructions.
 
 == CI / CD

src/main/resources/META-INF/archetype-post-generate.groovy

@@ -1,4 +1,6 @@
 import java.io.File
+import java.nio.file.Files
+import java.nio.file.attribute.PosixFilePermissions
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -216,6 +218,7 @@ ${modulesXml}
     <maven-jar-plugin.version>3.4.2</maven-jar-plugin.version>
     <maven-surefire-plugin.version>3.5.5</maven-surefire-plugin.version>
     <modernizer-maven-plugin.version>3.4.0</modernizer-maven-plugin.version>
+    <versions-maven-plugin.version>2.18.0</versions-maven-plugin.version>
   </properties>
 
   <dependencyManagement>
@@ -289,6 +292,35 @@ ${dmXml}
             </execution>
           </executions>
         </plugin>
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>versions-maven-plugin</artifactId>
+          <version>\${versions-maven-plugin.version}</version>
+          <configuration>
+            <ruleSet>
+              <ignoreVersions>
+                <ignoreVersion>
+                  <type>regex</type>
+                  <version>(?i).*-(alpha|beta|m|rc)([-.]?\\d+)?</version>
+                </ignoreVersion>
+              </ignoreVersions>
+              <rules>
+                <rule>
+                  <groupId>com.graphql-java</groupId>
+                  <artifactId>graphql-java-extended-scalars</artifactId>
+                  <ignoreVersions>
+                    <!-- ignore old versions starting with 2018, 2019, 2020, 2021, 2022, or 2023 that
+                    semantically are newer than current version scheme -->
+                    <ignoreVersion>
+                      <type>regex</type>
+                      <version>^20(1[8-9]|2[0-3]).*</version>
+                    </ignoreVersion>
+                  </ignoreVersions>
+                </rule>
+              </rules>
+            </ruleSet>
+          </configuration>
+        </plugin>
       </plugins>
     </pluginManagement>
     <plugins>
@@ -306,6 +338,49 @@ writeFile(projectDir, 'parent/pom.xml', parentPom)
 // Remove the placeholder pom.xml that the archetype engine wrote at the project root
 new File(projectDir, 'pom.xml').delete()
 
+// ─── Version-update helper scripts ────────────────────────────────────────────
+// Convenience wrappers around `mvn versions:update-properties` so all property
+// versions can be bumped to their latest in one command. Written into parent/
+// (alongside parent/pom.xml, where the version properties live) for both Linux
+// (LF, +x) and Windows (CRLF). Built from explicit line lists so the line
+// endings are correct regardless of this script's own endings.
+
+writeFile(projectDir, 'parent/mvn-update-properties-versions.sh', [
+    '#!/bin/bash',
+    '# Updates property versions to the latest found',
+    'FILE=target/version-updates-applied.log',
+    'mkdir -p target',
+    'rm -f $FILE',
+    'echo "Writing output to file $FILE"',
+    'echo "Applying version updates specified as properties..."',
+    'echo "======================================== PROPERTIES" >> $FILE',
+    'mvn versions:update-properties >> $FILE',
+    '',
+].join('\n'))
+
+writeFile(projectDir, 'parent/mvn-update-properties-versions.ps1', [
+    '# Updates property versions to the latest found',
+    '$FILE = "target/version-updates-applied.log"',
+    'New-Item -ItemType Directory -Force -Path "target" | Out-Null',
+    'if (Test-Path $FILE) { Remove-Item -Force $FILE }',
+    'Write-Host "Writing output to file $FILE"',
+    'Write-Host "Applying version updates specified as properties..."',
+    '"======================================== PROPERTIES" | Out-File -FilePath $FILE -Append -Encoding utf8',
+    '& mvn versions:update-properties | Out-File -FilePath $FILE -Append -Encoding utf8',
+    '',
+].join('\r\n'))
+
+// Set the exec bit on the Linux script. POSIX filesystems only; on Windows
+// (non-POSIX) this throws UnsupportedOperationException and we fall back to the
+// best-effort Java executable flag (a no-op on Windows, but harmless).
+def shFile = new File(projectDir, 'parent/mvn-update-properties-versions.sh')
+try {
+    Files.setPosixFilePermissions(shFile.toPath(),
+        PosixFilePermissions.fromString('rwxr-xr-x'))
+} catch (UnsupportedOperationException ignored) {
+    shFile.setExecutable(true, false)
+}
+
 // ─── common-domain ────────────────────────────────────────────────────────────
 
 writeFile(projectDir, 'common-domain/pom.xml',

src/site/asciidoc/index.adoc

@@ -14,9 +14,11 @@ the archetype builds the full module tree and wires up all POMs.
 mvn archetype:generate \
   -DarchetypeGroupId=io.github.jeffjensen \
   -DarchetypeArtifactId=java-service-archetype \
-  -DarchetypeVersion=1.0.0
+  -DarchetypeVersion=VERSION
 ----
 
+Replace `VERSION` with the archetype release you want to use.
+
 Maven prompts for standard coordinates (`groupId`, `artifactId`, `version`, `package`)
 followed by three archetype-specific properties.
 See link:usage.html[Usage] for the full prompts reference.

src/site/asciidoc/modules.adoc

@@ -92,8 +92,9 @@ It contains:
 * `<dependencyManagement>` — all modules pinned to `${project.version}`, sorted alphabetically by `artifactId`
 * Common properties: Java 21 via `maven.compiler.release`; UTF-8 source encoding
 * `<pluginManagement>` — pinned versions for `maven-compiler-plugin`, `maven-failsafe-plugin`,
-  `maven-jar-plugin` (with `skipIfEmpty=true`), `maven-surefire-plugin`, and
-  `modernizer-maven-plugin` (bound to `verify`, `javaVersion` = `${java.version}`)
+  `maven-jar-plugin` (with `skipIfEmpty=true`), `maven-surefire-plugin`,
+  `modernizer-maven-plugin` (bound to `verify`, `javaVersion` = `${java.version}`), and
+  `versions-maven-plugin` (rule set ignores alpha/beta/milestone/RC versions)
 * `<plugins>` — activates `modernizer-maven-plugin` so every module is checked for outdated API usage during `verify`
 
 To build a generated project:
@@ -106,6 +107,33 @@ mvn verify
 
 Use `mvn install` instead if other local projects need to consume the generated modules from your local Maven repository.
 
+=== Updating dependency and plugin versions
+
+`parent/` also contains two convenience scripts that wrap `mvn versions:update-properties`,
+bumping every dependency and plugin version property in `parent/pom.xml` to its latest stable
+release in a single command:
+
+[cols="1,2"]
+|===
+|Script |Platform
+
+|`mvn-update-properties-versions.sh`  |Linux / macOS
+|`mvn-update-properties-versions.ps1` |Windows (PowerShell)
+|===
+
+Run the applicable script from `parent/` immediately after generating the project to pick up
+the newest versions before your first build:
+
+[source,bash]
+----
+cd my-service/parent
+./mvn-update-properties-versions.sh
+----
+
+The full plugin output is written to `parent/target/version-updates-applied.log`.
+Pre-release versions (alpha, beta, milestone, RC) are skipped by the `versions-maven-plugin`
+rule set, so only stable releases are applied.
+
 == Package Reference
 
 All type and name segments in package names are lowercased.

src/site/asciidoc/requirements.adoc

@@ -59,10 +59,15 @@ Do not create a `pom.xml` at the project root.
   `project.build.sourceEncoding`.
 * `<pluginManagement>` — declare pinned versions for `maven-compiler-plugin`,
   `maven-failsafe-plugin`, `maven-jar-plugin` (configured with `skipIfEmpty=true`),
-  `maven-surefire-plugin`, and `modernizer-maven-plugin` (bound to the `verify`
-  phase with `javaVersion` set to `${java.version}`).
+  `maven-surefire-plugin`, `modernizer-maven-plugin` (bound to the `verify`
+  phase with `javaVersion` set to `${java.version}`), and `versions-maven-plugin`
+  (rule set ignores alpha/beta/milestone/RC versions).
 * `<plugins>` — activate `modernizer-maven-plugin` so every module is checked for
   outdated API usage during `verify`.
+* Generate two convenience scripts in `parent/` — `mvn-update-properties-versions.sh`
+  (Linux/macOS, LF line endings, executable bit set) and `mvn-update-properties-versions.ps1`
+  (Windows, CRLF line endings) — that wrap `mvn versions:update-properties` to bump every
+  dependency and plugin version property to its latest stable release.
 
 === Child module POMs
 

src/site/asciidoc/usage.adoc

@@ -10,9 +10,11 @@
 mvn archetype:generate \
   -DarchetypeGroupId=io.github.jeffjensen \
   -DarchetypeArtifactId=java-service-archetype \
-  -DarchetypeVersion=1.0.0
+  -DarchetypeVersion=VERSION
 ----
 
+Replace `VERSION` with the archetype release you want to use.
+
 Maven first prompts for the standard Maven coordinates:
 
 [cols="1,2"]
@@ -133,7 +135,7 @@ Uses the same values as the full multi-service example above.
 mvn archetype:generate -B \
   -DarchetypeGroupId=io.github.jeffjensen \
   -DarchetypeArtifactId=java-service-archetype \
-  -DarchetypeVersion=1.0.0 \
+  -DarchetypeVersion=VERSION \
   -DgroupId=com.example \
   -DartifactId=my-service \
   -Dversion=1.0.0-SNAPSHOT \

src/test/resources/projects/basic/verify.groovy

@@ -76,6 +76,13 @@ assert pmBlock.contains('<version>${modernizer-maven-plugin.version}</version>')
 assert pmBlock.contains('<javaVersion>${java.version}</javaVersion>')        : 'modernizer must configure javaVersion'
 assert pmBlock.contains('<goal>modernizer</goal>')                          : 'modernizer pluginManagement must bind the modernizer goal'
 
+// versions-maven-plugin: pinned and managed in pluginManagement with the update ruleSet
+assert parentPom.contains('<versions-maven-plugin.version>2.18.0</versions-maven-plugin.version>') \
+    : 'parent must pin versions-maven-plugin version'
+assert pmBlock.contains('<artifactId>versions-maven-plugin</artifactId>')         : 'versions-maven-plugin must be declared in pluginManagement'
+assert pmBlock.contains('<version>${versions-maven-plugin.version}</version>')     : 'versions-maven-plugin pluginManagement must reference the version property'
+assert pmBlock.contains('<artifactId>graphql-java-extended-scalars</artifactId>') : 'versions-maven-plugin must configure the graphql-java-extended-scalars rule'
+
 // the active <plugins> section is what remains of <build> after removing <pluginManagement>
 def buildBlock    = (parentPom =~ /(?s)<build>.*<\/build>/)[0]
 def activePlugins = buildBlock.replaceAll(/(?s)<pluginManagement>.*<\/pluginManagement>/, '')
@@ -215,5 +222,22 @@ modules.findAll { it.startsWith('integration-') }.each { m ->
         : "${m} must configure maven-failsafe-plugin"
 }
 
+// ── Version-update helper scripts in parent/ ──────────────────────────────────
+// They live alongside parent/pom.xml, where the version properties are defined.
+// The .sh exec bit is POSIX-only and cannot be set when generating on Windows,
+// so it is intentionally not asserted here.
+
+check('parent/mvn-update-properties-versions.sh')
+check('parent/mvn-update-properties-versions.ps1')
+
+def shScript = text('parent/mvn-update-properties-versions.sh')
+assert shScript.startsWith('#!/bin/bash')                     : 'bash script must start with the bash shebang'
+assert shScript.contains('mvn versions:update-properties')    : 'bash script must run mvn versions:update-properties'
+assert !shScript.contains('\r')                               : 'bash script must use LF line endings (no CR)'
+
+def psScript = text('parent/mvn-update-properties-versions.ps1')
+assert psScript.contains('mvn versions:update-properties')      : 'PowerShell script must run mvn versions:update-properties'
+assert psScript.contains('\r\n')                               : 'PowerShell script must use CRLF line endings'
+
 _buildLog.append("\n=== PASSED ===\n")
 true