svn commit: r1135905 - in /maven/site/trunk: pom.xml src/site/apt/developers/release/maven-shared-release.apt src/site/apt/pom.apt

[bi...@apache.org]

Author: bimargulies
Date: Wed Jun 15 03:02:17 2011
New Revision: 1135905

URL: http://svn.apache.org/viewvc?rev=1135905&view=rev
Log:
[MNG-5108]: add doc for the the plugin configuration control options to the pom doc

Modified:
    maven/site/trunk/pom.xml
    maven/site/trunk/src/site/apt/developers/release/maven-shared-release.apt
    maven/site/trunk/src/site/apt/pom.apt

Modified: maven/site/trunk/pom.xml
URL: http://svn.apache.org/viewvc/maven/site/trunk/pom.xml?rev=1135905&r1=1135904&r2=1135905&view=diff
==============================================================================
--- maven/site/trunk/pom.xml (original)
+++ maven/site/trunk/pom.xml Wed Jun 15 03:02:17 2011
@@ -23,7 +23,7 @@
   <parent>
     <groupId>org.apache.maven</groupId>
     <artifactId>maven-parent</artifactId>
-    <version>20-SNAPSHOT</version>
+    <version>21-SNAPSHOT</version>
     <relativePath>../pom/maven/pom.xml</relativePath>
   </parent>
 

Modified: maven/site/trunk/src/site/apt/developers/release/maven-shared-release.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/developers/release/maven-shared-release.apt?rev=1135905&r1=1135904&r2=1135905&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/developers/release/maven-shared-release.apt (original)
+++ maven/site/trunk/src/site/apt/developers/release/maven-shared-release.apt Wed Jun 15 03:02:17 2011
@@ -83,9 +83,12 @@ find . -type f -exec chmod 664 {} \;
  <<Note:>> Be sure to generate and deploy the site using the same version of the release. Typically, you need to check
  out the tag (or go to <<<target/checkout>>>)
 
+You will need to have your people.apache.org credentials in your settings.xml, and you may have to 
+explicitly specify the server ID on the command line to persuade maven to use them.
+
 +-----+
 cd target/checkout
-mvn site-deploy -Preporting
+mvn site-deploy -Preporting -DstagingRepositoryId=apache.website
 +-----+
 
   <<Note:>> You can not just copy the documentation from the staging site above into the released documentation as the links are not identical.

Modified: maven/site/trunk/src/site/apt/pom.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/pom.apt?rev=1135905&r1=1135904&r2=1135905&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/pom.apt (original)
+++ maven/site/trunk/src/site/apt/pom.apt Wed Jun 15 03:02:17 2011
@@ -787,6 +787,124 @@ mvn install:install-file -Dfile=non-mave
   values within a <<<configuration>>> element are never explicitly required by the POM schema, but a plugin goal
   has every right to require configuration values.
 
+  If your POM declares a parent, it will inherit plugin configuration from either the 
+  <<build/plugins>> or <<pluginManagement>> sections of the parent. 
+
+  To illustrate, consider the following fragment from a parent POM:
+
++-----------------------------------------------+
+<plugin>
+<groupId>my.group</groupId>
+<artifactId>my-plugin</artifactId>
+<configuration>
+  <items>
+    <item>parent-1</item>
+    <item>parent-2</item>
+  </items>
+  <properties>
+    <parentKey>parent</parentKey>
+  </properties>
+</configuration>
+</plugin>
++-----------------------------------------------+
+
+  And consider the following plugin configuration from a project that uses that parent
+  as its parent:
+
++-----------------------------------------------+
+<plugin>
+<groupId>my.group</groupId>
+<artifactId>my-plugin</artifactId>
+<configuration>
+  <items>
+    <item>child-1</item>
+  </items>
+  <properties>
+    <childKey>child</childKey>
+  </properties>
+</configuration>
++-----------------------------------------------+
+
+  The default behavior is to merge the content of the <<configuration>>
+  element according to element name. If the child POM has a particular
+  element, that value becomes the effective value. if the child POM
+  does not have an element, but the parent does, the parent value
+  becomes the effective value. Note that this is purely an operation on XML;
+  no code or configuration of the plugin itself is involved. Only the 
+  elements, not their values, are involved.
+
+  Applying those rules to the example, Maven comes up with:
+
++-----------------------------------------------+
+<plugin>
+<groupId>my.group</groupId>
+<artifactId>my-plugin</artifactId>
+<configuration>
+  <items>
+    <item>child-1</item>
+  </items>
+  <properties>
+    <childKey>child</childKey>
+    <parentKey>parent</parentKey>
+  </properties>
+</configuration>
++-----------------------------------------------+
+
+  You can control how child POMs inherit configuration from parent POMs by adding attributes
+  to the children of the <<configuration>> element. The attributes are <<<combine.children>>> and
+  <<<combine.self>>>. Use these attributes in a child POM to control how Maven combines 
+  plugin configuration from the parent with the explicit configuration in the child.
+
+  Here is the child configuration with illustrations of the two attributes:
+
++-----------------------------------------------+
+<configuration>
+  <items combine.children="append">
+    <!-- combine.children="merge" is the default -->
+    <item>child-1</item>
+  </items>
+  <properties combine.self="override">
+    <!-- combine.self="merge" is the default -->
+    <childKey>child</childKey>
+  </properties>
+</configuration>
++-----------------------------------------------+
+
+  Now, the effective result is the following:
+
++-----------------------------------------------+
+<configuration>
+  <items combine.children="append">
+    <item>parent-1</item>
+    <item>parent-2</item>
+    <item>child-1</item>
+  </items>
+  <properties combine.self="override">
+    <childKey>child</childKey>
+  </properties>
+</configuration>
++-----------------------------------------------+
+
+  <<combine.children="append">> results in the
+  concatenation of parent and child elements, in that order. 
+  <<combine.self="override">>, on the other hand, completely
+  suppresses parent configuration. You cannot use both
+  both <<combine.self="override">>
+  and <<combine.children="append">> on an element; if you try,
+  <override> will prevail.
+
+  Note that these attributes only apply to the configuration element
+  they are declared on, and are not propagated to nested elements. That
+  is if the content of an <item> element from the child POM was a complex
+  structure instead of text, its sub-elements would still be
+  subject to the default merge strategy unless they were themselves
+  marked with attributes.
+
+  The combine.* attributes are inherited from parent to child POMs.
+  Take care when adding those attributes 
+  a parent POM as this might affect child or
+  grand-child POMs.
+
   * <<dependencies>>:
   Dependencies are seen a lot within the POM, and are an element under all plugins element blocks.
   The dependencies have the same structure and function as under that base build.