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:39:59 UTC
[maven-site-plugin] branch maven3 created (now 24d2e11)
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a change to branch maven3
in repository https://gitbox.apache.org/repos/asf/maven-site-plugin.git.
at 24d2e11 assume Maven 3 as default
This branch includes the following new commits:
new 24d2e11 assume Maven 3 as default
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-site-plugin] 01/01: assume Maven 3 as default
Posted by el...@apache.org.
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"/>