[MNG-7598] Enforce binary backwards-compatibility (#874)

For now only enabled in core and plugin-api

Co-authored-by: Guillaume Nodet <gnodet@gmail.com>

maven-core/pom.xml

@@ -274,6 +274,45 @@ under the License.
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <configuration>
+          <parameter>
+            <!-- allowed non-binary backwards compatible changes -->
+            <excludes>
+              <!-- START default constructor on Plexus/JSR 330 components -->
+              <exclude>org.apache.maven.lifecycle.DefaultLifecycleExecutor#DefaultLifecycleExecutor()</exclude>
+              <exclude>org.apache.maven.plugin.DefaultBuildPluginManager#DefaultBuildPluginManager()</exclude>
+              <exclude>org.apache.maven.project.DefaultMavenProjectHelper#DefaultMavenProjectHelper()</exclude>
+              <exclude>org.apache.maven.project.DefaultProjectBuilder#DefaultProjectBuilder()</exclude>
+              <exclude>org.apache.maven.project.DefaultProjectBuildingHelper#DefaultProjectBuildingHelper()</exclude>
+              <exclude>org.apache.maven.project.DefaultProjectDependenciesResolver#DefaultProjectDependenciesResolver()</exclude>
+              <exclude>org.apache.maven.rtinfo.internal.DefaultRuntimeInformation#DefaultRuntimeInformation()</exclude>
+              <exclude>org.apache.maven.settings.DefaultMavenSettingsBuilder#DefaultMavenSettingsBuilder()</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchainManager#DefaultToolchainManager():CONSTRUCTOR_REMOVED</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchainManagerPrivate#DefaultToolchainManagerPrivate()</exclude>
+              <!-- END default constructor on Plexus/JSR 330 components -->
+              <!-- system property with that name no longer evaluated -->
+              <exclude>org.apache.maven.project.DefaultProjectBuilder#DISABLE_GLOBAL_MODEL_CACHE_SYSTEM_PROPERTY</exclude>
+              <!-- was only a workaround for Plexus Container, hopefully never used by anyone else -->
+              <exclude>org.apache.maven.plugin.DefaultBuildPluginManager#setMojoExecutionListeners(java.util.List)</exclude>
+              <!-- could have never been used due to usage of non-export class (CoreExportsProvider) -->
+              <exclude>org.apache.maven.classrealm.DefaultClassRealmManager#DefaultClassRealmManager(org.codehaus.plexus.logging.Logger,org.codehaus.plexus.PlexusContainer,java.util.List,org.apache.maven.extension.internal.CoreExportsProvider)</exclude>
+              <!-- internal field removed -->
+              <exclude>org.apache.maven.graph.DefaultGraphBuilder#projectBuilder</exclude>
+              <!-- MavenPluginValidator has been transformed into an interface -->
+              <exclude>org.apache.maven.plugin.MavenPluginValidator</exclude>
+              <!-- Remove plexus logger -->
+              <exclude>org.apache.maven.plugin.PluginParameterExpressionEvaluator#PluginParameterExpressionEvaluator(org.apache.maven.execution.MavenSession,org.apache.maven.plugin.MojoExecution,org.apache.maven.project.path.PathTranslator,org.codehaus.plexus.logging.Logger,org.apache.maven.project.MavenProject,java.util.Properties):CONSTRUCTOR_REMOVED</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchain#getLog():METHOD_RETURN_TYPE_CHANGED</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchain#DefaultToolchain(org.apache.maven.toolchain.model.ToolchainModel,org.codehaus.plexus.logging.Logger):CONSTRUCTOR_REMOVED</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchain#DefaultToolchain(org.apache.maven.toolchain.model.ToolchainModel,java.lang.String,org.codehaus.plexus.logging.Logger):CONSTRUCTOR_REMOVED</exclude>
+              <exclude>org.apache.maven.toolchain.DefaultToolchainManager#logger</exclude>
+            </excludes>
+          </parameter>
+        </configuration>
+      </plugin>
     </plugins>
   </build>
 </project>

maven-core/src/main/java/org/apache/maven/execution/DefaultMavenExecutionRequestPopulator.java

@@ -235,7 +235,7 @@ public class DefaultMavenExecutionRequestPopulator implements MavenExecutionRequ
         request.setActiveProfiles(settings.getActiveProfiles());
 
         for (org.apache.maven.settings.Profile rawProfile : settings.getProfiles()) {
-            request.addProfile(SettingsUtils.convertFromSettingsProfile(rawProfile.getDelegate()));
+            request.addProfile(SettingsUtils.convertFromSettingsProfile(rawProfile));
 
             if (settings.getActiveProfiles().contains(rawProfile.getId())) {
                 List<Repository> remoteRepositories = rawProfile.getRepositories();

maven-core/src/main/java/org/apache/maven/execution/MavenSession.java

@@ -30,6 +30,7 @@ import java.util.stream.Collectors;
 import org.apache.maven.api.Session;
 import org.apache.maven.artifact.repository.ArtifactRepository;
 import org.apache.maven.artifact.repository.RepositoryCache;
+import org.apache.maven.model.Profile;
 import org.apache.maven.monitor.event.EventDispatcher;
 import org.apache.maven.plugin.descriptor.PluginDescriptor;
 import org.apache.maven.project.MavenProject;
@@ -38,7 +39,7 @@ import org.apache.maven.settings.Mirror;
 import org.apache.maven.settings.Proxy;
 import org.apache.maven.settings.Server;
 import org.apache.maven.settings.Settings;
-import org.apache.maven.settings.SettingsUtils;
+import org.apache.maven.settings.SettingsUtilsV4;
 import org.codehaus.plexus.PlexusContainer;
 import org.codehaus.plexus.component.repository.exception.ComponentLookupException;
 import org.eclipse.aether.RepositorySystemSession;
@@ -372,7 +373,8 @@ public class MavenSession implements Cloneable {
                 .servers(request.getServers().stream().map(Server::getDelegate).collect(Collectors.toList()))
                 .mirrors(request.getMirrors().stream().map(Mirror::getDelegate).collect(Collectors.toList()))
                 .profiles(request.getProfiles().stream()
-                        .map(SettingsUtils::convertToSettingsProfile)
+                        .map(Profile::getDelegate)
+                        .map(SettingsUtilsV4::convertToSettingsProfile)
                         .collect(Collectors.toList()))
                 .activeProfiles(request.getActiveProfiles())
                 .pluginGroups(request.getPluginGroups())

maven-core/src/main/java/org/apache/maven/graph/DefaultGraphBuilder.java

@@ -68,6 +68,15 @@ public class DefaultGraphBuilder implements GraphBuilder {
     private final RequestPomCollectionStrategy requestPomCollectionStrategy;
     private final ProjectSelector projectSelector;
 
+    /**
+     * @deprecated Use {@link #DefaultGraphBuilder(BuildResumptionDataRepository, PomlessCollectionStrategy,
+     * MultiModuleCollectionStrategy, RequestPomCollectionStrategy)} instead or rely on JSR 330
+     */
+    @Deprecated
+    public DefaultGraphBuilder() {
+        this(null, null, null, null);
+    }
+
     @Inject
     public DefaultGraphBuilder(
             BuildResumptionDataRepository buildResumptionDataRepository,

maven-core/src/main/java/org/apache/maven/graph/DefaultProjectDependencyGraph.java

@@ -70,6 +70,22 @@ public class DefaultProjectDependencyGraph implements ProjectDependencyGraph {
      * @throws DuplicateProjectException
      * @throws CycleDetectedException
      * @since 3.5.0
+     * @deprecated Use {@link #DefaultProjectDependencyGraph(Collection, Collection)} instead.
+     */
+    @Deprecated
+    public DefaultProjectDependencyGraph(List<MavenProject> allProjects, Collection<MavenProject> projects)
+            throws CycleDetectedException, DuplicateProjectException {
+        this((Collection<MavenProject>) allProjects, projects);
+    }
+
+    /**
+     * Creates a new project dependency graph based on the specified projects.
+     *
+     * @param allProjects All collected projects.
+     * @param projects    The projects to create the dependency graph with.
+     * @throws DuplicateProjectException
+     * @throws CycleDetectedException
+     * @since 4.0.0
      */
     public DefaultProjectDependencyGraph(Collection<MavenProject> allProjects, Collection<MavenProject> projects)
             throws CycleDetectedException, DuplicateProjectException {

maven-core/src/main/java/org/apache/maven/lifecycle/DefaultLifecycleExecutor.java

@@ -20,6 +20,7 @@ package org.apache.maven.lifecycle;
 
 import java.util.Arrays;
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 import javax.inject.Inject;
 import javax.inject.Named;
@@ -103,6 +104,13 @@ public class DefaultLifecycleExecutor implements LifecycleExecutor {
         return lifeCyclePluginAnalyzer.getPluginsBoundByDefaultToAllLifecycles(packaging);
     }
 
+    // USED BY MAVEN HELP PLUGIN
+
+    @Deprecated
+    public Map<String, Lifecycle> getPhaseToLifecycleMap() {
+        return defaultLifeCycles.getPhaseToLifecycleMap();
+    }
+
     // Used by m2eclipse
 
     @SuppressWarnings({"UnusedDeclaration"})

maven-core/src/main/java/org/apache/maven/lifecycle/DefaultLifecycles.java

@@ -51,10 +51,21 @@ public class DefaultLifecycles {
 
     private final PlexusContainer plexusContainer;
 
+    private Map<String, Lifecycle> customLifecycles;
+
     public DefaultLifecycles() {
         this.plexusContainer = null;
     }
 
+    /**
+     * @deprecated Rely on {@link #DefaultLifecycles(PlexusContainer)} instead
+     */
+    @Deprecated
+    public DefaultLifecycles(Map<String, Lifecycle> lifecycles, org.codehaus.plexus.logging.Logger logger) {
+        this.customLifecycles = lifecycles;
+        this.plexusContainer = null;
+    }
+
     @Inject
     public DefaultLifecycles(PlexusContainer plexusContainer) {
         this.plexusContainer = plexusContainer;
@@ -132,7 +143,7 @@ public class DefaultLifecycles {
         // TODO: Remove the following code when maven-compat is gone
         // This code is here to ensure maven-compat's EmptyLifecycleExecutor keeps on working.
         if (plexusContainer == null) {
-            return new HashMap<>();
+            return customLifecycles != null ? customLifecycles : new HashMap<>();
         }
 
         // Lifecycles cannot be cached as extensions might add custom lifecycles later in the execution.

maven-core/src/main/java/org/apache/maven/plugin/CycleDetectedInPluginGraphException.java

@@ -18,7 +18,7 @@
  */
 package org.apache.maven.plugin;
 
-import org.apache.maven.api.model.Plugin;
+import org.apache.maven.model.Plugin;
 import org.codehaus.plexus.component.composition.CycleDetectedInComponentGraphException;
 
 /**

maven-core/src/main/java/org/apache/maven/plugin/DebugConfigurationListener.java

@@ -21,6 +21,7 @@ package org.apache.maven.plugin;
 import java.lang.reflect.Array;
 import org.codehaus.plexus.component.configurator.ConfigurationListener;
 import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Log at debug level the mojo configuration.
@@ -31,6 +32,14 @@ import org.slf4j.Logger;
 public class DebugConfigurationListener implements ConfigurationListener {
     private final Logger logger;
 
+    /**
+     * @deprecated Use {@link #DebugConfigurationListener(Logger)} instead.
+     */
+    @Deprecated
+    public DebugConfigurationListener(org.codehaus.plexus.logging.Logger logger) {
+        this(LoggerFactory.getLogger(logger.getName()));
+    }
+
     public DebugConfigurationListener(Logger logger) {
         this.logger = logger;
     }

maven-core/src/main/java/org/apache/maven/plugin/MavenPluginManager.java

@@ -66,10 +66,20 @@ public interface MavenPluginManager {
             throws MojoNotFoundException, PluginResolutionException, PluginDescriptorParsingException,
                     InvalidPluginDescriptorException;
 
+    /**
+     * Verifies the specified plugin is compatible with the current Maven runtime.
+     *
+     * @param pluginDescriptor The descriptor of the plugin to check, must not be {@code null}.
+     * @deprecated Use {@link #checkPrerequisites(PluginDescriptor)} instead.
+     */
+    @Deprecated
+    void checkRequiredMavenVersion(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException;
+
     /**
      * Verifies that the specified plugin's prerequisites are met.
      *
      * @param pluginDescriptor The descriptor of the plugin to check, must not be {@code null}.
+     * @since 4.0.0
      */
     void checkPrerequisites(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException;
 

maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java

@@ -306,6 +306,12 @@ public class DefaultMavenPluginManager implements MavenPluginManager {
         }
     }
 
+    @Override
+    @Deprecated
+    public void checkRequiredMavenVersion(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException {
+        checkPrerequisites(pluginDescriptor);
+    }
+
     public void setupPluginRealm(
             PluginDescriptor pluginDescriptor,
             MavenSession session,

maven-core/src/main/java/org/apache/maven/settings/SettingsUtils.java

@@ -18,19 +18,6 @@
  */
 package org.apache.maven.settings;
 
-import java.util.ArrayList;
-import java.util.List;
-import java.util.stream.Collectors;
-import org.apache.maven.api.model.ActivationFile;
-import org.apache.maven.api.settings.Activation;
-import org.apache.maven.api.settings.ActivationOS;
-import org.apache.maven.api.settings.ActivationProperty;
-import org.apache.maven.api.settings.Profile;
-import org.apache.maven.api.settings.Repository;
-import org.apache.maven.api.settings.RepositoryPolicy;
-import org.apache.maven.api.settings.Settings;
-import org.apache.maven.settings.merge.MavenSettingsMerger;
-
 /**
  * Several convenience methods to handle settings
  *
@@ -47,8 +34,10 @@ public final class SettingsUtils {
      * @param recessive
      * @param recessiveSourceLevel
      */
-    public static Settings merge(Settings dominant, Settings recessive, String recessiveSourceLevel) {
+    public static void merge(Settings dominant, Settings recessive, String recessiveSourceLevel) {
-        return new MavenSettingsMerger().merge(dominant, recessive, recessiveSourceLevel);
+        if (dominant != null && recessive != null) {
+            dominant.delegate = SettingsUtilsV4.merge(dominant.getDelegate(), recessive.getDelegate());
+        }
     }
 
     /**
@@ -56,80 +45,7 @@ public final class SettingsUtils {
      * @return a profile
      */
     public static Profile convertToSettingsProfile(org.apache.maven.model.Profile modelProfile) {
-        Profile.Builder profile = Profile.newBuilder();
+        return new Profile(SettingsUtilsV4.convertToSettingsProfile(modelProfile.getDelegate()));
-
-        profile.id(modelProfile.getId());
-
-        org.apache.maven.model.Activation modelActivation = modelProfile.getActivation();
-
-        if (modelActivation != null) {
-            Activation.Builder activation = Activation.newBuilder();
-
-            activation.activeByDefault(modelActivation.isActiveByDefault());
-
-            activation.jdk(modelActivation.getJdk());
-
-            org.apache.maven.model.ActivationProperty modelProp = modelActivation.getProperty();
-
-            if (modelProp != null) {
-                ActivationProperty prop = ActivationProperty.newBuilder()
-                        .name(modelProp.getName())
-                        .value(modelProp.getValue())
-                        .build();
-                activation.property(prop);
-            }
-
-            org.apache.maven.model.ActivationOS modelOs = modelActivation.getOs();
-
-            if (modelOs != null) {
-                ActivationOS os = ActivationOS.newBuilder()
-                        .arch(modelOs.getArch())
-                        .family(modelOs.getFamily())
-                        .name(modelOs.getName())
-                        .version(modelOs.getVersion())
-                        .build();
-
-                activation.os(os);
-            }
-
-            org.apache.maven.model.ActivationFile modelFile = modelActivation.getFile();
-
-            if (modelFile != null) {
-                org.apache.maven.api.settings.ActivationFile file =
-                        org.apache.maven.api.settings.ActivationFile.newBuilder()
-                                .exists(modelFile.getExists())
-                                .missing(modelFile.getMissing())
-                                .build();
-
-                activation.file(file);
-            }
-
-            profile.activation(activation.build());
-        }
-
-        profile.properties(modelProfile.getProperties().entrySet().stream()
-                .collect(Collectors.toMap(
-                        e -> e.getKey().toString(), e -> e.getValue().toString())));
-
-        List<org.apache.maven.model.Repository> repos = modelProfile.getRepositories();
-        if (repos != null) {
-            List<Repository> repositories = new ArrayList<>();
-            for (org.apache.maven.model.Repository repo : repos) {
-                repositories.add(convertToSettingsRepository(repo));
-            }
-            profile.repositories(repositories);
-        }
-
-        List<org.apache.maven.model.Repository> pluginRepos = modelProfile.getPluginRepositories();
-        if (pluginRepos != null) {
-            List<Repository> repositories = new ArrayList<>();
-            for (org.apache.maven.model.Repository pluginRepo : pluginRepos) {
-                repositories.add(convertToSettingsRepository(pluginRepo));
-            }
-            profile.pluginRepositories(repositories);
-        }
-
-        return profile.build();
     }
 
     /**
@@ -137,144 +53,32 @@ public final class SettingsUtils {
      * @return a profile
      */
     public static org.apache.maven.model.Profile convertFromSettingsProfile(Profile settingsProfile) {
-        org.apache.maven.api.model.Profile.Builder profile = org.apache.maven.api.model.Profile.newBuilder();
+        return new org.apache.maven.model.Profile(
-
+                SettingsUtilsV4.convertFromSettingsProfile(settingsProfile.getDelegate()));
-        profile.id(settingsProfile.getId());
-
-        Activation settingsActivation = settingsProfile.getActivation();
-
-        if (settingsActivation != null) {
-            org.apache.maven.api.model.Activation.Builder activation =
-                    org.apache.maven.api.model.Activation.newBuilder();
-
-            activation.activeByDefault(settingsActivation.isActiveByDefault());
-
-            activation.jdk(settingsActivation.getJdk());
-
-            ActivationProperty settingsProp = settingsActivation.getProperty();
-            if (settingsProp != null) {
-                activation.property(org.apache.maven.api.model.ActivationProperty.newBuilder()
-                        .name(settingsProp.getName())
-                        .value(settingsProp.getValue())
-                        .build());
-            }
-
-            ActivationOS settingsOs = settingsActivation.getOs();
-            if (settingsOs != null) {
-                activation.os(org.apache.maven.api.model.ActivationOS.newBuilder()
-                        .arch(settingsOs.getArch())
-                        .family(settingsOs.getFamily())
-                        .name(settingsOs.getName())
-                        .version(settingsOs.getVersion())
-                        .build());
-            }
-
-            org.apache.maven.api.settings.ActivationFile settingsFile = settingsActivation.getFile();
-            if (settingsFile != null) {
-                activation.file(ActivationFile.newBuilder()
-                        .exists(settingsFile.getExists())
-                        .missing(settingsFile.getMissing())
-                        .build());
-            }
-
-            profile.activation(activation.build());
-        }
-
-        profile.properties(settingsProfile.getProperties());
-
-        List<Repository> repos = settingsProfile.getRepositories();
-        if (repos != null) {
-            profile.repositories(repos.stream()
-                    .map(SettingsUtils::convertFromSettingsRepository)
-                    .collect(Collectors.toList()));
-        }
-
-        List<Repository> pluginRepos = settingsProfile.getPluginRepositories();
-        if (pluginRepos != null) {
-            profile.pluginRepositories(pluginRepos.stream()
-                    .map(SettingsUtils::convertFromSettingsRepository)
-                    .collect(Collectors.toList()));
-        }
-
-        org.apache.maven.model.Profile value = new org.apache.maven.model.Profile(profile.build());
-        value.setSource("settings.xml");
-        return value;
-    }
-
-    /**
-     * @param settingsRepo
-     * @return a repository
-     */
-    private static org.apache.maven.api.model.Repository convertFromSettingsRepository(Repository settingsRepo) {
-        org.apache.maven.api.model.Repository.Builder repo = org.apache.maven.api.model.Repository.newBuilder();
-
-        repo.id(settingsRepo.getId());
-        repo.layout(settingsRepo.getLayout());
-        repo.name(settingsRepo.getName());
-        repo.url(settingsRepo.getUrl());
-
-        if (settingsRepo.getSnapshots() != null) {
-            repo.snapshots(convertRepositoryPolicy(settingsRepo.getSnapshots()));
-        }
-        if (settingsRepo.getReleases() != null) {
-            repo.releases(convertRepositoryPolicy(settingsRepo.getReleases()));
-        }
-
-        return repo.build();
-    }
-
-    /**
-     * @param settingsPolicy
-     * @return a RepositoryPolicy
-     */
-    private static org.apache.maven.api.model.RepositoryPolicy convertRepositoryPolicy(
-            RepositoryPolicy settingsPolicy) {
-        org.apache.maven.api.model.RepositoryPolicy policy = org.apache.maven.api.model.RepositoryPolicy.newBuilder()
-                .enabled(Boolean.toString(settingsPolicy.isEnabled()))
-                .updatePolicy(settingsPolicy.getUpdatePolicy())
-                .checksumPolicy(settingsPolicy.getChecksumPolicy())
-                .build();
-        return policy;
-    }
-
-    /**
-     * @param modelRepo
-     * @return a repository
-     */
-    private static Repository convertToSettingsRepository(org.apache.maven.model.Repository modelRepo) {
-        Repository repo = Repository.newBuilder()
-                .id(modelRepo.getId())
-                .layout(modelRepo.getLayout())
-                .name(modelRepo.getName())
-                .url(modelRepo.getUrl())
-                .snapshots(modelRepo.getSnapshots() != null ? convertRepositoryPolicy(modelRepo.getSnapshots()) : null)
-                .releases(modelRepo.getReleases() != null ? convertRepositoryPolicy(modelRepo.getReleases()) : null)
-                .build();
-
-        return repo;
-    }
-
-    /**
-     * @param modelPolicy
-     * @return a RepositoryPolicy
-     */
-    private static RepositoryPolicy convertRepositoryPolicy(org.apache.maven.model.RepositoryPolicy modelPolicy) {
-        RepositoryPolicy policy = RepositoryPolicy.newBuilder()
-                .enabled(modelPolicy.isEnabled())
-                .updatePolicy(modelPolicy.getUpdatePolicy())
-                .checksumPolicy(modelPolicy.getUpdatePolicy())
-                .build();
-        return policy;
     }
 
     /**
      * @param settings could be null
      * @return a new instance of settings or null if settings was null.
      */
-    public static org.apache.maven.settings.Settings copySettings(org.apache.maven.settings.Settings settings) {
+    public static Settings copySettings(Settings settings) {
         if (settings == null) {
             return null;
         }
-        return new org.apache.maven.settings.Settings(settings.getDelegate());
+
+        Settings clone = new Settings();
+        clone.setActiveProfiles(settings.getActiveProfiles());
+        clone.setInteractiveMode(settings.isInteractiveMode());
+        clone.setLocalRepository(settings.getLocalRepository());
+        clone.setMirrors(settings.getMirrors());
+        clone.setOffline(settings.isOffline());
+        clone.setPluginGroups(settings.getPluginGroups());
+        clone.setProfiles(settings.getProfiles());
+        clone.setProxies(settings.getProxies());
+        clone.setServers(settings.getServers());
+        clone.setSourceLevel(settings.getSourceLevel());
+        clone.setUsePluginRegistry(settings.isUsePluginRegistry());
+
+        return clone;
     }
 }

maven-core/src/main/java/org/apache/maven/settings/SettingsUtilsV4.java

@@ -0,0 +1,299 @@
+/*
+ * 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.
+ */
+package org.apache.maven.settings;
+
+/*
+ * 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.
+ */
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.apache.maven.api.model.ActivationFile;
+import org.apache.maven.api.settings.Activation;
+import org.apache.maven.api.settings.ActivationOS;
+import org.apache.maven.api.settings.ActivationProperty;
+import org.apache.maven.api.settings.Profile;
+import org.apache.maven.api.settings.Repository;
+import org.apache.maven.api.settings.RepositoryPolicy;
+import org.apache.maven.api.settings.Settings;
+import org.apache.maven.settings.v4.SettingsMerger;
+
+/**
+ * Several convenience methods to handle settings
+ *
+ * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
+ */
+public final class SettingsUtilsV4 {
+
+    private SettingsUtilsV4() {
+        // don't allow construction.
+    }
+
+    /**
+     * @param dominant
+     * @param recessive
+     */
+    public static Settings merge(Settings dominant, Settings recessive) {
+        return new SettingsMerger().merge(dominant, recessive, true, Collections.emptyMap());
+    }
+
+    /**
+     * @param modelProfile
+     * @return a profile
+     */
+    public static Profile convertToSettingsProfile(org.apache.maven.api.model.Profile modelProfile) {
+        Profile.Builder profile = Profile.newBuilder();
+
+        profile.id(modelProfile.getId());
+
+        org.apache.maven.api.model.Activation modelActivation = modelProfile.getActivation();
+
+        if (modelActivation != null) {
+            Activation.Builder activation = Activation.newBuilder();
+
+            activation.activeByDefault(modelActivation.isActiveByDefault());
+
+            activation.jdk(modelActivation.getJdk());
+
+            org.apache.maven.api.model.ActivationProperty modelProp = modelActivation.getProperty();
+
+            if (modelProp != null) {
+                ActivationProperty prop = ActivationProperty.newBuilder()
+                        .name(modelProp.getName())
+                        .value(modelProp.getValue())
+                        .build();
+                activation.property(prop);
+            }
+
+            org.apache.maven.api.model.ActivationOS modelOs = modelActivation.getOs();
+
+            if (modelOs != null) {
+                ActivationOS os = ActivationOS.newBuilder()
+                        .arch(modelOs.getArch())
+                        .family(modelOs.getFamily())
+                        .name(modelOs.getName())
+                        .version(modelOs.getVersion())
+                        .build();
+
+                activation.os(os);
+            }
+
+            org.apache.maven.api.model.ActivationFile modelFile = modelActivation.getFile();
+
+            if (modelFile != null) {
+                org.apache.maven.api.settings.ActivationFile file =
+                        org.apache.maven.api.settings.ActivationFile.newBuilder()
+                                .exists(modelFile.getExists())
+                                .missing(modelFile.getMissing())
+                                .build();
+
+                activation.file(file);
+            }
+
+            profile.activation(activation.build());
+        }
+
+        profile.properties(modelProfile.getProperties().entrySet().stream()
+                .collect(Collectors.toMap(
+                        e -> e.getKey().toString(), e -> e.getValue().toString())));
+
+        List<org.apache.maven.api.model.Repository> repos = modelProfile.getRepositories();
+        if (repos != null) {
+            List<Repository> repositories = new ArrayList<>();
+            for (org.apache.maven.api.model.Repository repo : repos) {
+                repositories.add(convertToSettingsRepository(repo));
+            }
+            profile.repositories(repositories);
+        }
+
+        List<org.apache.maven.api.model.Repository> pluginRepos = modelProfile.getPluginRepositories();
+        if (pluginRepos != null) {
+            List<Repository> repositories = new ArrayList<>();
+            for (org.apache.maven.api.model.Repository pluginRepo : pluginRepos) {
+                repositories.add(convertToSettingsRepository(pluginRepo));
+            }
+            profile.pluginRepositories(repositories);
+        }
+
+        return profile.build();
+    }
+
+    /**
+     * @param settingsProfile
+     * @return a profile
+     */
+    public static org.apache.maven.api.model.Profile convertFromSettingsProfile(Profile settingsProfile) {
+        org.apache.maven.api.model.Profile.Builder profile = org.apache.maven.api.model.Profile.newBuilder();
+
+        profile.id(settingsProfile.getId());
+
+        Activation settingsActivation = settingsProfile.getActivation();
+
+        if (settingsActivation != null) {
+            org.apache.maven.api.model.Activation.Builder activation =
+                    org.apache.maven.api.model.Activation.newBuilder();
+
+            activation.activeByDefault(settingsActivation.isActiveByDefault());
+
+            activation.jdk(settingsActivation.getJdk());
+
+            ActivationProperty settingsProp = settingsActivation.getProperty();
+            if (settingsProp != null) {
+                activation.property(org.apache.maven.api.model.ActivationProperty.newBuilder()
+                        .name(settingsProp.getName())
+                        .value(settingsProp.getValue())
+                        .build());
+            }
+
+            ActivationOS settingsOs = settingsActivation.getOs();
+            if (settingsOs != null) {
+                activation.os(org.apache.maven.api.model.ActivationOS.newBuilder()
+                        .arch(settingsOs.getArch())
+                        .family(settingsOs.getFamily())
+                        .name(settingsOs.getName())
+                        .version(settingsOs.getVersion())
+                        .build());
+            }
+
+            org.apache.maven.api.settings.ActivationFile settingsFile = settingsActivation.getFile();
+            if (settingsFile != null) {
+                activation.file(ActivationFile.newBuilder()
+                        .exists(settingsFile.getExists())
+                        .missing(settingsFile.getMissing())
+                        .build());
+            }
+
+            profile.activation(activation.build());
+        }
+
+        profile.properties(settingsProfile.getProperties());
+
+        List<Repository> repos = settingsProfile.getRepositories();
+        if (repos != null) {
+            profile.repositories(repos.stream()
+                    .map(SettingsUtilsV4::convertFromSettingsRepository)
+                    .collect(Collectors.toList()));
+        }
+
+        List<Repository> pluginRepos = settingsProfile.getPluginRepositories();
+        if (pluginRepos != null) {
+            profile.pluginRepositories(pluginRepos.stream()
+                    .map(SettingsUtilsV4::convertFromSettingsRepository)
+                    .collect(Collectors.toList()));
+        }
+
+        org.apache.maven.api.model.Profile value = profile.build();
+        value.setSource("settings.xml");
+        return value;
+    }
+
+    /**
+     * @param settingsRepo
+     * @return a repository
+     */
+    private static org.apache.maven.api.model.Repository convertFromSettingsRepository(Repository settingsRepo) {
+        org.apache.maven.api.model.Repository.Builder repo = org.apache.maven.api.model.Repository.newBuilder();
+
+        repo.id(settingsRepo.getId());
+        repo.layout(settingsRepo.getLayout());
+        repo.name(settingsRepo.getName());
+        repo.url(settingsRepo.getUrl());
+
+        if (settingsRepo.getSnapshots() != null) {
+            repo.snapshots(convertRepositoryPolicy(settingsRepo.getSnapshots()));
+        }
+        if (settingsRepo.getReleases() != null) {
+            repo.releases(convertRepositoryPolicy(settingsRepo.getReleases()));
+        }
+
+        return repo.build();
+    }
+
+    /**
+     * @param settingsPolicy
+     * @return a RepositoryPolicy
+     */
+    private static org.apache.maven.api.model.RepositoryPolicy convertRepositoryPolicy(
+            RepositoryPolicy settingsPolicy) {
+        org.apache.maven.api.model.RepositoryPolicy policy = org.apache.maven.api.model.RepositoryPolicy.newBuilder()
+                .enabled(Boolean.toString(settingsPolicy.isEnabled()))
+                .updatePolicy(settingsPolicy.getUpdatePolicy())
+                .checksumPolicy(settingsPolicy.getChecksumPolicy())
+                .build();
+        return policy;
+    }
+
+    /**
+     * @param modelRepo
+     * @return a repository
+     */
+    private static Repository convertToSettingsRepository(org.apache.maven.api.model.Repository modelRepo) {
+        Repository repo = Repository.newBuilder()
+                .id(modelRepo.getId())
+                .layout(modelRepo.getLayout())
+                .name(modelRepo.getName())
+                .url(modelRepo.getUrl())
+                .snapshots(modelRepo.getSnapshots() != null ? convertRepositoryPolicy(modelRepo.getSnapshots()) : null)
+                .releases(modelRepo.getReleases() != null ? convertRepositoryPolicy(modelRepo.getReleases()) : null)
+                .build();
+
+        return repo;
+    }
+
+    /**
+     * @param modelPolicy
+     * @return a RepositoryPolicy
+     */
+    private static RepositoryPolicy convertRepositoryPolicy(org.apache.maven.api.model.RepositoryPolicy modelPolicy) {
+        RepositoryPolicy policy = RepositoryPolicy.newBuilder()
+                .enabled(modelPolicy.isEnabled())
+                .updatePolicy(modelPolicy.getUpdatePolicy())
+                .checksumPolicy(modelPolicy.getUpdatePolicy())
+                .build();
+        return policy;
+    }
+
+    /**
+     * @param settings could be null
+     * @return a new instance of settings or null if settings was null.
+     */
+    public static org.apache.maven.settings.Settings copySettings(org.apache.maven.settings.Settings settings) {
+        if (settings == null) {
+            return null;
+        }
+        return new org.apache.maven.settings.Settings(settings.getDelegate());
+    }
+}

maven-core/src/main/java/org/apache/maven/toolchain/DefaultToolchainsBuilder.java

@@ -22,7 +22,7 @@ import java.io.File;
 import java.io.Reader;
 import javax.inject.Named;
 import javax.inject.Singleton;
-import org.apache.maven.api.toolchain.PersistedToolchains;
+import org.apache.maven.toolchain.model.PersistedToolchains;
 import org.apache.maven.toolchain.v4.MavenToolchainsXpp3Reader;
 import org.codehaus.plexus.util.ReaderFactory;
 import org.slf4j.Logger;
@@ -43,7 +43,7 @@ public class DefaultToolchainsBuilder implements ToolchainsBuilder {
 
         if (userToolchainsFile != null && userToolchainsFile.isFile()) {
             try (Reader in = ReaderFactory.newXmlReader(userToolchainsFile)) {
-                toolchains = new MavenToolchainsXpp3Reader().read(in);
+                toolchains = new PersistedToolchains(new MavenToolchainsXpp3Reader().read(in));
             } catch (Exception e) {
                 throw new MisconfiguredToolchainException(
                         "Cannot read toolchains file at " + userToolchainsFile.getAbsolutePath(), e);

maven-core/src/main/java/org/apache/maven/toolchain/ToolchainsBuilder.java

@@ -19,7 +19,7 @@
 package org.apache.maven.toolchain;
 
 import java.io.File;
-import org.apache.maven.api.toolchain.PersistedToolchains;
+import org.apache.maven.toolchain.model.PersistedToolchains;
 
 /**
  * Builds the toolchains model from a previously configured filesystem path to the toolchains file.

maven-core/src/test/java/org/apache/maven/settings/PomConstructionWithSettingsTest.java

@@ -97,7 +97,7 @@ public class PomConstructionWithSettingsTest {
         ProjectBuildingRequest config = new DefaultProjectBuildingRequest();
 
         for (org.apache.maven.settings.Profile rawProfile : settings.getProfiles()) {
-            Profile profile = SettingsUtils.convertFromSettingsProfile(rawProfile.getDelegate());
+            Profile profile = SettingsUtils.convertFromSettingsProfile(rawProfile);
             config.addProfile(profile);
         }
 

maven-core/src/test/java/org/apache/maven/settings/SettingsUtilsTest.java

@@ -48,7 +48,7 @@ public class SettingsUtilsTest {
                 .pluginGroups(Arrays.asList("org.codehaus.plexus"))
                 .build();
 
-        Settings merged = SettingsUtils.merge(dominant, recessive, Settings.GLOBAL_LEVEL);
+        Settings merged = SettingsUtilsV4.merge(dominant, recessive);
 
         List<String> pluginGroups = merged.getPluginGroups();
 
@@ -116,7 +116,7 @@ public class SettingsUtilsTest {
                 .pluginRepositories(pluginRepos)
                 .build();
 
-        Profile clone = SettingsUtils.convertToSettingsProfile(SettingsUtils.convertFromSettingsProfile(p));
+        Profile clone = SettingsUtilsV4.convertToSettingsProfile(SettingsUtilsV4.convertFromSettingsProfile(p));
 
         assertEquals(p.getId(), clone.getId());
         assertEquals(p.getActivation().getJdk(), clone.getActivation().getJdk());

maven-embedder/src/main/java/org/apache/maven/cli/configuration/SettingsXmlConfigurationProcessor.java

@@ -202,7 +202,7 @@ public class SettingsXmlConfigurationProcessor implements ConfigurationProcessor
         request.setActiveProfiles(settings.getActiveProfiles());
 
         for (Profile rawProfile : settings.getProfiles()) {
-            request.addProfile(SettingsUtils.convertFromSettingsProfile(rawProfile.getDelegate()));
+            request.addProfile(SettingsUtils.convertFromSettingsProfile(rawProfile));
 
             if (settings.getActiveProfiles().contains(rawProfile.getId())) {
                 List<Repository> remoteRepositories = rawProfile.getRepositories();

maven-plugin-api/pom.xml

@@ -112,6 +112,10 @@ under the License.
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+      </plugin>
     </plugins>
   </build>
 </project>

maven-settings-builder/src/main/java/org/apache/maven/settings/merge/MavenSettingsMerger.java

@@ -33,7 +33,9 @@ import org.codehaus.plexus.util.StringUtils;
 /**
  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
  * @author Benjamin Bentmann
+ * @deprecated use {@link org.apache.maven.settings.v4.SettingsMerger}
  */
+@Deprecated
 public class MavenSettingsMerger {
 
     /**

pom.xml

@@ -560,6 +560,55 @@ under the License.
           <artifactId>buildnumber-maven-plugin</artifactId>
           <version>1.4</version>
         </plugin>
+        <!-- enforce backwards compatibility -->
+        <plugin>
+          <groupId>com.github.siom79.japicmp</groupId>
+          <artifactId>japicmp-maven-plugin</artifactId>
+          <version>0.16.0</version>
+          <executions>
+            <execution>
+              <goals>
+                <goal>cmp</goal>
+              </goals>
+              <phase>verify</phase>
+              <configuration>
+                <parameter>
+                  <!-- baseline is 3.8.6 for Maven 4 -->
+                  <oldVersionPattern>3.8.6</oldVersionPattern>
+                  <breakBuildOnBinaryIncompatibleModifications>true</breakBuildOnBinaryIncompatibleModifications>
+                  <onlyBinaryIncompatible>true</onlyBinaryIncompatible>
+                  <!-- only exported packages from maven-core/META-INF/maven/extension.xml matter  -->
+                  <includes>
+                    <include>org.apache.maven.artifact</include>
+                    <include>org.apache.maven.classrealm</include>
+                    <include>org.apache.maven.cli</include>
+                    <include>org.apache.maven.configuration</include>
+                    <include>org.apache.maven.exception</include>
+                    <include>org.apache.maven.execution</include>
+                    <include>org.apache.maven.execution.scope</include>
+                    <include>org.apache.maven.feature</include>
+                    <include>org.apache.maven.graph</include>
+                    <include>org.apache.maven.lifecycle</include>
+                    <include>org.apache.maven.model</include>
+                    <include>org.apache.maven.monitor</include>
+                    <include>org.apache.maven.plugin</include>
+                    <include>org.apache.maven.profiles</include>
+                    <include>org.apache.maven.project</include>
+                    <include>org.apache.maven.reporting</include>
+                    <include>org.apache.maven.repository</include>
+                    <include>org.apache.maven.rtinfo</include>
+                    <include>org.apache.maven.rtinfo.internal</include>
+                    <include>org.apache.maven.settings</include>
+                    <include>org.apache.maven.toolchain</include>
+                    <include>org.apache.maven.usability</include>
+                  </includes>
+                  <includeExclusively>true</includeExclusively>
+                  <!-- don't include subpackages -->
+                </parameter>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
     </pluginManagement>
     <plugins>