start developer documentation for the branch

git-svn-id: https://svn.apache.org/repos/asf/archiva/branches/MRM-1025@908844 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 163 insertions, 9 deletions

diff --git a/archiva-modules/src/site/apt/index.apt b/archiva-modules/src/site/apt/index.apt
deleted file mode 100644
index 7bd2758a9..000000000
--- a/archiva-modules/src/site/apt/index.apt
+++ /dev/null
@@ -1,8 +0,0 @@
- ----
- Archiva Developer's Documentation
- ----
-
-Archiva Developer's Documentation
-
-  These documents cover the architecture of Archiva and how to work with it.
-
diff --git a/archiva-modules/src/site/apt/index.apt.vm b/archiva-modules/src/site/apt/index.apt.vm
new file mode 100644
index 000000000..c0af70403
--- /dev/null
+++ b/archiva-modules/src/site/apt/index.apt.vm
@@ -0,0 +1,75 @@
+ ----
+ Archiva Developer's Documentation
+ ----
+
+Archiva Developer's Documentation
+
+    These documents cover the architecture of Archiva and how to work with it. Information for users and plugin
+    developers can be found instead in the
+    {{{http://archiva.apache.org/docs/${project.version}/index.html} main Archiva documentation}}.
+
+    <Note:> This documentation is far from complete, and mostly covers new improvements relevant to developers as they
+    are made, and may not cover older topics such as the <<<archiva-model>>> or <<<archiva-repository-layer>>> libraries
+    that are still in use and particularly coupled to certain repository types and the web interfaces.
+
+* Overview
+
+    Archiva is built as a layered application. It is intended to provide a platform for dealing with repositories of
+    varied types, and so is built as a series of modular libraries that aim to be able to be used independently (such as
+    embedded scenarios, from the CLI, or within the Archiva web application).
+
+    Central to the redesign of Archiva is the concept of a metadata content repository. Archiva separates the physical
+    storage of a repository from the representation it works on, allowing it to store information about the repository
+    in an extensible format that any plugin can operate on or add to, without all subsystems needing to know about
+    each other. The metadata is not specific to any repository type - for instance, the Maven 2 portions can be
+    completely optional. More information on the {{{./metadata.html} metadata format}} and how it is persisted is
+    present in the section below.
+
+    This structure allows metadata repositories to be physically separated from the repository they represent and
+    remotely updated. However, it is also possible to link the repository storage via the API so that the metadata can
+    operate "live" on a repository, detecting changes. This also allows plugins that wish to operate directly on a
+    repository (for example, Maven snapshot purging).
+
+    Similarly, the resolution strategy for resources in the repository is abstracted from the storage and metadata to
+    allow multiple strategies. This facilitates features such as repository proxying, repository grouping, and on the
+    fly format conversion. These are described in the {{{./repositories.html} Repository API}} documents.
+
+    On top of the metadata repository, components can be built to provide the services available in the application.
+    These are described as plugins, though at this time there is no formal plugin registration mechanism or interface -
+    they are loaded by the presence of the JAR in the application classpath, with the appropriate Spring or Plexus
+    manifest and implementation of a core interface that they can "plug in" to. At present, these plugins interact
+    either due to a user request (the repository resolution extension points), a distinct scheduled task, or as part of
+    a repository scanning operation (the Archiva 1.0+ 'consumer' mechanism). In the future, an event mechanism is
+    envisaged as the main means of triggering plugin operations, further decoupling them from the core interfaces.
+    Plugins generally interact directly with the metadata repository to retrieve information, or store their own.
+
+    Some examples of current plugins are:
+
+        * Maven 2 storage repository type
+
+        * Repository statistics
+
+        * File-based metadata content repository persistence
+
+        []
+
+    Finally, we look to the web application layers. At present, there is a single web application that serves both a
+    WebDAV and Struts 2-based application, and operates directly on the metadata repository and some of the legacy
+    APIs. Future development plans to better decouple these from the underlying plugins and legacy APIs, to allow
+    applications to be much more componentised in their deployment.
+
+** How it Works
+
+    * {{{./terminology.html} Terminology}}
+
+    * {{{./metadata.html} Repository metadata}}
+
+    * {{{./repositories.html} Repository APIs}}
+
+* More Information
+
+    More information is available on the Archiva Wiki:
+
+        * {{{http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+Developer+Notes} Developer Notes}}
+
+        * {{{http://cwiki.apache.org/confluence/display/ARCHIVA/Conventions+and+Processes} Conventions and Processes}}
diff --git a/archiva-modules/src/site/apt/metadata.apt b/archiva-modules/src/site/apt/metadata.apt
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/archiva-modules/src/site/apt/metadata.apt
diff --git a/archiva-modules/src/site/apt/repositories.apt b/archiva-modules/src/site/apt/repositories.apt
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/archiva-modules/src/site/apt/repositories.apt
diff --git a/archiva-modules/src/site/apt/terminology.apt b/archiva-modules/src/site/apt/terminology.apt
new file mode 100644
index 000000000..fd82d4b26
--- /dev/null
+++ b/archiva-modules/src/site/apt/terminology.apt
@@ -0,0 +1,84 @@
+ ----
+ Terminology
+ ----
+
+Terminology
+
+    Archiva uses a lot of pieces of data that can have heavily overloaded meaning, so it is important to ensure the
+    terminology used is well defined and consistently used. The following section highlights the terms used in these
+    documents.
+
+* Repository
+
+    Repository is the most overloaded term, but when used alone it will refer to the abstract concept of anything that
+    can act as a repository. For example, an on-disk Maven 2 repository, a remote proxied repository, or a repository
+    group that appears as a single repository.
+
+    A repository is capable of storing a number of artifacts and their associated metadata. Each artifact is identified
+    by a number of elements: the repository itself, it's namespace, project, project version and artifact ID. Some
+    components are optional, depending on the repository type being discussed - for example each is mapped in a Maven 2
+    repository, while for a flat file storage only the repository and artifact ID (file path and name) is needed.
+
+* Namespace
+
+    A namespace is a hierarchical grouping for projects and artifacts, allowing project and artifact IDs to more easily
+    be made unique within their namespace and to assist in mapping between different repository types.
+
+    In a Maven 2 repository, this maps to the group ID of an artifact.
+
+* Project
+
+    A project is a simple grouping of artifacts that share a version in a repository. It does not contain subprojects.
+
+    In a Maven 2 repository, this maps to the artifact ID of an artifact. Note that multi-module projects will actually
+    represent multiple projects by default, and additional grouping (other than achieved by the namespace) would need
+    to be done through additional metadata.
+
+* Project Version
+
+    A project version is the version best used to describe the project (the "marketed version"). It must be unique for
+    lookup and comparing project versions to each other, but the artifact(s) it contains may still use a different
+    version. For example:
+
+        * Archiva 1.4-SNAPSHOT may have artifacts <<<archiva-1.4-20090909.123456-1.jar>>> and
+          <<<archiva-1.4-20100201.345612-2.jar>>>.
+
+        * Jetty 7.0.0 may have an artifact <<<jetty-7.0.0.v20091005.jar>>>
+
+    In a Maven 2 repository, this maps to the (base) version of a project.
+
+* Artifact ID
+
+    The artifact ID uniquely identifies an artifact within a given namespace, project and project version. For example,
+    <<<archiva-1.4-20100201.345612-2.jar>>> or <<<archiva-1.4-20100201.345612-2.pom>>>.
+
+    In a Maven 2 repository, this maps to the filename within the repository, including both the Maven artifact ID,
+    artifact version, classifier and type/extension. Note that the POM and the classic artifact will be stored with
+    separate artifact IDs, but the repository implementation stores the common information for the whole project
+    version (and perhaps all project versions in some instances).
+
+* Metadata Repository
+
+    The metadata repository is the metadata representation of a given repository, containing information about the
+    artifacts it contains, as well as other auxiliary information such as statistics, events, etc.
+
+* Metadata Content Repository
+
+    The metadata content repository is how the information in a metadata repository is persisted. It is effectively the
+    same in appearance to the metadata repository.
+
+* Repository Resolver
+
+    A resolver decides how to translate a request into a given set of metadata or an artifact retrieved from repository
+    storage. The default resolver first queries metadata, falling back to the repository storage if available if
+    necessary due to not being found or being out of date. It is possible that new resolvers can be introduced to also
+    check proxied repositories or to group multiple repositories.
+
+* Repository Storage
+
+    A physical storage medium for a type of repository. This may be a file system in Maven 2 format, a URL pointing to
+    a repository in a certain format, a flat set of files, etc. It can be queried and modified to affect the canonical
+    set of artifacts.
+
+
+
diff --git a/archiva-modules/src/site/site.xml b/archiva-modules/src/site/site.xml
index bc1849025..3a18408c7 100644
--- a/archiva-modules/src/site/site.xml
+++ b/archiva-modules/src/site/site.xml
@@ -32,7 +32,10 @@
     </breadcrumbs>
 
     <menu name="Developers">
-      <item name="About" href="/index.html" />
+      <item name="Overview" href="/index.html" />
+      <item name="Terminology" href="/terminology.html" />
+      <item name="Metadata" href="/metadata.html" />
+      <item name="Repositories" href="/repositories.html" />
     </menu>
     <menu ref="modules" />
   </body>