This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch deprecate in repository https://gitbox.apache.org/repos/asf/maven-verifier.git
commit 01d7cf06a12fc833b1d7a14dcbd882197faaaada Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Tue Dec 30 14:05:35 2025 +0000 Added notice about planned project deprecation --- MIGRATION.md | 304 +++++++++++++++++++++ README.md | 9 + pom.xml | 43 ++- .../maven/shared/verifier/Embedded3xLauncher.java | 5 + .../maven/shared/verifier/ForkedLauncher.java | 7 + .../maven/shared/verifier/LauncherException.java | 6 + .../maven/shared/verifier/MavenLauncher.java | 7 + .../shared/verifier/VerificationException.java | 7 + .../org/apache/maven/shared/verifier/Verifier.java | 40 +++ .../shared/verifier/util/ResourceExtractor.java | 12 +- src/site/markdown/getting-started.md | 9 + src/site/markdown/index.md | 11 + 12 files changed, 457 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..57dc343 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,304 @@ +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> + +# Migration Guide: From maven-verifier to maven-executor + +## ⚠️ Deprecation Notice + +**Apache Maven Verifier is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** + +New projects should use maven-executor. Existing projects should plan migration to maven-executor. + +See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for more details. + +## Why Migrate? + +### Problems with Current Ecosystem + +Maven currently has two overlapping components for running Maven programmatically: +- **maven-invoker**: Can only fork Maven processes +- **maven-verifier**: Can fork or embed Maven, but with helper methods unnecessarily coupled to execution + +Both have issues: +- ❌ Different APIs for the same purpose +- ❌ Require updates when Maven CLI changes +- ❌ Heavy-handed solutions with duplicated concerns +- ❌ No unified approach for Maven 3 and Maven 4 support +- ❌ Time-consuming to maintain + +### Benefits of maven-executor + +- ✅ **Unified API**: Single, simple API without need for changes when CLI changes +- ✅ **Both execution modes**: Supports both "forked" and "embedded" executors +- ✅ **Dependency-less**: Minimal dependencies +- ✅ **Maven 3.9 & 4+ support**: Transparent support for both Maven versions +- ✅ **Better isolation**: Proper environment isolation +- ✅ **Already in use**: Powers Maven 4 Integration Tests + +## Migration Path + +### 1. Update Dependencies + +**Remove:** +```xml +<dependency> + <groupId>org.apache.maven.shared</groupId> + <artifactId>maven-verifier</artifactId> + <scope>test</scope> +</dependency> +``` + +**Add:** +```xml +<dependency> + <groupId>org.apache.maven</groupId> + <artifactId>maven-executor</artifactId> + <version>4.0.0-rc-5</version> <!-- Use latest version --> + <scope>test</scope> +</dependency> +``` + +> **Note**: maven-executor location may change as it might be moved out of Maven 4 core to become a standalone project. Check the latest documentation. + +### 2. Code Migration Examples + +#### Before (maven-verifier): + +```java +import org.apache.maven.shared.verifier.Verifier; +import org.apache.maven.shared.verifier.VerificationException; + +public class MyTest { + @Test + public void testBuild() throws Exception { + String baseDir = "/path/to/project"; + Verifier verifier = new Verifier(baseDir); + + // Configure + verifier.setAutoclean(false); + verifier.setMavenDebug(true); + verifier.addCliArgument("-DskipTests=true"); + + // Execute + verifier.addCliArgument("package"); + verifier.execute(); + + // Verify + verifier.verifyErrorFreeLog(); + verifier.verifyFilePresent("target/my-app-1.0.jar"); + verifier.resetStreams(); + } +} +``` + +#### After (maven-executor): + +```java +import org.apache.maven.api.cli.Executor; +import org.apache.maven.api.cli.ExecutorRequest; +import org.apache.maven.cling.executor.ExecutorHelper; +import org.apache.maven.cling.executor.forked.ForkedExecutor; +import org.apache.maven.cling.executor.embedded.EmbeddedExecutor; + +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Arrays; + +public class MyTest { + @Test + public void testBuild() throws Exception { + Path baseDir = Paths.get("/path/to/project"); + + // Choose executor type: Forked or Embedded + Executor executor = new ForkedExecutor(); + // OR: Executor executor = new EmbeddedExecutor(); + + // Build request with CLI arguments + ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(Arrays.asList("package", "-DskipTests=true", "-X")) + .build(); + + // Execute + int exitCode = executor.execute(request); + + // Verify + assertEquals(0, exitCode, "Build should succeed"); + assertTrue(Files.exists(baseDir.resolve("target/my-app-1.0.jar")), + "JAR file should exist"); + } +} +``` + +### 3. Key API Mapping + +| maven-verifier Concept | maven-executor Equivalent | +|------------------------|---------------------------| +| `new Verifier(baseDir)` | `ExecutorRequest.builder().cwd(baseDir).build()` | +| `verifier.addCliArgument(arg)` | Add to `arguments` list in ExecutorRequest | +| `verifier.setMavenDebug(true)` | Add `-X` to arguments | +| `verifier.setAutoclean(false)` | Manage manually or via arguments | +| `verifier.setForkJvm(true)` | Use `ForkedExecutor` | +| `verifier.setForkJvm(false)` | Use `EmbeddedExecutor` | +| `verifier.execute()` | `executor.execute(request)` | +| `verifier.verifyErrorFreeLog()` | Check `exitCode == 0` | +| `verifier.verifyFilePresent(path)` | Use `Files.exists(Paths.get(...))` | +| `verifier.verifyTextInLog(text)` | Capture and parse executor output | + +### 4. Environment Variables + +**Before:** +```java +verifier.setEnvironmentVariable("JAVA_HOME", "/path/to/java"); +verifier.setEnvironmentVariable("MAVEN_OPTS", "-Xmx1024m"); +``` + +**After:** +```java +Map<String, String> env = new HashMap<>(); +env.put("JAVA_HOME", "/path/to/java"); +env.put("MAVEN_OPTS", "-Xmx1024m"); + +ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(args) + .environmentVariables(env) + .build(); +``` + +### 5. Verification Helpers + +maven-verifier included many helper methods like `verifyFilePresent()`, `verifyTextInLog()`, etc. These are not part of maven-executor's core responsibility. Instead: + +**Extract verification to separate utilities:** +```java +public class MavenTestUtils { + public static void assertFileExists(Path base, String relativePath) { + Path file = base.resolve(relativePath); + assertTrue(Files.exists(file), + "Expected file does not exist: " + file); + } + + public static void assertLogContains(String log, String expectedText) { + assertTrue(log.contains(expectedText), + "Log does not contain expected text: " + expectedText); + } + + public static void assertErrorFreeLog(String log) { + assertFalse(log.contains("[ERROR]"), + "Log contains errors"); + } +} +``` + +### 6. Settings and Local Repository + +**Before:** +```java +verifier.setLocalRepo("/custom/repo"); +verifier.setUserSettingsFile("/path/to/settings.xml"); +``` + +**After:** +```java +ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(Arrays.asList( + "package", + "-Dmaven.repo.local=/custom/repo", + "-s", "/path/to/settings.xml" + )) + .build(); +``` + +## Migration Checklist + +- [ ] Review all usages of `Verifier` class in your codebase +- [ ] Update POM dependencies to use maven-executor +- [ ] Replace Verifier instantiation with ExecutorRequest builder pattern +- [ ] Convert `addCliArgument()` calls to arguments list +- [ ] Choose between ForkedExecutor and EmbeddedExecutor +- [ ] Replace verification methods with standard Java file checks or custom utilities +- [ ] Update environment variable configuration +- [ ] Update local repository and settings configuration +- [ ] Test thoroughly with your integration test suite +- [ ] Update documentation and comments + +## Gradual Migration Strategy + +For large codebases, consider a gradual approach: + +1. **Phase 1**: Add maven-executor dependency alongside maven-verifier +2. **Phase 2**: Create adapter/wrapper classes to ease transition +3. **Phase 3**: Migrate tests module by module +4. **Phase 4**: Remove maven-verifier dependency once all tests are migrated + +## Example Adapter Pattern + +For gradual migration, you can create an adapter: + +```java +public class MavenExecutorAdapter { + private final Path baseDir; + private final List<String> arguments = new ArrayList<>(); + private final Map<String, String> env = new HashMap<>(); + private Executor executor = new ForkedExecutor(); + + public MavenExecutorAdapter(String baseDir) { + this.baseDir = Paths.get(baseDir); + } + + public void addCliArgument(String arg) { + arguments.add(arg); + } + + public void setEnvironmentVariable(String key, String value) { + env.put(key, value); + } + + public void setForkJvm(boolean fork) { + executor = fork ? new ForkedExecutor() : new EmbeddedExecutor(); + } + + public void execute() throws Exception { + ExecutorRequest request = ExecutorRequest.builder() + .cwd(baseDir) + .arguments(arguments) + .environmentVariables(env) + .build(); + + int exitCode = executor.execute(request); + if (exitCode != 0) { + throw new Exception("Maven execution failed with exit code: " + exitCode); + } + } + + // Add other adapter methods as needed +} +``` + +## Resources + +- [maven-executor source](https://github.com/apache/maven/tree/master/impl/maven-executor) +- [Maven 4 IT Verifier implementation](https://github.com/apache/maven/blob/master/its/core-it-support/maven-it-helper/src/main/java/org/apache/maven/it/Verifier.java) +- [Issue #186 discussion](https://github.com/apache/maven-verifier/issues/186) + +## Support & Questions + +For migration questions or issues: +- Post to [Maven Dev Mailing List](https://maven.apache.org/mailing-lists.html) +- Open issues on [maven-executor GitHub](https://github.com/apache/maven/issues) diff --git a/README.md b/README.md index 8839ca8..444766c 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,15 @@ Contributing to [Apache Maven Verifier](https://maven.apache.org/shared/maven-verifier/) ====================== +> **⚠️ DEPRECATION NOTICE** +> +> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> +> - **New projects**: Please use maven-executor instead +> - **Existing projects**: Please plan migration to maven-executor +> - See [MIGRATION.md](MIGRATION.md) for migration guide +> - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion + [][license] [](https://search.maven.org/artifact/org.apache.maven.shared/maven-verifier) [](https://github.com/jvm-repo-rebuild/reproducible-central/blob/master/content/org/apache/maven/shared/maven-verifier/README.md) diff --git a/pom.xml b/pom.xml index 1721bea..a29805e 100644 --- a/pom.xml +++ b/pom.xml @@ -30,8 +30,14 @@ <artifactId>maven-verifier</artifactId> <version>2.0.0-M2-SNAPSHOT</version> - <name>Apache Maven Verifier Component</name> - <description>Provides a test harness for Maven integration tests.</description> + <name>Apache Maven Verifier Component (Deprecated)</name> + <description> + [DEPRECATED] This component is deprecated and will be replaced by maven-executor. + New projects should use maven-executor (https://github.com/apache/maven/tree/master/impl/maven-executor). + Existing projects should plan migration. See https://github.com/apache/maven-verifier/issues/186 + + Provides a test harness for Maven integration tests. + </description> <contributors> <contributor> @@ -131,6 +137,39 @@ <build> <pluginManagement> <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <configuration> + <showDeprecation>true</showDeprecation> + <compilerArgs> + <arg>-Xlint:deprecation</arg> + </compilerArgs> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <configuration> + <tags> + <tag> + <name>deprecated</name> + <placement>a</placement> + <head>Deprecated:</head> + </tag> + </tags> + <header> + <![CDATA[ + <div style="background-color: #fff3cd; border: 1px solid #ffc107; padding: 10px; margin: 10px 0;"> + <strong>⚠️ Deprecation Notice:</strong> + This component is deprecated. Please use + <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> instead. + See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. + </div> + ]]> + </header> + </configuration> + </plugin> <plugin> <groupId>org.apache.rat</groupId> <artifactId>apache-rat-plugin</artifactId> diff --git a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java index 792bd50..fd7fd4b 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/Embedded3xLauncher.java @@ -40,7 +40,12 @@ import org.apache.maven.shared.utils.io.IOUtil; * Launches an embedded Maven 3.x instance from some Maven installation directory. * * @author Benjamin Bentmann + * @deprecated This class is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a>'s + * {@code EmbeddedExecutor} instead. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) class Embedded3xLauncher implements MavenLauncher { private final Object mavenCli; diff --git a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java index f4a3b73..89a2dc3 100644 --- a/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/ForkedLauncher.java @@ -41,8 +41,15 @@ import org.apache.maven.shared.utils.cli.WriterStreamConsumer; import org.apache.maven.shared.utils.io.FileUtils; /** + * Launcher implementation that forks a new JVM process to execute Maven. + * * @author Benjamin Bentmann + * @deprecated This class is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a>'s + * {@code ForkedExecutor} instead. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) class ForkedLauncher implements MavenLauncher { private final String mavenHome; diff --git a/src/main/java/org/apache/maven/shared/verifier/LauncherException.java b/src/main/java/org/apache/maven/shared/verifier/LauncherException.java index 867e457..2f8f640 100644 --- a/src/main/java/org/apache/maven/shared/verifier/LauncherException.java +++ b/src/main/java/org/apache/maven/shared/verifier/LauncherException.java @@ -19,8 +19,14 @@ package org.apache.maven.shared.verifier; /** + * Exception thrown when Maven launcher encounters an error. + * * @author Benjamin Bentmann + * @deprecated This exception is deprecated along with the MavenLauncher interface. + * When migrating to maven-executor, use standard Java exceptions. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) class LauncherException extends Exception { /** * diff --git a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java index 23c346f..b5cffa6 100644 --- a/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java +++ b/src/main/java/org/apache/maven/shared/verifier/MavenLauncher.java @@ -23,8 +23,15 @@ import java.io.IOException; import java.util.Properties; /** + * Interface for Maven launcher implementations. + * * @author Benjamin Bentmann + * @deprecated This interface is deprecated. Use + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a>'s + * {@code Executor} interface instead. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) interface MavenLauncher { int run(String[] cliArgs, Properties systemProperties, String workingDirectory, File logFile) diff --git a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java index d3a5342..3583140 100644 --- a/src/main/java/org/apache/maven/shared/verifier/VerificationException.java +++ b/src/main/java/org/apache/maven/shared/verifier/VerificationException.java @@ -19,8 +19,15 @@ package org.apache.maven.shared.verifier; /** + * Exception thrown when Maven verification fails. + * * @author Jason van Zyl + * @deprecated This exception is deprecated along with the Verifier class. + * When migrating to maven-executor, use standard Java exceptions + * and check executor exit codes directly. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) public class VerificationException extends Exception { /** * diff --git a/src/main/java/org/apache/maven/shared/verifier/Verifier.java b/src/main/java/org/apache/maven/shared/verifier/Verifier.java index 378ffd0..73d48d4 100644 --- a/src/main/java/org/apache/maven/shared/verifier/Verifier.java +++ b/src/main/java/org/apache/maven/shared/verifier/Verifier.java @@ -79,9 +79,49 @@ import org.xml.sax.SAXParseException; import org.xml.sax.helpers.DefaultHandler; /** + * Maven test harness for integration tests. + * + * <p><strong>DEPRECATION NOTICE:</strong> This class is deprecated and will be removed in a future version. + * Please migrate to + * <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> + * which provides a unified, modern API for programmatic Maven execution with support for both + * Maven 3.9+ and Maven 4+.</p> + * + * <p>Benefits of maven-executor:</p> + * <ul> + * <li>Unified API that doesn't require updates when Maven CLI changes</li> + * <li>Support for both forked and embedded execution modes</li> + * <li>Dependency-less design</li> + * <li>Better environment isolation</li> + * <li>Transparent support for Maven 3.9+ and Maven 4+</li> + * </ul> + * + * <p>Migration example:</p> + * <pre>{@code + * // Old (maven-verifier): + * Verifier verifier = new Verifier("/path/to/project"); + * verifier.addCliArgument("package"); + * verifier.execute(); + * verifier.verifyErrorFreeLog(); + * + * // New (maven-executor): + * Executor executor = new ForkedExecutor(); + * ExecutorRequest request = ExecutorRequest.builder() + * .cwd(Paths.get("/path/to/project")) + * .arguments(List.of("package")) + * .build(); + * int exitCode = executor.execute(request); + * assertEquals(0, exitCode); + * }</pre> + * + * @see <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a> + * @see <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> * @author Jason van Zyl * @author <a href="mailto:[email protected]";>Brett Porter</a> + * @deprecated Use <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a> instead. + * See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) public class Verifier { private static final String LOG_FILENAME = "log.txt"; diff --git a/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java b/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java index befeae8..ebaeecb 100644 --- a/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java +++ b/src/main/java/org/apache/maven/shared/verifier/util/ResourceExtractor.java @@ -32,8 +32,18 @@ import org.apache.maven.shared.utils.io.FileUtils; import org.apache.maven.shared.utils.io.IOUtil; /** - * TODO this can be replaced with plexus-archiver + * Utility for extracting test resources. + * + * <p><strong>Note:</strong> This utility class provides functionality independent of + * Maven execution and could potentially be extracted to a separate, non-deprecated + * utility library if there is community interest.</p> + * + * @deprecated This class is deprecated as part of maven-verifier deprecation. + * The resource extraction functionality may be moved to a separate utility + * library in the future. For now, users should copy this utility if needed. + * See <a href="https://github.com/apache/maven-verifier/issues/186";>Issue #186</a>. */ +@Deprecated(since = "2.0.0", forRemoval = true) public class ResourceExtractor { public static File simpleExtractResources(Class<?> cl, String resourcePath) throws IOException { diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md index 2fb690b..9c45f68 100644 --- a/src/site/markdown/getting-started.md +++ b/src/site/markdown/getting-started.md @@ -19,6 +19,15 @@ # Getting Started +> **⚠️ DEPRECATION NOTICE** +> +> **This project is deprecated and will be replaced by [maven-executor](https://github.com/apache/maven/tree/master/impl/maven-executor).** +> +> - **New projects**: Please use maven-executor instead +> - **Existing projects**: Please plan migration to maven-executor +> - See [Migration Guide](https://github.com/apache/maven-verifier/blob/master/MIGRATION.md) +> - See [Issue #186](https://github.com/apache/maven-verifier/issues/186) for discussion + ## Overview Using the `Verifier` consists out of three different phases diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index f10d5c3..1c512cf 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -19,6 +19,17 @@ # About Apache Maven Verifier Component +<div class="alert alert-warning" role="alert"> + <h4>⚠️ Deprecation Notice</h4> + <p><strong>This project is deprecated and will be replaced by <a href="https://github.com/apache/maven/tree/master/impl/maven-executor";>maven-executor</a>.</strong></p> + <ul> + <li><strong>New projects:</strong> Please use maven-executor instead</li> + <li><strong>Existing projects:</strong> Please plan migration to maven-executor</li> + <li>See <a href="https://github.com/apache/maven-verifier/blob/master/MIGRATION.md";>Migration Guide</a></li> + <li>See <a href="https://github.com/apache/maven-verifier/issues/186";>Issue #186</a> for discussion</li> + </ul> +</div> + Provides a test harness for Maven integration tests. This is a library which can be used in Java-based integration tests. Look at the [Getting Started guide](./getting-started.html) for more information on how to use it. More complex example usages can be found in the the [different integration tests](https://github.com/apache/maven-integration-testing/tree/master/core-it-suite/src/test/java/org/apache/maven/it) of [Maven Core Integration Tests](https://github.com/apache/maven-integration-testing).
