From df6414525d19f5c3de61eac52006f8a85df0f195 Mon Sep 17 00:00:00 2001
From: John Dennis Casey <jdcasey@apache.org>
Date: Wed, 24 Aug 2005 02:25:15 +0000
Subject: [PATCH] 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
---
 ...ories-and-artifact-resolution-overview.apt | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 maven-site/src/site/apt/repositories-and-artifact-resolution-overview.apt

diff --git a/maven-site/src/site/apt/repositories-and-artifact-resolution-overview.apt b/maven-site/src/site/apt/repositories-and-artifact-resolution-overview.apt
new file mode 100644
index 0000000000..122daab914
--- /dev/null
+++ b/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
\ No newline at end of file