Beginnings of document explaining how repository lists are constructed during inheritance and transitive dependency resolution.

git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@239509 13f79535-47bb-0310-9956-ffa450edef68

maven-site/src/site/apt/repositories-and-artifact-resolution-overview.apt

@@ -0,0 +1,54 @@
+  ---
+  Repository Definitions and Artifact Resolution: Overview
+  ---
+  John Casey
+  ---
+  23-August-2005
+  ---
+  
+Overview: Repository Definitions and Artifact Resolution
+
+*Introduction
+
+  As you no doubt know by now, artifacts are a central concept to Maven. Since
+  artifacts are referenced in abstract terms (groupId/artifactId rather than
+  file path), they must be available in the Maven repository system in order
+  for the build process to resolve them. This really amounts to putting the
+  referenced artifacts into a Maven repository. 
+  
+  To promote flexibility in the configuration of your build environment, 
+  Maven allows multiple repositories to be defined from which artifacts can 
+  be resolved. Repositories are always defined in the POM, but since POMs can 
+  inherit from one another, and POM dependencies are resolved transitively, 
+  predicting which repository will be used to resolve a particular artifact 
+  can be daunting.
+  
+  This document will attempt to explain the rules involved with constructing
+  repository lists for resolving artifacts referenced in various parts of the 
+  build process, and eliminate - or at least, reduce - the potential for 
+  confusion when it comes to artifact resolution.
+
+*Goals
+
+  The artifact resolution process in Maven has a couple of central goals which
+  should help make the build process as flexible and powerful as possible. They
+  are:
+  
+  * Allow the local POM (the one being built) to have the first opportunity to 
+    control resolution.
+    
+    <NOTE: In the case of an inheritance hierarchy, the ancestor POMs are 
+    appended to the current repository list in inside-out order.>
+    
+  * Allow the declaring-POM (the one declaring the dependency, in the case of 
+    transitivity) the second opportunity.
+    
+  * Default to the repositories defined in the super-POM for resolution.
+
+~~Repository list construction (for resolution)
+~~~~Repository sources (local vs. default vs. inheritance vs. transitive POMs)
+~~~~Preserving the authority of the POM which declares the artifacts
+~~~~Local-wins priority (during inheritance AND transitive dependency resolution)
+~~~~Keeping the super-POM repositories last in line (ensuring their default status)
+
+~~The net effect: a sample walkthrough