Author: dennisl
Date: Fri Jul 7 16:35:34 2006
New Revision: 420011
URL: http://svn.apache.org/viewvc?rev=420011&view=rev
Log:
Guide on how to relocate artifacts in the repository
Added:
maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt (with
props)
Added: maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt
URL:
http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt?rev=420011&view=auto
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt (added)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt Fri Jul 7
16:35:34 2006
@@ -0,0 +1,139 @@
+ ------
+ Guide to relocation
+ ------
+ Dennis Lundberg
+ ------
+ 8 July 2006
+ ------
+
+Guide to relocation
+
+ Sometimes it is necessary to relocate artifacts in the repository. One
+ example of that is when a project moves from Maven 1 to Maven 2. Maven 1
+ projects have traditionally used a flat repository structure, while Maven 2
+ uses a deep repository structure. As an example the Maven 1 project has a
groupId
+ of <<<maven>>> while the Maven 2 project has a groupId of
<<<org.apache.maven>>>.
+
+ Making changes to the repository can have far reaching consequences. So it is
+ best to get it right the first time, hence this guide. It will go through a
+ couple of different kinds of relocations:
+
+ * Maven 1 to Maven 1
+
+ * Maven 2 to Maven 2
+
+ * Maven 1 to Maven 2
+
+ []
+
+ The goal of the examples below is to relocate the groupId from <<<bar>>> to
+ <<<org.bar>>> for the <<<foo>>> project.
+
+* How to relocate a Maven 1 artifact to a different groupId
+
+ [[1]] Copy all <<<foo>>>-related files from <<</bar/>>> in your Maven 1
repository
+ to a temporary location.
+
+ [[2]] Change the groupId to <<<org.bar>>> in all the <<<foo>>>-related pom
files in
+ the temporary location.
+
+ [[3]] If your project uses MD5 checksums you must now create new checksums for
+ the changed pom files in the temporary location. If the pom file needs to be
+ signed, do that as well.
+
+ [[4]] Copy all files from the temporary location to <<</org.bar/>>> in your
+ Maven 1 repository.
+
+ [[5]] If your project syncs with ibiblio, you should now initiate that sync.
+ This might happen automatically depending on your projects sync policy.
+
+ []
+
+ Your <<<foo>>>-artifacts are now available to Maven 1 users with both the old
and
+ the new groupId.
+
+** Releasing the next version
+
+ When the next release of <<<foo>>> is made, you publish the Maven 1 pom as you
+ have always done. Unfortunately Maven 1 does not have a concept of automatic
+ relocation and notification, so you will have to inform your users of the
+ changed groupId through your regular information channels.
+
+
+* How to relocate a Maven 2 artifact to a different groupId
+
+ [[1]] Copy all <<<foo>>>-related files from <<</bar/foo/>>> in your Maven 2
+ repository to a temporary location.
+
+ [[2]] Change the groupId to <<<org.bar>>> in all <<<foo>>>-related pom files
in the
+ temporary location.
+
+ [[3]] Copy all files from the temporary location to <<</org/bar/foo/>>> in
+ your Maven 2 repository.
+
+ [[4]] Create a minimal Maven 2 pom file for every old release of <<<foo>>> in
+ your Maven 2 repository. The pom files only need to include <<<groupId>>>,
+ <<<artifactId>>>, <<<version>>> and the relocation section.
+
+ <<Note:>> Before you replace your old pom files in <<</bar/foo/>>> with these
+ minimal pom files, make sure you have made backups!
+
+ The minimal pom file might look like this for version 1.0 of <<<foo>>>:
+
++----+
+<project>
+ <groupId>bar</groupId>
+ <artifactId>foo</artifactId>
+ <version>1.0</version>
+ <distributionManagement>
+ <relocation>
+ <groupId>org.bar</groupId>
+ </relocation>
+ </distributionManagement>
+</project>
++----+
+
+ In this case we are relocating because the groupId has changed. We only need
+ to add the element that has changed to the <<<relocation>>> element. For
+ information on which elements are allowed in the <<<relocation>>> element,
+ see
+
{{{http://maven.apache.org/ref/current/maven-model/maven.html#class_relocation}the
pom reference}}.
+
+ [[5]] If your project uses MD5 checksums you must now create new checksums for
+ the pom files in <<</bar/foo/>>> in your Maven 2 repository. If the pom file
needs
+ to be signed, do that as well.
+
+ [[6]] If your project syncs with ibiblio, you should now initiate that sync.
+ This might happen automatically depending on your projects sync policy.
+
+ []
+
+ Your <<<foo>>>-artifacts are now available to Maven 2 users with both the old
+ and the new groupId. Projects using the old groupId will automatically be
+ redirected to the new groupId and a warning telling the user to update their
+ dependencies will be issued.
+
+** Releasing the next version
+
+ When the next release of <<<foo>>> is made, you only need to publish a Maven 2
+ pom with a groupId of <<<org.bar>>>, since users of previous versions have
+ already been informed of the changed groupId.
+
+
+* How to relocate a Maven 1 artifact to a Maven 2 artifact with a different
groupId
+
+ <This is only of interest to organizations (like the Apache Software
+ Foundation) that automatically converts the contents of their Maven 1
+ repository to their Maven 2 repository.>
+
+ Follow steps 4 to 6 in the section <How to relocate a Maven 2 artifact to a
+ different groupId> above.
+
+** Releasing the next version
+
+ When the next release of <<<foo>>> is made, you should publish the Maven 1 pom
+ as you have always done. In addition to that, you should publish a Maven 2 pom
+ with a groupId of <<<bar>>>, a version of \<next-version\> and include a
+ relocation section. This step can be done once for the first release of a
+ project, after the groupId has been changed, but your users will be happier if
+ you do it more times.
Propchange: maven/site/trunk/src/site/apt/guides/mini/guide-relocation.apt
------------------------------------------------------------------------------
svn:eol-style = native
