slawekjaranowski commented on code in PR #191: URL: https://github.com/apache/maven-verifier/pull/191#discussion_r2653149828
########## 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; Review Comment: not used in example -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
