~~ 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.

 -----
 Maven configuration management
 -----
 The Maven Team
 -----

Configuration levels in maven

 In maven configuration control happens on four differ levels: the site level, the group level,
 the project level, and the user level. On the site level you can configure maven for all users
 utilizing the local installation, the group level allows configuration management for all the projects
 that belong to the same group, the project level allows configuration management at
 the project level, and the user level allows users to override settings on
 the site level, group level and project level.

* Site configuration

 At the site level all configuration is achieved by tweaking the the various files that
 are available in the ${maven.home}/site-configuration directory

+-----+
${maven.home}
     |
     +--- maven.properties
+-----+

* Group configuration

 As far as properties go for an entire build the maven.properties could be placed at
 the top of the group but I'm not really sure how this might work. There could probably
 also be a directory for plugins.xml and maven.properties.

* Project configuration

 At the project level all configuration is achieved by tweaking the POM. One of the differences between
 maven 1.x and 2.x is that all project parameterization occurs in the POM and not from properties
 files.

 For many of the more advanced features in Maven2 it is critical that POMs be available in the local repository.
 Features like transitive dependencies and the new parent specification mechanism. The problem we run into is
 that currently we have information about a project scattered across the project.xml and the
 various properties files. What needs to be done is to encapsulate all of this in the POM.

 Typically users parameterize the use of plugins, or have custom values like ${user.name}
 for use in elements like the <developerConnection/>. It would be idea if we
 could encapsulate everything we need about the project in the POM including
 plugin parameters and anything else.

 We once had a document that Vincent and I agreed upon and I was about to
 implement it and then I disappeared for 8 months so it never came to pass.

 So I guess it's important to figure out what people are using propeties
 files for and see if we can't incorporate it all into the POM. Or if we do
 have properties file (something I would like to avoid) say they don't
 contribute in any meaningful way to information in the POM. For example a
 properties file could be used the specify $ so it can be interpolated in
 <developerConnection/> but you couldn't use a properties file to specify the
 version of your project say. Anyway, food for thought to begin with.

 - elements that are critical for pom dissemination
 - those that are used locally by the user like <developerConnection/>

* User configuration

 User configuration which is utilized site wide are controlled with the ${user.home}/.m2/maven.properties.

 User configuration which is utilized at the project level are controlled with the
 ${project.home}/maven.properties file.

Plugin configuration

 The configuration of plugins is of the same form as the maven {{{plugin-descriptors}plugin descriptors}}
 themselves:

+-----+
<plugins>
  <plugin>
   <id>xdoc</id>
   <version>1.0</version>
   <parameters>
     <parameter>
       <name>theme</name>
       <value>classic</value>
     </parameter>
   </parameters>
  </plugin>
</plugins>
+-----+

Unified source directory

 Unified source directory structure that is analagous to the repository
 itself. This way locations of intermediary artifacts of a build would be
 in a known location. This would also help with developer setup i.e. getting
 new developers up and running. They could run a maven command and have all
 their source trees set up in the same way as their collegues.

 here's what I do currently in the netbeans part of the mevenide project to
 find the relevant subprojects/sibling projects. I check if the user has
 defined the maven.multiproject.includes property in any of his properties
 files for the current project. if yes. then I'm able to find projects that
 can be offered to be opened together with the current project.
 problems with the current solution are:
 1. information is duplicate. once in POM's dependencies and once in the
 maven.multiproject.includes property.
 2. it works without problems only for projects with relative paths, eg. from
 one CVS repository.. for projects from multiple SCM repositories it's harder
 to maintain the same relative links on all developer computers.
 not sure the unified source directory structure addresses this issue.

 Properties

 maven.user.config.dir (system,default=${user.home}/.m2)
 maven.home            (system,user,default=${user.home}/m2)
 maven.repo.local      (system,user,default=${maven.user.config.dir}/repository)

 We need to define what happens in the when things are not setup correctly

 o ~/.m2 directory does not exist
 o ~/.m2/maven.properties does not exist
 o if they once existed but now to do not exist
 o what the installer will take care of of what we can recover from