[maven-site] branch master updated: relocation guide details, with Ant example and analysis

[hb...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hboutemy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 536e1f2  relocation guide details, with Ant example and analysis
536e1f2 is described below

commit 536e1f2e61e93156db40c6877e75d6d2da62ddc1
Author: Hervé Boutemy <hb...@apache.org>
AuthorDate: Sat Feb 22 10:28:37 2020 +0100

    relocation guide details, with Ant example and analysis
---
 content/apt/guides/mini/guide-relocation.apt | 44 +++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/content/apt/guides/mini/guide-relocation.apt b/content/apt/guides/mini/guide-relocation.apt
index 8b59734..16ee431 100644
--- a/content/apt/guides/mini/guide-relocation.apt
+++ b/content/apt/guides/mini/guide-relocation.apt
@@ -29,17 +29,22 @@
 Guide to relocation
 
  Sometimes it is necessary to relocate artifacts in the repository. One
- example of that is when a project moves from one groupId to different groupId.
+ example of that is when a project moves from one groupId to a different groupId.
+
  Making changes to the repository can have far reaching consequences. So it is
- best to get it right the first time, hence this guide. 
- 
- []
+ best to get it right the first time, hence this guide.
  
- The goal of the examples below is to relocate the groupId from <<<bar>>> to
- <<<org.bar>>> for the <<<foo>>> project.
+ <<2020 rework in progress>>, see
+ {{{https://lists.apache.org/thread.html/r5e940260cfe5234f540c20fdb7bb7dacbb63b911a4b902c75f4f0cd2%40%3Cdev.maven.apache.org%3E}discussion on dev mailing list}},
+ still need analysis of issues, definition of improvements, and of course implementation...
  
 * How to relocate a Maven 2 artifact to a different groupId
  
+ The goal of the example below is for the <<<foo>>> project to relocate its groupId from <<<bar>>> to
+ <<<org.bar>>>.
+ 
+** Working on past versions
+
  [[1]] Copy all <<<foo>>>-related files from <<</bar/foo/>>> in your Maven 2
  repository to a temporary location.
 
@@ -95,15 +100,34 @@ Guide to relocation
 ** 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>>>.
+ files: first you should publish <<<foo>>>'s POM with the new groupId <<<org.bar>>>.
  
  Because data in the repository is not supposed to change, Maven 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
+ to publish a relocation 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 pom with a
+ For the release after that, you only need to publish a Maven POM with a
  groupId of <<<org.bar>>>, since users of the previous version have been
  informed of the changed groupId.
 
+** Examples
+
+ <<Apache Ant>>
+ 
+  [[1]] has published its releases until 1.6.5 to Maven 1-compliant <<<ant:ant>>> coordinates
+  (see {{{https://repo.maven.apache.org/maven2/ant/ant/}repository content}}),
+ 
+  [[2]] starting with 1.7.0, moved to reverse-DNS compliant Maven 2+ <<<org.apache.ant:ant>>> coordinates,
+  (see {{{https://repo.maven.apache.org/maven2/org/apache/ant/ant/}repository content}}),
+ 
+  [[3]] published one <<<ant:ant:1.7.0>>> relocation POM
+  in old groupId to advertise about the move
+  (see {{{https://repo.maven.apache.org/maven2/ant/ant/1.7.0/}repository content}}).
+
+ []
+
+ Notice that past <<<ant:ant>>> versions POMs (until 1.6.5) have not been modified to advertise about the move:  
+ Central POM content is not expected to be changed once published (because initial content has been downloaded
+ many times and is not expected to be re-loaded later).