This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-invoker-plugin.git


The following commit(s) were added to refs/heads/master by this push:
     new eb7785b  Refresh the site and README ahead of 3.11.0
eb7785b is described below

commit eb7785bfe180f15f5723be34d2de305100f8ca3c
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 18 01:06:48 2026 +0000

    Refresh the site and README ahead of 3.11.0
---
 README.md                                          | 108 ++++++++-------------
 .../markdown/examples/access-test-classes.md.vm    |   2 +-
 src/site/markdown/examples/clone-projects.md.vm    |   2 +-
 src/site/markdown/examples/fast-use.md.vm          |  12 +--
 src/site/markdown/examples/filtering.md.vm         |  14 +--
 src/site/markdown/examples/invoker-properties.md   |  27 ++++--
 .../markdown/examples/logs-for-failed-tests.md.vm  |   4 +-
 .../examples/parallel-projects-execution.md.vm     |  14 +--
 .../markdown/examples/pre-post-build-script.md.vm  |  38 +++++---
 src/site/markdown/examples/prepare-build-env.md.vm |   4 +-
 src/site/markdown/examples/selector-conditions.md  |  32 ++++--
 src/site/markdown/examples/selector-scripts.md.vm  |  10 +-
 src/site/markdown/examples/skipping.md.vm          |   4 +-
 src/site/markdown/faq.md                           |  12 +--
 src/site/markdown/groovy-version.md.vm             |  18 ++--
 src/site/markdown/index.md                         |  47 +++++++--
 src/site/markdown/usage.md.vm                      |   2 +-
 17 files changed, 204 insertions(+), 146 deletions(-)

