You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2020/03/31 12:40:00 UTC
[maven-site-plugin] 01/01: assume Maven 3 as default
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch maven3
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git
commit 24d2e11969f9733ed1bef78bdae79ed68fbfa32b
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Tue Mar 31 08:39:39 2020 -0400
assume Maven 3 as default
---
src/site/apt/maven-3.apt.vm | 361 --------------------------------------------
src/site/site.xml | 1 -
2 files changed, 362 deletions(-)
diff --git a/src/site/apt/maven-3.apt.vm b/src/site/apt/maven-3.apt.vm
deleted file mode 100644
index 3ee7199..0000000
--- a/src/site/apt/maven-3.apt.vm
+++ /dev/null
@@ -1,361 +0,0 @@
- ------
- Using maven-site-plugin with Maven 3
- ------
- Olivier Lamy
- ------
- 2011-07-22
- ------
-
- ~~ 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.
-
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
-
-
-Using maven-site-plugin with Maven 3
-
- A major aim of the refactoring in Maven 3 was to decouple the Maven core from {{{/doxia/}Doxia}}
- and to allow arbitrary reporting systems to be developed. For this reason, all reporting
- related code has been removed from the core of Maven 3
- ({{{https://issues.apache.org/jira/browse/MNG-4162}MNG-4162}}).
-
- As a result, the 2.x versions of the Maven Site Plugin will not work with Maven 3.
- Using such versions of Maven Site Plugin with Maven 3 won't generate any reports from reporting plugins,
- only hand-written Doxia documents (apt, xdoc, ...) will be rendered.
-
- You need to use version 3.x of the Site Plugin, in order for it to work with Maven 3.
-
-%{toc|section=1|fromDepth=2|toDepth=3}
-
-* Plugins Compatibility Matrix for Maven 3
-
-** Plugins Maintained by the Apache Maven Community
-
- Tests have been made on the reporting profile of the Maven parent POM which enables some reports.
- You will need to update some of these plugins for them to work with Maven 3. Below you will find the minimum version
- required for these plugins to work in Maven 3.
-
-*-----------------------------------+-----------+
-| <<Plugin>> |<<Version>>|
-*-----------------------------------+-----------+
-| maven-changelog-plugin | 2.1 |
-*-----------------------------------+-----------+
-| maven-changes-plugin | 2.1 |
-*-----------------------------------+-----------+
-| maven-checkstyle-plugin | 2.5 |
-*-----------------------------------+-----------+
-| maven-javadoc-plugin | 2.6.1 |
-*-----------------------------------+-----------+
-| maven-jxr-plugin | 2.1 |
-*-----------------------------------+-----------+
-| maven-plugin-plugin | 2.5.1 |
-*-----------------------------------+-----------+
-| maven-pmd-plugin | 2.4 |
-*-----------------------------------+-----------+
-| maven-project-info-reports-plugin | 2.2 |
-*-----------------------------------+-----------+
-| maven-surefire-report-plugin | 2.4.3 |
-*-----------------------------------+-----------+
-
-** Plugins Maintained by the Mojo Community
-
-*----------------------------------+-------------+
-| <<Plugin>> |<<Version>> |
-*----------------------------------+-------------+
-| cobertura-maven-plugin | 2.3 |
-*----------------------------------+-------------+
-| emma-maven-plugin | 1.0-alpha-2 |
-*----------------------------------+-------------+
-
-* Version Resolution
-
- When used with Maven 3, a report plugin version can be empty (like build plugins).
-
- The following order/strategy will be used to find/resolve a version:
-
- * search the same groupId/artifactId in the build.plugins section
-
- * search the same groupId/artifactId in the build.pluginManagement.plugins section
-
- * resolve with current repositories (can include automatic SNAPSHOT resolution)
-
- []
-
- Notice that Maven 3.0.x reports a misleading warning in case of empty report plugin version: see
- {{{https://issues.apache.org/jira/browse/MNG-5477}MNG-5477}}, fixed in Maven 3.1.0.
-
-* Site descriptor attachment
-
- In Maven 3, the default execution of <<<site:attach-descriptor>>> has been removed from the
- built-in lifecycle bindings for projects with <<<pom>>> packaging. Users that actually use those
- projects to provide a common site descriptor for sub modules will need to explicitly define
- the following goal execution to restore the intended behavior:
-
-+-----+
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-site-plugin</artifactId>
- <executions>
- <execution>
- <id>attach-descriptor</id>
- <goals>
- <goal>attach-descriptor</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-+-----+
-
-* Using the same version of maven-site-plugin for both Maven 2 and Maven 3
-
- Starting with version 3.0, maven-site-plugin can run with both Maven 2.2.x and 3.x. The
- results should be exactly the same if reports are configured in the classical Maven 2 way, in the <<<\<reporting\>>>>
- section. If you use the new Maven 3 way of configuring reports (not recommended), in the <<<\<reportPlugins\>>>> section,
- it will only work with Maven 3.
-
- The following snippet automatically activates <<<site:attach-descriptor>>> when run with Maven 3:
-
-+-----+
- <profiles>
- <profile>
- <id>maven-3</id>
- <activation>
- <file>
- <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
- <exists>${basedir}</exists>
- </file>
- </activation>
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-site-plugin</artifactId>
- <executions>
- <execution>
- <id>attach-descriptor</id>
- <goals>
- <goal>attach-descriptor</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- </profile>
- </profiles>
-+-----+
-
- <<Note:>> The profile is needed to avoid duplicate install and deploy of the site descriptor when running with Maven 2.2.x
- due to POM default lifecycle mappings.
-
-* Using maven-site-plugin 2.x with Maven 2 and maven-site-plugin 3.x with Maven 3
-
- Before maven-site-plugin 3.0, maven-site-plugin 2.x was compatible only with Maven 2 and maven-site-plugin
- 3.0-betas were compatible only with Maven 3. A trick was needed to let Maven 2 use one version of the plugin and Maven 3
- another version in the same <<<pom.xml>>>.
-
- The following snippet automatically activates maven-site-plugin 3.x when run with Maven 3:
-
-+-----+
- <profiles>
- <profile>
- <id>maven-3</id>
- <activation>
- <file>
- <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) -->
- <exists>${basedir}</exists>
- </file>
- </activation>
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <version>${project.version}</version>
- </plugin>
- </plugins>
- </pluginManagement>
- <plugins>
- <plugin>
- <artifactId>maven-site-plugin</artifactId>
- <executions>
- <execution>
- <id>attach-descriptor</id>
- <goals>
- <goal>attach-descriptor</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- </profile>
- </profiles>
-+-----+
-
- <<Note:>> Be aware that you should also use <<<\<pluginManagement\>>>> to specify the version for maven-site-plugin 2.x.
- If you define the plugin version directly inside the <<<\<plugins\>>>> section of the <<<\<build\>>>> element
- then that version is always used, no matter which version of Maven is used. That snippet would look like this:
-
-+-----+
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <version>2.3</version>
- </plugin>
- </plugins>
- </pluginManagement>
- </build>
-+-----+
-
-* Configuration formats
-
- The <<<\<reporting\>>>> section of the POM has been added to the Site Plugin's configuration as <<<\<reportPlugins\>>>> in Maven 3.
- The content of the configuration has been kept as similar as possible to Maven 2 and
- the <<<{{{/shared/maven-reporting-exec/}maven-reporting-exec}}>>> component transforms the configuration on the fly.
-
-** Classic configuration (Maven 2 & 3)
-
- Reports are configured in the <<<\<reporting\>>>> section of the POM.
- <<This stays the recommended configuration format.>>
-
-+-----+
-<project>
-...
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-project-info-reports-plugin</artifactId>
- <version>2.4</version>
- <configuration>
- <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
- <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
- </configuration>
- <reportSets>
- <reportSet>
- <reports>
- <report>dependencies</report>
- <report>scm</report>
- </reports>
- </reportSet>
- </reportSets>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>2.8</version>
- </plugin>
- </plugins>
- </reporting>
-...
-</project>
-+-----+
-
-** New Configuration (Maven 3 only, no reports configuration inheritance)
-
- Starting with <<<maven-site-plugin>>> 3.0, reports could be configured in the configuration of <<<maven-site-plugin>>>
- as <<<\<reportPlugins\>>>> elements.
-
- <<This new configuration format is not actually ready for end-users: please don't use it for the moment.>>
-
- As a consequence, with <<<maven-site-plugin>>> 3.7, the <<<\<reportPlugins\>>>> configuration has simply been removed
- (and marked marked private/internal since 3.3), and
- {{{https://issues.apache.org/jira/browse/MNG-6189}Maven 3.5.0 prints following warning if <<<\<reportPlugins\>>>> is used}}:
-
-+-----+
-[WARNING] Reporting configuration should be done in <reporting> section, not in maven-site-plugin <configuration> as reportPlugins parameter.
-+-----+
-
- This documentation is kept public only to help people who used <<<\<reportPlugins\>>>> in previous versions
- understand why they need to migrate back to classic configuration, and learn how to switch back to
- {{{Classic_configuration_Maven_2__3}<<<\<reports\><plugins\>>>> classic configuration}}.
-
- <Explanation:> The (former) new format did not support report plugins configuration inheritance, which is crucial for
- usability: see {{{https://issues.apache.org/jira/browse/MSITE-484}MSITE-484}}. This field is technically necessary to remove
- most reporting logic from Maven 3, but a new inheritance mechanism still needs to be added to make it as flexible as the old format:
- we made the field public before finding this crucial limitation and required to explain later why end-users must not use it, then
- cannot use it since <<<maven-site-plugin>>> 3.3.
-
- Here is how this feature looked like:
-
-+-----+
-<project>
-...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
- <version>3.2</version><!-- last maven-site-plugin version supporting this reportPlugins configuration -->
- <configuration>
- ...
- <reportPlugins><!-- not supported any more, causes WARNING in Maven 3.5.0: move to <project><reporting><plugins> instead -->
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-project-info-reports-plugin</artifactId>
- <version>2.4</version>
- <configuration>
- <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
- <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
- </configuration>
- <!-- simpler configuration without reportSets available for usual cases -->
- <reports>
- <report>dependencies</report>
- <report>scm</report>
- </reports>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-javadoc-plugin</artifactId>
- <version>2.8</version>
- </plugin>
- </reportPlugins>
- </configuration>
- </plugin>
- </plugins>
- </build>
-...
-</project>
-+-----+
-
-* Inheritance of reports for Maven 3 before 3.0.4
-
- Maven 3 before 3.0.4 works differently from Maven 2 when dealing with inheritance of reports: given
- a plugin providing multiple report goals, in Maven 2,
- reports configured in child pom are added to reports from parent, whereas in Maven 3 up to 3.0.3
- reports from child replace reports from parent. Since 3.0.4, though, inheritance of reports works
- in the same way as with Maven 2.
-
- For example, given a multi module build where the parent POM has the <<<index>>> report
- configured and the child POM has the <<<summary>>> report configured for
- <<<maven-project-info-reports-plugin>>> plugin:
-
- * with Maven 2 and Maven 3.0.4, the child site will have both the <<<index>>> and <<<summary>>> reports,
-
- * with Maven 3.0.3, the child site will have only the <<<summary>>> report.
-
- []
-
- For more info see {{{https://issues.apache.org/jira/browse/MSITE-596}MSITE-596}}.
diff --git a/src/site/site.xml b/src/site/site.xml
index b5be51e..68ffbc7 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -30,7 +30,6 @@ under the License.
<item name="FAQ" href="faq.html"/>
<item name="History" href="history.html"/>
<item name="Migrate" href="migrate.html"/>
- <item name="Maven 3" href="maven-3.html"/>
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
<item name="License" href="http://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>