package-moves: Allow moving back, and describe how to chain updates

Make the rule forbidding reusing old package names less strict. There is no real reason not to move packages back — we can safely assume that the package manager will handle that just fine. The only real restriction is that no other package must reuse any of the old names, i.e. effectively cause the package manager to attempt merging the packages together. Add explicit rules for updating old package move entries. These match the logic used in pkgcheck, and therefore ensure both correct results and no warnings from pkgcheck. Signed-off-by: Michał Górny <mgorny@gentoo.org> [Replace Unicode subscripts by <sub> markup; rewrap paragraph] Signed-off-by: Ulrich Müller <ulm@gentoo.org>
gentoo · Feb 8, 2024 · 89b2bf7 · 89b2bf7
1 parent bd47497
commit 89b2bf7
Showing 1 changed file with 51 additions and 5 deletions.
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
@@ -19,8 +19,10 @@ the following must be noted:
   </li>
   <li>
     Once an update entry is created, the old package name (or slot) cannot be
-    reused. Attempting to reuse it will cause updates to apply again,
-    to the reused name. This also means that updates cannot be undone.
+    reused for another package. Attempting to reuse it will cause updates to
+    apply again, to the reused name. This also means that while a package can
+    be moved back to its previous name, all the names historically used for
+    a package are reserved to it alone.
   </li>
   <li>
     Updates can only perform one-to-one moves. They cannot be used to merge
@@ -97,9 +99,9 @@ during the update.
 <body>
 
 <p>
-The process for changing the ebuild's <c>SLOT</c> (a "slotmove") is very similar to the
-previous process.  Besides changing the <c>SLOT</c> in the ebuild file, you
-also need to create a new entry in <c>profiles/updates/</c> in
+The process for changing the ebuild's <c>SLOT</c> (a "slotmove") is very
+similar to the previous process. Besides changing the <c>SLOT</c> in the ebuild
+file, you also need to create a new entry in <c>profiles/updates/</c> in
 the Gentoo repository in the following format:
 </p>
 
@@ -113,6 +115,50 @@ you have updated every file in <c>profiles/</c> directory that
 happens to contain an entry which may be affected by your change.
 </p>
 
+</body>
+</section>
+
+<section>
+<title>Updating prior update entries when moving the package again</title>
+<body>
+
+<p>
+When the same package is moved again, the previous update entries should
+be updated appropriately. This is meant to make the situation more transparent
+to users reading update entries and to ensure that the process is handled
+efficiently even if the package manager does not implement updates in a robust
+way. This involves the following steps:
+</p>
+
+<ol>
+  <li>
+    The previous package moves for the package in question must be updated
+    to reference the final name. That is, rather than the chain A → B → C,
+    we want to have two update entries: A → C, and B → C.
+  </li>
+
+  <li>
+    If the package is being moved to a name that it used before, the original
+    move entry must be removed. That is, rather than the chain A → B → A,
+    we want to have the reverse entry: B → A. If the package manager did not
+    move A → B before, we don't want it to touch the package at all.
+  </li>
+
+  <li>
+    As a combination of the two aforementioned steps, a chain of A → B → C → A
+    would be replaced by two moves: B → A, and C → A.
+  </li>
+
+  <li>
+    If the package was slot-moved before, the slot moves should be updated
+    to use the final package name, and moved after the final package move.
+    That is, rather than the chain: A:S<sub>1</sub> → A:S<sub>2</sub>, A → B;
+    we prefer to have the chain: A → B, B:S<sub>1</sub> → B:S<sub>2</sub>.
+    All package and slot move entries must reside in the same file then, to
+    guarantee sequential processing.
+  </li>
+</ol>
+
 </body>
 </section>
 </chapter>