Updating prior update entries when moving the package again

From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 11CD415815E for ; Thu, 8 Feb 2024 10:39:44 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 53136E2A2E; Thu, 8 Feb 2024 10:39:43 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 06041E2A5E for ; Thu, 8 Feb 2024 10:39:43 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id D98EF34312C for ; Thu, 8 Feb 2024 10:39:41 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 623F414B7 for ; Thu, 8 Feb 2024 10:39:40 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1707388646.89b2bf7f24c04546bc9d25177ee7739f528f872c.ulm@gentoo> Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/ X-VCS-Repository: proj/devmanual X-VCS-Files: ebuild-maintenance/package-moves/text.xml X-VCS-Directories: ebuild-maintenance/package-moves/ X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 89b2bf7f24c04546bc9d25177ee7739f528f872c X-VCS-Branch: master Date: Thu, 8 Feb 2024 10:39:40 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply X-Archives-Salt: 78d1a939-207d-4f9d-aff2-99c7685ba130 X-Archives-Hash: dc24181196b8a175b94ab79e015cdc8e commit: 89b2bf7f24c04546bc9d25177ee7739f528f872c Author: Michał Górny gentoo org> AuthorDate: Sun Jan 21 14:41:51 2024 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Thu Feb 8 10:37:26 2024 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=89b2bf7f 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 gentoo.org> [Replace Unicode subscripts by _{markup; rewrap paragraph]
Signed-off-by: Ulrich Müller gentoo.org>

ebuild-maintenance/package-moves/text.xml | 56 ++++++++++++++++++++++++++++---
1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index eab8848..33646f5 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -19,8 +19,10 @@ the following must be noted:

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.

Updates can only perform one-to-one moves. They cannot be used to merge
@@ -97,9 +99,9 @@ during the update.

-The process for changing the ebuild's SLOT (a "slotmove") is very similar to the
-previous process. Besides changing the SLOT in the ebuild file, you
-also need to create a new entry in profiles/updates/ in
+The process for changing the ebuild's SLOT (a "slotmove") is very
+similar to the previous process. Besides changing the SLOT in the ebuild
+file, you also need to create a new entry in profiles/updates/ in
the Gentoo repository in the following format:

@@ -113,6 +115,50 @@ you have updated every file in profiles/ directory that
happens to contain an entry which may be affected by your change.

+
+
+
+
+Updating prior update entries when moving the package again
+
+
+
+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:
+
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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₁ → A:S₂, A → B;
+ we prefer to have the chain: A → B, B:S₁ → B:S₂.
+ All package and slot move entries must reside in the same file then, to
+ guarantee sequential processing.
+
+
+}