diff --git a/README.md b/README.md
index df1f3e7..32e0317 100644
--- a/README.md
+++ b/README.md
@@ -14,71 +14,47 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-Contributing to [Apache Maven Invoker 
Plugin](https://maven.apache.org/plugins/maven-invoker-plugin/)
-======================
 
-[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)][license]
-[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-invoker-plugin.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.apache.maven.plugins/maven-invoker-plugin)
+# Apache Maven Invoker Plugin
+
+[![Apache License, Version 2.0, January 
2004](https://img.shields.io/github/license/apache/maven.svg?label=License)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Maven 
Central](https://img.shields.io/maven-central/v/org.apache.maven.plugins/maven-invoker-plugin.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-invoker-plugin)
 [![Reproducible 
Builds](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/jvm-repo-rebuild/reproducible-central/master/content/org/apache/maven/plugins/maven-invoker-plugin/badge.json)](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/plugins/maven-invoker-plugin/README.md)
-[![Jenkins 
Status](https://img.shields.io/jenkins/s/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-invoker-plugin/job/master.svg?)][build]
-[![Jenkins 
tests](https://img.shields.io/jenkins/t/https/ci-maven.apache.org/job/Maven/job/maven-box/job/maven-invoker-plugin/job/master.svg?)][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss 
your changes 
-  on the [dev list][ml-list] first. 
-  This way you can make sure you're not wasting your time on something that 
isn't 
-  considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
-  + Clearly describe the issue, including steps to reproduce when it is a bug.
-  + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is 
the
-main channel of communication for contributors.  
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually 
the master branch).
-  Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
-  patches should only highlight the actual difference, not being disturbed by 
any formatting issues:
-  + Only use spaces for indentation.
-  + Create minimal diffs - disable on save actions like reformat source code 
or organize imports. 
-    If you feel the source code should be reformatted, create a separate PR 
for this change.
-  + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was 
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a 
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing 
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request 
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon 
Account](https://mastodon.social/deck/@[email protected])
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-invoker-plugin/job/master/lastCompletedBuild/testReport/
-[build]: 
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-invoker-plugin/job/master/
+[![Verify](https://github.com/apache/maven-invoker-plugin/actions/workflows/maven-verify.yml/badge.svg)](https://github.com/apache/maven-invoker-plugin/actions/workflows/maven-verify.yml)
+
+The Invoker Plugin runs a set of Maven projects and checks the result of each 
build. Maven plugins use it for their
+integration tests: each test is a small Maven project under `src/it`, and an 
optional Groovy script checks what the
+build produced. The plugin requires Maven 3.9.0 or later and Java 8 or later.
+
+- Documentation: <https://maven.apache.org/plugins/maven-invoker-plugin/>
+- Issues: <https://github.com/apache/maven-invoker-plugin/issues>
+- Mailing lists: <https://maven.apache.org/mailing-lists.html>
+
+## Build
+
+Build the plugin and run the unit tests:
+
+```shell
+mvn verify
+```
+
+Also run the integration tests in `src/it`, which use this plugin to test 
itself:
+
+```shell
+mvn -Prun-its verify
+```
+
+Run one integration test, for example `selector-scripts`:
+
+```shell
+mvn -Prun-its verify -Dinvoker.test=selector-scripts
+```
+
+The output of each integration test is in `target/it/<name>/build.log`.
+
+## Contributing
+
+Open an issue or a pull request on GitHub. Format the code with `mvn 
spotless:apply` before you push, and add a unit
+test or an integration test for a change in behavior. Write new integration 
test scripts in Groovy; BeanShell scripts
+are deprecated. See the [guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html)
+for the wider contribution process.
diff --git a/src/site/markdown/examples/access-test-classes.md.vm 
b/src/site/markdown/examples/access-test-classes.md.vm
index 141ee09..ece7a70 100644
--- a/src/site/markdown/examples/access-test-classes.md.vm
+++ b/src/site/markdown/examples/access-test-classes.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Accessing Test Classes
 
-In case your pre-/post-build scripts perform complex operations that you would 
rather like to refactor out into some utility class instead of copy&amp;pasting 
them in each script, you can use the parameter `addTestClassPath`:
+In case your pre-/post-build scripts perform complex operations that you would 
rather like to refactor out into some utility class instead of copying and 
pasting them in each script, you can use the parameter `addTestClassPath`:
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/clone-projects.md.vm 
b/src/site/markdown/examples/clone-projects.md.vm
index 701ace8..dc31592 100644
--- a/src/site/markdown/examples/clone-projects.md.vm
+++ b/src/site/markdown/examples/clone-projects.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Cloning Projects
 
-By default the projects will be executed in the same directory where they are 
found. (With the exception when project using invoker plugin is of 
_maven-plugin_ packaging. In such case IT projects will be cloned to and 
executed in `target/its` by default.) This means that build output will be 
generated with the project files. It may be helpful to copy the projects to 
another directory before running them, for example `target/it`. This will allow 
`mvn clean` to remove the output generated  [...]
+By default the projects will be executed in the same directory where they are 
found. The exception is a project with `maven-plugin` packaging: its IT 
projects are cloned to `target/its` and executed there by default. Running in 
place means that build output will be generated with the project files. It may 
be helpful to copy the projects to another directory before running them, for 
example `target/it`. This will allow `mvn clean` to remove the output generated 
by all of the test projects.
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/fast-use.md.vm 
b/src/site/markdown/examples/fast-use.md.vm
index 81023d6..de79a4c 100644
--- a/src/site/markdown/examples/fast-use.md.vm
+++ b/src/site/markdown/examples/fast-use.md.vm
@@ -19,9 +19,9 @@ under the License.
 
 # Fast Build Configuration
 
-If you follow the recommended approach and use a dedicated local repository 
for the integration tests (e.g. `target/local-repo`), you will likely encounter 
long build times. If the test repository has been cleaned, the plugin needs to 
re-download all artifacts from the central repo and the resulting network 
traffic slows the test execution down.
+If you follow the recommended approach and use a dedicated local repository 
for the integration tests (e.g. `target/local-repo`), you will likely encounter 
long build times. If the test repository has been cleaned, the plugin needs to 
re-download all artifacts from Maven Central and the resulting network traffic 
slows the test execution down.
 
-But you can configure the plugin to download released artifacts from your 
local repo. _Note:_ This will work without optional settings with Maven &gt;= 
2.0.9 because many plugins versions are locked in the super POM. For older 
versions, you have to lock plugins versions.
+But you can configure the plugin to download artifacts from your local 
repository instead.
 
 To enable this feature, you have to add a `settings.xml` file in your project 
(for example in `src/it/settings.xml`) and modify the plugin configuration as 
this: 
 
@@ -90,7 +90,7 @@ The token `@localRepositoryUrl@` will be automatically 
replaced by the Invoker P
 
 # Fast Build Configuration - mergeUserSettings and mirrors
 
-When you want to use Fast Build Configuration with options `mergeUserSettings` 
you should take care for your mirror setting.
+If you use the Fast Build Configuration together with the `mergeUserSettings` 
parameter, check your mirror settings.
 
 If you have in `~/.m2/settings.xml` something like:
 
@@ -105,9 +105,9 @@ If you have in `~/.m2/settings.xml` something like:
 </mirrors>
 ```
 
-Please look at `mirrorOf` tag, single `*` means match all repositories for 
mirroring - also repository with id `local.central` will be mirrored. In 
effective Fast Build Configuration will not work as expected.
+Look at the `mirrorOf` element: a single `*` matches all repositories, 
including the repository with ID `local.central`, so the test builds download 
from the mirror and the Fast Build Configuration has no effect.
 
-You should change this to similar:
+Change it to something like this:
 
 ```xml
 <mirrors>
@@ -120,4 +120,4 @@ You should change this to similar:
 </mirrors>
 ```
 
-Where `external:*` - matches all repositories except those using localhost or 
file based repositories.
+`external:*` matches all repositories except those on `localhost` or with a 
`file:` URL.
diff --git a/src/site/markdown/examples/filtering.md.vm 
b/src/site/markdown/examples/filtering.md.vm
index 2050569..4263a37 100644
--- a/src/site/markdown/examples/filtering.md.vm
+++ b/src/site/markdown/examples/filtering.md.vm
@@ -25,7 +25,9 @@ Some files of the sub projects can be filtered, i.e. special 
tokens will be repl
 - The custom user setting file. Again, the tokens to be filtered in this file 
must be enclosed in `@...@`.
 - The invoker properties, the goals file and the profiles file. Tokens in 
these files must use the usual Maven syntax `${esc.d}{...}`.
 
-    Note: for filtering to work, the `cloneProjectsTo` property of the 
`invoker:run` goal must be set.
+When the projects are not [cloned](./clone-projects.html), the plugin filters 
only the POM it invokes Maven on, into a
+temporary `interpolated-pom.xml` next to it. Parent and module POMs keep their 
`@...@` tokens, so set
+`cloneProjectsTo` if a test project has modules.
 
 The following example directory structure highlights the files which are 
filtered by the Invoker Plugin:
 
@@ -88,11 +90,11 @@ When filtering the files, the plugin searches various data 
sources for a token's
 1. Built-in properties defined by the Invoker Plugin will be processed. See 
this table for a list of available built-in properties:
 
     |Built-in Property|Value|Since|
-|:---|:---|:---|
-|`basedir`|The absolute path to the project base directory of the main 
build.|1.1|
-|`baseurl`|The `file:` URL to the project base directory of the main 
build.|1.4|
-|`localRepository`|The absolute path to the local repository used for the main 
build.|1.2|
-|`localRepositoryUrl`|The `file:` URL to the local repository used for the 
main build.|1.3|
+    |:---|:---|:---|
+    |`basedir`|The absolute path to the project base directory of the main 
build.|1.1|
+    |`baseurl`|The `file:` URL to the project base directory of the main 
build.|1.4|
+    |`localRepository`|The absolute path to the local repository used for the 
main build.|1.2|
+    |`localRepositoryUrl`|The `file:` URL to the local repository used for the 
main build.|1.3|
 
 1. The properties given by the parameter `filterProperties` in the plugin 
configuration will be consulted for a property whose key equals the token. For 
the example POM shown above, the value `some-value` has been associated with 
the token `pluginPropertyUsedForFiltering`.
 1. The properties given by the POM's `<properties>` section will be searched 
for a property whose key equals the token. Regarding the example POM, the value 
`another-value` has been associated with the token 
`projectPropertyUsedForFiltering`.
diff --git a/src/site/markdown/examples/invoker-properties.md 
b/src/site/markdown/examples/invoker-properties.md
index 72b43c2..26c81f1 100644
--- a/src/site/markdown/examples/invoker-properties.md
+++ b/src/site/markdown/examples/invoker-properties.md
@@ -54,7 +54,7 @@ invoker.goals.2 = 
${project.groupId}:${project.artifactId}:${project.version}:ru
 
 # A comma or space separated list of profiles to activate
 # can be indexed
-invoker.profiles = its,jdk15
+invoker.profiles = its,java17
 
 # The path to an alternative POM or base directory to invoke Maven on, 
defaults to the
 # project that was originally specified in the plugin configuration
@@ -93,6 +93,8 @@ invoker.offline = true
 # filename given by the plugin parameter testPropertiesFile
 # Since plugin version 1.4
 # can be indexed
+# The older key invoker.systemPropertiesFile still works but is deprecated;
+# set only one of the two keys
 invoker.userPropertiesFile = test.properties
 
 # An optional human friendly name and description for this build job.
@@ -103,7 +105,7 @@ invoker.description = Checks the support for build reports.
 
 # A comma separated list of JRE versions on which this build job should be run.
 # Since plugin version 1.4
-invoker.java.version = 1.4+, !1.4.1, 1.7-
+invoker.java.version = 17+, !21.0.1
 
 # A comma separated list of OS families on which this build job should be run.
 # Since plugin version 1.4
@@ -111,24 +113,25 @@ invoker.os.family = !windows, unix, mac
 
 # A comma separated list of Maven versions on which this build should be run.
 # Since plugin version 1.5
-invoker.maven.version = 2.0.10+, !2.1.0, !2.2.0
+invoker.maven.version = 3.9.0+, !3.9.2
 
 # A mapping for toolchain to ensure it exists
 # Since plugin version 3.2.0
 invoker.toolchain.<type>.<provides> = value
 # Exact match
-invoker.toolchain.jdk.version = 11
+# invoker.toolchain.jdk.version = 17
 # Range match
-invoker.toolchain.jdk.version = [11,12)
+invoker.toolchain.jdk.version = [17,22)
 
 # For java.version, maven.version, os.family and toolchain it is possible to 
define multiple selectors.
 # If one of the indexed selectors matches, the test is executed.
 # With the invoker.x.y equivalents you can specify global matchers.
-selector.1.java.version = 1.8+
-selector.1.maven.version = 3.2.5+
+# An indexed toolchain selector uses the key 
selector.N.invoker.toolchain.<type>.<provides>
+selector.1.java.version = 17+
+selector.1.maven.version = 3.9.0+
 selector.1.os.family = !windows
-selector.2.maven.version = 3.0+
-selector.3.java.version = 9+
+selector.2.maven.version = 4.0.0+
+selector.3.java.version = 21+
 
 # A boolean value controlling the debug logging level of Maven, defaults to 
"false"
 # Since plugin version 1.8
@@ -146,9 +149,11 @@ invoker.quiet = true
 invoker.timeoutInSeconds = 5
 
 # Path to an alternate settings.xml to use for Maven invocation with this IT.
+# A relative path is resolved against the working directory of the main build,
+# usually the base directory of the project that runs the plugin.
 # Since plugin version 3.0.1
 # can be indexed
-invoker.settingsFile = ../
+invoker.settingsFile = src/it/other-settings.xml
 
 # An integer value to control run order of projects. sorted in the descending 
order of the ordinal.
 # In other words, the BuildJobs with the highest numbers will be executed first
@@ -158,8 +163,10 @@ invoker.ordinal = 3
 
 # The additional value for the environment variable.
 # Since plugin version 3.2.2
+# can be indexed, with the index after the variable name
 invoker.environmentVariables.<variableName> = variableValue
 invoker.environmentVariables.MY_ENV_NAME = myEnvValue
+invoker.environmentVariables.MY_ENV_NAME.2 = valueForSecondInvocation
 
 # A boolean value indicating a check for missing releases and updated 
snapshots on remote repositories to be done
 # Passed to the invoker. Same as passing -U, --update-snapshots flag on the 
command line
diff --git a/src/site/markdown/examples/logs-for-failed-tests.md.vm 
b/src/site/markdown/examples/logs-for-failed-tests.md.vm
index d452fb1..6adfaf4 100644
--- a/src/site/markdown/examples/logs-for-failed-tests.md.vm
+++ b/src/site/markdown/examples/logs-for-failed-tests.md.vm
@@ -19,9 +19,9 @@ under the License.
 
 # Inspect logs for failed tests
 
-In the usual build all tests pass as we expect, so printing logs from all 
tests to project build log make our standard build log illegible. The problem 
begin when some of test was failed, especially when happened on CI system when 
access to files from build workspace is difficult.
+The output of each test build goes to its own `build.log` file, which keeps 
the main build output readable. When a test fails on a CI system, though, the 
files of the build workspace are often hard to reach.
 
-In order to help investigation on failed test we can use option: 
`streamLogsOnFailures`. Now logs from all failed test will be printed to 
project build log when all test will have finished.
+Set the `streamLogsOnFailures` parameter of the 
[`run`](../run-mojo.html#streamLogsOnFailures) or 
[`verify`](../verify-mojo.html#streamLogsOnFailures) goal to print the 
`build.log` of every failed test to the main build output once all tests have 
finished.
 
 ```xml
 <project>
diff --git a/src/site/markdown/examples/parallel-projects-execution.md.vm 
b/src/site/markdown/examples/parallel-projects-execution.md.vm
index 1385455..d9abd55 100644
--- a/src/site/markdown/examples/parallel-projects-execution.md.vm
+++ b/src/site/markdown/examples/parallel-projects-execution.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Parallel projects execution
 
-In order to speed up your tests execution you can use options 
`parallelThreads`. This will be the number of maven forked process in parallel. 
When terminated with "C", the number part is multiplied by the number of 
processors (cores) available to the Java virtual machine.
+To speed up test execution, set the `parallelThreads` parameter to the number 
of Maven processes to run in parallel. When the value ends with "C", the number 
is multiplied by the number of processors (cores) available to the Java virtual 
machine.
 
 Example configuration:
 
@@ -44,14 +44,14 @@ Example configuration:
 
 # Order of projects execution in parallel mode
 
-When use parallel, at any point, at most `parallelThreads` threads will be 
active for projects executions.
+In parallel mode, at most `parallelThreads` projects run at any point.
 
-Projects are send to execute by available thread in **non guaranteed 
sequence**, the most time it is determined by file system ordering. Internally 
`java.io.File#list()` is used for scanning projects.
+The order in which projects start is **not guaranteed**; most of the time it 
follows the order in which the file system lists the project directories.
 
-Some of projects can take more time and some can finish quicker. Next projects 
from queue will be executed as soon as thread in pool will be available. So 
order of executing can change, depends on many thing, like available processor, 
current system load etc...
+Some projects take longer than others. The next project in the queue starts as 
soon as a thread is free, so the order of execution can change with the number 
of processors, the system load and so on.
 
-If you need be sure of execution sequence, you can use `invoker.ordinal` 
property in [Invoker Properties](./invoker-properties.html)
+If you need a defined order, use the `invoker.ordinal` property in [Invoker 
Properties](./invoker-properties.html).
 
-In parallel mode projects are **grouped** by `invoker.ordinal` and projects 
from each groups are running in parallel. Projects from next group will start 
running after all projects from previous group are finished.
+In parallel mode, projects are **grouped** by `invoker.ordinal`, and the 
projects of a group run in parallel. The projects of the next group start after 
all projects of the previous group have finished.
 
-`Setup` projects are executed first in sequential always on one thread.
+Setup projects always run first, one after the other on a single thread.
diff --git a/src/site/markdown/examples/pre-post-build-script.md.vm 
b/src/site/markdown/examples/pre-post-build-script.md.vm
index e26b575..6300587 100644
--- a/src/site/markdown/examples/pre-post-build-script.md.vm
+++ b/src/site/markdown/examples/pre-post-build-script.md.vm
@@ -21,22 +21,20 @@ under the License.
 
 Complementary to the post-build hook script, you can also create a pre-build 
hook script that will be run before the invocation of Maven. This can be used 
to do some preparations for the build.
 
-The default name of the pre-build script is `prebuild`, which resolves to 
`prebuild.groovy`, or to the deprecated `prebuild.bsh`.
+The default name of the pre-build script is `prebuild`, which resolves to 
`prebuild.groovy`, or to the deprecated `prebuild.bsh`. Write hook scripts in 
Groovy; see [BeanShell scripts](${esc.hash}BeanShell_scripts) for the 
deprecation of BeanShell.
 
-**BeanShell scripts are deprecated.** Support for `.bsh` scripts will be 
removed in a future release; write new scripts in Groovy and port existing 
BeanShell scripts. The plugin logs a warning for every BeanShell script it 
runs. Tracked in 
[apache/maven#13207](https://github.com/apache/maven/issues/13207).
+In a pre-build script you can prepare test resources for your project.
 
-In Pre-Build scripts you can prepare a test resources for your project.
+You can also define user properties, which the plugin passes to the build of 
the test project as `-D` arguments.
 
-You can also define a user properties which will be added to executed test 
project by `-D` Maven argument.
-
-Here is an example of groovy script:
+Here is an example of a Groovy script (`prebuild.groovy`) that finds a free 
port and passes it to the build:
 
 ```groovy
 def userProperties = context.get('userProperties')
 
-def server = new MockServer()
-userProperties.put('serverHost', server.getHost())
-userProperties.put('serverPort', server.getPort())
+def port = new ServerSocket(0).withCloseable { it.localPort }
+userProperties.put('serverHost', 'localhost')
+userProperties.put('serverPort', String.valueOf(port))
 ```
 
 Now you can use it in test project:
@@ -63,7 +61,7 @@ Now you can use it in test project:
 
 # Using a Post-Build Script
 
-Here is an example of how the Invoker Plugin can be used to run a set of Maven 
projects and then verify their output with a [Groovy](https://groovy-lang.org/) 
script (or a deprecated [BeanShell](https://beanshell.github.io/) one). The 
name of the script file in this case is `verify` - default value is `postbuild`.
+Here is an example of how the Invoker Plugin can be used to run a set of Maven 
projects and then verify their output with a [Groovy](https://groovy-lang.org/) 
script. The name of the script file in this case is `verify`; the default name 
is `postbuild`.
 
 ```xml
 <project>
@@ -101,7 +99,22 @@ def file = new File( basedir, 
"target/my-test-project-1.0-SNAPSHOT.jar" )
 assert file.isFile()
 ```
 
-The same check as a deprecated BeanShell script (`verify.bsh`), for existing 
scripts that have not been ported yet:
+# BeanShell scripts
+
+Since plugin version 3.11.0, BeanShell (`.bsh`) scripts are deprecated, and 
support for them will be removed in a
+future release. This covers every script the plugin runs: the selector script 
and the pre-build and post-build hook
+scripts, including the indexed ones such as `postbuild.1.bsh`. Write new 
scripts in Groovy and port existing ones.
+Removing BeanShell across Maven is tracked in 
[apache/maven#13207](https://github.com/apache/maven/issues/13207).
+
+The plugin still runs BeanShell scripts. For each `.bsh` script it runs, it 
logs a warning once per plugin execution,
+both in the Maven output and in the `build.log` of the test project:
+
+```text
+[WARNING] BeanShell scripts are deprecated, port 
/path/to/project/target/it/first-it/verify.bsh to Groovy: 
https://maven.apache.org/plugins/maven-invoker-plugin/examples/pre-post-build-script.html
+```
+
+To port a script, rename it to `.groovy` and adjust the code. Most BeanShell 
code is valid Groovy; the `verify.bsh`
+below behaves like the `verify.groovy` above:
 
 ```java
 import java.io.*;
@@ -113,6 +126,9 @@ if ( !file.isFile() )
 }
 ```
 
+Delete the `.bsh` file once the `.groovy` file exists: when you configure a 
script name without an extension and both
+files exist, the plugin runs the `.bsh` one.
+
 # Pre and Post Build Script for multiple project executions
 
 You can run multiple project executions in a single test by defining several 
`invoker.goals.N` in the `invoker.properties` file.
diff --git a/src/site/markdown/examples/prepare-build-env.md.vm 
b/src/site/markdown/examples/prepare-build-env.md.vm
index a88b391..3f5bcce 100644
--- a/src/site/markdown/examples/prepare-build-env.md.vm
+++ b/src/site/markdown/examples/prepare-build-env.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Preparing the Build Environment
 
-In general, the plugin assumes that the projects to build are unrelated to one 
other such that their build order does not matter. However, you might sometimes 
want to ensure that certain projects are build before others. As a motivation, 
imagine that a project performs some kind of common setup for the other 
projects, e.g. installing utility artifacts into the local repository.
+In general, the plugin assumes that the projects to build are unrelated to one 
another such that their build order does not matter. However, you might 
sometimes want to ensure that certain projects are built before others. As a 
motivation, imagine that a project performs some kind of common setup for the 
other projects, e.g. installing utility artifacts into the local repository.
 
 Starting with plugin version 1.3, you can declare a group of setup projects 
that must be run before all the other projects by means of the parameter 
`<setupIncludes>` as shown in the following example:
 
@@ -56,4 +56,4 @@ This tells the plugin that the project 
`utility-plugin/pom.xml` must be run befo
 
 The build order of several such setup projects is still undefined. So if the 
setup projects have inter-dependencies that require a certain build order, you 
should group them by an aggregator POM and feed that into the Invoker Plugin 
such that the correct build order will be determined by Maven's multi-module 
reactor.
 
-You can also apply `invoker.ordinal` property in [Invoker 
Properties](./invoker-properties.html) for setup projects to ensure order
+You can also set the `invoker.ordinal` property in [Invoker 
Properties](./invoker-properties.html) of setup projects to define their order.
diff --git a/src/site/markdown/examples/selector-conditions.md 
b/src/site/markdown/examples/selector-conditions.md
index 8b683fe..205494b 100644
--- a/src/site/markdown/examples/selector-conditions.md
+++ b/src/site/markdown/examples/selector-conditions.md
@@ -19,11 +19,11 @@ under the License.
 
 # Selector Conditions
 
-Starting with plugin version 1.4, some keys of the [Invoker 
Properties](./invoker-properties.html) can be used to skip individual projects 
based on the current JRE version or OS family as illustrated in the example 
below:
+Starting with plugin version 1.4, some keys of the [Invoker 
Properties](./invoker-properties.html) can be used to skip individual projects 
based on the current Java version or OS family as illustrated in the example 
below:
 
 ```properties
-# build project if JRE version is 1.4 or higher, but exclude version 1.4.1
-invoker.java.version = 1.4+, !1.4.1
+# build project if Java version is 17 or higher, but exclude version 21.0.1
+invoker.java.version = 17+, !21.0.1
 
 # build project if OS family is not Windows
 invoker.os.family = !windows
@@ -32,18 +32,32 @@ invoker.os.family = !windows
 In addition, with plugin version 1.5, there is the ability to skip individual 
projects based on the current Maven version as illustrated in the example below:
 
 ```properties
-# build project if Maven version is 2.0.10 or higher, but exclude versions 
2.1.0 and 2.2.0
-invoker.maven.version = 2.0.10+, !2.1.0, !2.2.0
+# build project if Maven version is 3.9.0 or higher, but exclude version 3.9.2
+invoker.maven.version = 3.9.0+, !3.9.2
 ```
 
+The Java version is the one of the JVM that runs the test builds: the JVM 
running Maven, or the one given by the
+[`javaHome`](../run-mojo.html#javaHome) parameter. The Maven version is the 
one of the Maven installation that runs
+the test builds.
+
 The values of these keys are comma separated tokens. A token prefixed with 
"\!" denotes an exclusion, otherwise it denotes an inclusion. A project is 
build if no exclusion matches and if no inclusions are given or at least one of 
them matches the current environment.
 
 The tokens to describe versions can be suffixed with "+" or "-". The table 
below shows how the different styles of version tokens translate to a version 
range:
 
 |Version Token|Equivalent Version Range|
 |:---|:---|
-|1\.5|\[1.5,1.6)|
-|1\.5+|\[1.5,)|
-|1\.5-|(,1.5)|
+|17|\[17,18)|
+|17+|\[17,)|
+|17-|(,17)|
+|3\.9|\[3.9,3.10)|
+
+For the OS family, use tokens such as "windows", "unix" and "mac".
+
+A project can also require a toolchain configured in `toolchains.xml`, for 
example a JDK 17 toolchain:
+
+```properties
+invoker.toolchain.jdk.version = 17
+```
 
-For the OS family, the tokens "windows", "unix" and "mac" are supported.
+To run a project if any one of several combinations matches, use indexed 
selectors such as `selector.1.java.version`;
+see [Invoker Properties](./invoker-properties.html).
diff --git a/src/site/markdown/examples/selector-scripts.md.vm 
b/src/site/markdown/examples/selector-scripts.md.vm
index 6d47ade..2b6b6b5 100644
--- a/src/site/markdown/examples/selector-scripts.md.vm
+++ b/src/site/markdown/examples/selector-scripts.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Selector Scripts
 
-Starting with plugin version 1.5, a custom script can be used to skip 
individual projects based on whatever criteria expressed in the script as 
illustrated in the following example. Write the script in Groovy; BeanShell 
scripts are deprecated and the plugin warns when it runs one. Assume the 
following directory structure:
+Starting with plugin version 1.5, a custom script can be used to skip 
individual projects based on whatever criteria expressed in the script as 
illustrated in the following example. Write the script in Groovy; BeanShell 
scripts are 
[deprecated](./pre-post-build-script.html${esc.hash}BeanShell_scripts) and the 
plugin warns when it runs one. Assume the following directory structure:
 
 ```text
 ./
@@ -75,6 +75,12 @@ If the script returns any value other than `true`, then the 
project will not be
 
 If the script throws an exception, then the project will be marked as being in 
ERROR.
 
+For example, this `check-assumptions.groovy` runs the project only when a 
`docker` executable is on the `PATH`:
+
+```groovy
+return System.getenv('PATH').split(File.pathSeparator).any { new File(it, 
'docker').canExecute() }
+```
+
 # Predefined global variables
 
-In Selector Scripts the same global variables are defined as in [Pre and Post 
Build Script](./pre-post-build-script.html#predefined-global-variables)
+In Selector Scripts the same global variables are defined as in [Pre and Post 
Build Script](./pre-post-build-script.html#Predefined_global_variables)
diff --git a/src/site/markdown/examples/skipping.md.vm 
b/src/site/markdown/examples/skipping.md.vm
index a48cadf..4f2d5b1 100644
--- a/src/site/markdown/examples/skipping.md.vm
+++ b/src/site/markdown/examples/skipping.md.vm
@@ -21,7 +21,7 @@ under the License.
 
 The Invoker Plugin usually performs an installation setup and runs the 
configured Maven invocations. Since version 1.4 of the plugin all these steps 
may be skipped.
 
-To skip running the invocations for a particular project, set the 
`skipInvocation` property to `true`. The artifact staging to a local repository 
can be skipped by setting the parameter `skipInstallation` to `true`.
+To skip running the invocations for a particular project, set the 
`skipInvocation` parameter to `true`. The artifact staging to a local 
repository can be skipped by setting the parameter `skipInstallation` to `true`.
 
 ```xml
 <project>
@@ -43,7 +43,7 @@ To skip running the invocations for a particular project, set 
the `skipInvocatio
 </project>
 ```
 
-All these steps can also be omited via the command line by use of the 
`invoker.skip` property:
+You can also skip all these steps from the command line with the 
`invoker.skip` property:
 
 ```shell
 mvn install -Dinvoker.skip=true
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 2b389b8..df70fbb 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -34,11 +34,9 @@ under the License.
 
 ### Why do I need to use this plugin?
 
-It is essential that you provide some form of integration testing for your 
projects and the Invoker Plugin
-tries to make is easy for you to create integration tests for your Maven 
Plugins, new Lifecycles, or any other
-type of Maven component that you've created. Currently the Invoker Plugin 
forks Maven to execute the specified
-projects, but it is hoped that soon we will integrate the Maven Embedder into 
the mix to allow you run your
-projects in process for great speed.
+Integration tests show that your Maven plugin, lifecycle or other Maven 
component works in a real build. The
+Invoker Plugin runs each test project in a separate Maven process, so the test 
sees the same behavior as a user's
+build, and it reports which test projects passed or failed.
 
 <a id="question2"></a>
 
@@ -47,14 +45,14 @@ projects in process for great speed.
 Sometimes you might want to test that error conditions are properly dealt 
with, i.e. fail a build. To assert a
 failure for a particular IT project, put the following setting into the 
properties file denoted by the
 plugin's [`invokerPropertiesFile`](run-mojo.html#invokerPropertiesFile) 
parameter:
-*invoker.buildResult=failure*. Now, the failure of the IT build will be 
interpreted as a test success.
+`invoker.buildResult = failure`. Now, the failure of the IT build will be 
interpreted as a test success.
 Likewise, a successful IT build will be considered a test failure.
 
 <a id="question3"></a>
 
 ### How can I share common code between the pre-/post-build scripts?
 
-If you want to avoid copy&amp;paste of lengthy code snippets within the hook 
scripts, you can move this code
+If you want to avoid copy and paste of lengthy code snippets within the hook 
scripts, you can move this code
 into a regular Java class. More precisely, you would place this utility code 
somewhere in your test source
 tree and set the plugin parameter 
[`addTestClassPath`](run-mojo.html#addTestClassPath) to `true`. For more
 details, please see the example [Accessing Test 
Classes](examples/access-test-classes.html).
diff --git a/src/site/markdown/groovy-version.md.vm 
b/src/site/markdown/groovy-version.md.vm
index 1fc1fcd..c2094c8 100644
--- a/src/site/markdown/groovy-version.md.vm
+++ b/src/site/markdown/groovy-version.md.vm
@@ -19,15 +19,16 @@ under the License.
 
 # Groovy version and extensions
 
-**NOTICE**: Plugin `maven-invoker-plugin` in versions older than `3.3.0` has 
dependency on `groovy-all` artifact from `Groovy 2`.
-
-Plugin `maven-invoker-plugin` in version `3.4.0` has only dependency on 
`Groovy 4` core add common extensions:
+The plugin runs Groovy hook and selector scripts with Groovy ${groovyVersion}. 
Groovy 4.0.33 added the Java 26 and 27
+bytecode levels 
([GROOVY-12200](https://issues.apache.org/jira/browse/GROOVY-12200)), so 
scripts also run when Maven
+runs on JDK 27. The plugin depends on these Groovy modules:
 
 - `org.apache.groovy:groovy:${groovyVersion}`
 - `org.apache.groovy:groovy-json:${groovyVersion}`
 - `org.apache.groovy:groovy-xml:${groovyVersion}`
 
-If you need additional `Groovy` extension in your scripts ( post, pre, setup, 
... ) you must add a dependency to plugin definition, eg:
+If your scripts (`setup`, `prebuild`, `postbuild`, `selector`) need another 
Groovy module, add it as a dependency of
+the plugin, with the same version as the Groovy modules above, for example:
 
 ```xml
 <project>
@@ -36,7 +37,6 @@ If you need additional `Groovy` extension in your scripts ( 
post, pre, setup, ..
       <plugin>
         <artifactId>maven-invoker-plugin</artifactId>
         <version>${project.version}</version>
-        .....
         <dependencies>
           <dependency>
             <groupId>org.apache.groovy</groupId>
@@ -50,4 +50,10 @@ If you need additional `Groovy` extension in your scripts ( 
post, pre, setup, ..
 </project>
 ```
 
-**NOTICE**: In plugin version `3.3.0` only `Groovy 4` extensions can be used.
+Older plugin versions shipped other Groovy versions, so an extension has to 
match the plugin version you use:
+
+|Plugin version|Groovy|Group ID of the modules|
+|:---|:---|:---|
+|3.4.0 and later|Groovy 4|`org.apache.groovy`|
+|3.3.0|Groovy 3|`org.codehaus.groovy`|
+|before 3.3.0|Groovy 2, as `groovy-all`|`org.codehaus.groovy`|
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 7c3cf71..1fb1b59 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -18,29 +18,59 @@ under the License.
 -->
 
 # Apache Maven Invoker Plugin
-The Invoker Plugin is used to run a set of Maven projects. The plugin can 
determine whether each project execution is successful, and optionally can 
verify the output generated from a given project execution.
 
-This plugin is in particular handy to perform integration tests for other 
Maven plugins. The Invoker Plugin can be employed to run a set of test projects 
that have been designed to assert certain features of the plugin under test.
+The Invoker Plugin runs a set of Maven projects and checks the result of each 
build. Its main use is integration
+testing of Maven plugins and extensions: each test is a small Maven project 
under `src/it` that exercises the plugin
+under test, and an optional Groovy script checks what the build produced.
+
+The plugin requires Maven 3.9.0 or later and Java 8 or later.
+
+Most users come to the plugin for these tasks:
+
+- Run all integration tests in `src/it` as part of the build:
+
+    ```shell
+    mvn verify
+    ```
+
+- Rerun one or a few integration tests:
+
+    ```shell
+    mvn verify -Dinvoker.test=first-it,second-*
+    ```
+
+- Check the result of a build with a [post-build Groovy 
script](./examples/pre-post-build-script.html), and
+  configure each test with an 
[`invoker.properties`](./examples/invoker-properties.html) file.
+- Skip the integration tests:
+
+    ```shell
+    mvn install -Dinvoker.skip=true
+    ```
+
+The [usage page](./usage.html) shows the plugin configuration these commands 
rely on.
 
 ## Goals Overview
 
-The plugin has four goals meant to participate in the default build lifecycle:
+The plugin has four goals that take part in the default build lifecycle:
 
 - [invoker:install](./install-mojo.html) copies the project artifacts and 
dependencies of the main build into a dedicated local repository to prepare the 
execution of the selected sub projects in an isolated environment.
 - [invoker:integration-test](./integration-test-mojo.html) runs a set of Maven 
projects in a directory.
 - [invoker:verify](./verify-mojo.html) verifies the result of 
`invoker:integration-test`.
 - [invoker:run](./run-mojo.html) runs a set of Maven projects in a directory 
and verifies the result. This is equivalent to running both 
`invoker:integration-test` and `invoker:verify`.
 
-This last goal is intended for usage with the site lifecycle:
+One goal is meant for the site lifecycle:
 
 - [invoker:report](./report-mojo.html) integrates the results from previous 
builds into the site.
+
+[invoker:help](./help-mojo.html) displays help information on the plugin's 
goals and parameters.
+
 ## Usage
 
 General instructions on how to use the Invoker Plugin can be found on the 
[usage page](./usage.html). Some more specific use cases are described in the 
examples given below.
 
-In case you still have questions regarding the plugin's usage, please have a 
look at the [FAQ](./faq.html) and feel free to contact the [user mailing 
list](./mailing-lists.html). The posts to the mailing list are archived and 
could already contain the answer to your question as part of an older thread. 
Hence, it is also worth browsing/searching the [mail 
archive](./mailing-lists.html).
+If you still have questions about the plugin's usage, see the 
[FAQ](./faq.html) and ask on the [user mailing list](./mailing-lists.html), 
whose archive may already answer your question.
 
-If you feel like the plugin is missing a feature or has a defect, you can fill 
a feature request or bug report in our [issue 
tracker](./issue-management.html). When creating a new issue, please provide a 
comprehensive description of your concern. Especially for fixing bugs it is 
crucial that the developers can reproduce your problem. For this reason, entire 
debug logs, POMs or most preferably little demo projects attached to the issue 
are very much appreciated. Of course, patches are wel [...]
+If the plugin is missing a feature or has a defect, open an issue in our 
[issue tracker](./issue-management.html). For a bug, include a debug log (`mvn 
-X`) and, ideally, a small project that reproduces the problem. Contributors 
can check out the project from our [source repository](./scm.html) and will 
find supplementary information in the [guide to helping with 
Maven](https://maven.apache.org/guides/development/guide-helping.html).
 
 ## Examples
 
@@ -54,9 +84,12 @@ The following example configurations are available to 
illustrate selected use ca
 - [Fast Invoker Plugin configuration](./examples/fast-use.html) to accelerate 
project execution.
 - [Access test classes](./examples/access-test-classes.html) to share code 
between hook scripts.
 - [Use Invoker Properties](./examples/invoker-properties.html) to configure 
goals, profiles etc. for individual projects.
-- [Use Selector Conditions](./examples/selector-conditions.html) to skip 
projects based on JRE version or OS family.
+- [Use Selector Conditions](./examples/selector-conditions.html) to skip 
projects based on the Java version, Maven version, OS family or available 
toolchains.
+- [Use Selector Scripts](./examples/selector-scripts.html) to skip projects 
based on a Groovy script.
 - [Parallel projects execution](./examples/parallel-projects-execution.html) 
to speed up project execution.
 - [Prepare the Build Environment](./examples/prepare-build-env.html) by 
building some setup projects before other projects.
+- [Skip invocations](./examples/skipping.html) or the installation step.
+- [Inspect logs for failed tests](./examples/logs-for-failed-tests.html) in 
the main build output.
 - [Using with other integration test 
frameworks](./examples/integration-test-verify.html) by decoupling checking the 
results of the integration tests from executing the integration tests.
 
 You can also study some real-life usages of the Invoker Plugin by browsing its 
own integration tests which are located in the directory `src/it` of the 
[project source tree](./scm.html).
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 7837e31..34a714d 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -19,7 +19,7 @@ under the License.
 
 # Usage
 
-This page provides general usage information along with a basic example. The 
plugin is commonly used to run and verify integration tests for a project, say 
a Maven plugin. This is done using the [` invoker:run `](./run-mojo.html) goal. 
And as a preparation for the integration tests, one usually wants to stage the 
artifacts under tests into a testing repository. For this job, the [` 
invoker:install `](./install-mojo.html) goal can be used.
+This page provides general usage information along with a basic example. The 
plugin is commonly used to run and verify integration tests for a project, say 
a Maven plugin. This is done using the [`invoker:run`](./run-mojo.html) goal. 
And as a preparation for the integration tests, one usually wants to stage the 
artifacts under tests into a testing repository. For this job, the 
[`invoker:install`](./install-mojo.html) goal can be used.
 
 Basic Example
 -------------

Reply via email to