content/apt/guides/mini/guide-relocation.apt - maven-site - Git at Google

  ------
  Guide to relocation
  ------
  Dennis Lundberg
  ------
  2006-07-08
  ------

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

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

 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 or SHA1 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>
   <modelVersion>4.0.0</modelVersion>
   <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
  {{{/ref/current/maven-model/maven.html#class_relocation}the pom reference}}.

  [[5]] If your project uses MD5 or SHA1 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 should publish two Maven 2 pom
  files. First you should publish a pom with the new groupId <<<org.bar>>>.

  Because data in the repository is not supposed to change, Maven 2 doesn't
  download pom files that it has already downloaded. Therefore you will also need
  to publish a pom file with the old groupId <<<bar>>> for the new version. This
  should be a minimal relocation pom (as described in step 4 above), but for the
  new version of <<<foo>>>.

  For the release after that, you only need to publish a Maven 2 pom with a
  groupId of <<<org.bar>>>, since users of the previous version have 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.
	------
	Guide to relocation
	------
	Dennis Lundberg
	------
	2006-07-08
	------

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

	~~ NOTE: For help with the syntax of this file, see:
	~~ http://maven.apache.org/doxia/references/apt-format.html

	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 or SHA1 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>
	<modelVersion>4.0.0</modelVersion>
	<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
	{{{/ref/current/maven-model/maven.html#class_relocation}the pom reference}}.

	[[5]] If your project uses MD5 or SHA1 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 should publish two Maven 2 pom
	files. First you should publish a pom with the new groupId <<<org.bar>>>.

	Because data in the repository is not supposed to change, Maven 2 doesn't
	download pom files that it has already downloaded. Therefore you will also need
	to publish a pom file with the old groupId <<<bar>>> for the new version. This
	should be a minimal relocation pom (as described in step 4 above), but for the
	new version of <<<foo>>>.

	For the release after that, you only need to publish a Maven 2 pom with a
	groupId of <<<org.bar>>>, since users of the previous version have 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.