* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2020-01-23 8:24 Ulrich Müller
0 siblings, 0 replies; 9+ messages in thread
From: Ulrich Müller @ 2020-01-23 8:24 UTC (permalink / raw
To: gentoo-commits
commit: 82debb8070ef7a417ae82aafcf9d0a8b2ce7c2cf
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 30 17:22:24 2019 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Jan 23 08:22:17 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=82debb80
ebuild-maintenance/package-and-slot-moves: Update package moves
Update the text on package moves to cover the case when PN changes
as well as category. Cover necessary changes in moved ebuild. Switch
from wall-of-text block into a more readable list. Move additional
points from examples to this list. Finally, remove the example that now
pretty much repeats what was said above.
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
[Clarification added by committer to first paragraph of "Moving or
renaming a package".]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 94 +++++++++----------------------
1 file changed, 27 insertions(+), 67 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index a3a45c2..21cd245 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -31,99 +31,59 @@ the following must be noted:
</body>
<section>
-<title>Moving a package</title>
+<title>Moving or renaming a package</title>
<body>
<p>
-Moving a package in the tree requires several operations. Firstly,
-the package directory needs to be moved to the correct category
-using <c>git mv</c>. After this, a new entry needs to be added to
-the latest file in <c>profiles/updates/</c> in the
-following format:
+Moving or renaming a package requires several operations. Firstly, verify that
+the ebuilds will continue to work correctly after the move. If the category
+changes, you must verify all <c>${CATEGORY}</c> uses. If the package name
+changes, you must verify <c>${PN}</c>, <c>${P}</c>, etc. Whenever the old value
+is necessary, substitute the variable reference with the verbatim text, so that
+it won't get affected by the move. Commit the changes separately before moving
+the package.
</p>
-<pre>
-move old-category/package-name new-category/package-name
-</pre>
-
<p>
-Following the update entry, ebuilds that have a
-<uri link="::general-concepts/dependencies">dependency</uri>
-to this package (in other words, the reverse dependencies of
-the package to be moved) need to be updated properly.
+Afterwards, move the package files using <c>git mv</c>. Add the move entry
+to <c>profiles/updates/</c>, in the following format:
</p>
-<p>
-Next is checking the files under <c>profiles/</c> such as
-<c>profiles/package.mask</c> and update them to reflect the ebuild
-move. Various eclasses automatically provide some of the dependencies upon
-inherit, so the files under <c>eclass/</c> should be checked and updated
-properly. If the package metadata.xml has tags with <c>restrict</c>
-attribute, they should be updated to reflect the move. The
-metadata.xml for various packages may contain references to the
-package being moved using the <c><pkg></c> tag which need to be
-updated accordingly as well. Lastly, the titles of the open bugs
-related to the package should be updated.
-</p>
+<pre>
+move old-category/old-name new-category/new-name
+</pre>
<p>
-Here is an example where the package
-<c>net-misc/fwbuilder</c> is transparently moved to
-<c>net-firewall/fwbuilder</c>:
+Following the update entry, find all references to the old package name
+and update them. These include:
</p>
-<ol>
- <li>Issue <c>git mv net-misc/fwbuilder net-firewall/fwbuilder</c></li>
+<ul>
<li>
- <p>
- Add the following entry to the latest file in
- <c>profile/updates/</c>:
- </p>
- <p><c>move net-misc/fwbuilder net-firewall/fwbuilder</c></p>
+ <uri link="::general-concepts/dependencies">dependencies</uri>,
+ <c>has_version</c> and <c>best_version</c> uses in other ebuilds
+ and eclasses
</li>
- <li>Update the reverse dependencies of the package</li>
<li>
- Update <c>profiles/package.mask</c> and other related files under
- <c>profiles/</c>
+ all <c>profiles/</c> tree entries (e.g. <c>profiles/package.mask</c>)
</li>
- <li>Check the eclasses that may be referencing the package</li>
<li>
- Update all the
- <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri>
- files which contain a reference to this package using the
- <c><pkg></c> tag or the <c>restrict</c> attribute.
+ <c>restrict</c> entries in package <c>metadata.xml</c> files, as well
+ as <c><pkg/></c> tags
</li>
<li>
- Stage all the changed files using <c>git add</c>. For example: <c>git add
- profiles/package.mask</c>
+ news item <c>Display-If-Installed</c>
</li>
<li>
- Commit all the changes in one commit using: <c>git commit --gpg-sign --signoff</c>
+ open bug summaries
</li>
- <li>
- Update any <uri link="::general-concepts/news">news items</uri>
- referencing the package in a <c>Display-If-Installed</c> header
- or in the item's body (and increment their <c>Revision</c>).
- </li>
- <li>Update any open bugs related to the package</li>
-</ol>
+</ul>
<p>
-It is very important to commit all the changes in a single commit to ensure
-that no breakage occurs. The commit message should follow a format similar
-to the following:
+Preferably, combine all those changes into a single commit to ensure atomicity
+during the update.
</p>
-<pre>
-commit 7a699bcdce5c1412c02a2aa7717a31bc17c49058
-Author: Miroslav Šulc <fordfrog@gentoo.org>
-Date: Wed Dec 18 19:56:03 2019 +0100
-
- media-libs/libclxclient: moved to x11-libs/libclxclient
-
- Signed-off-by: Miroslav Šulc <fordfrog@gentoo.org>
-</pre>
-
</body>
</section>
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2020-01-23 8:24 Ulrich Müller
0 siblings, 0 replies; 9+ messages in thread
From: Ulrich Müller @ 2020-01-23 8:24 UTC (permalink / raw
To: gentoo-commits
commit: 4b68e4039e4f0b1a484cac97c3a44c97e604b179
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Dec 30 17:10:32 2019 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Jan 23 08:22:08 2020 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=4b68e403
ebuild-maintenance/package-and-slot-moves: Add extra warnings
Since people are frequently getting moves wrong, try to point out a few
important limitations.
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index 0d20667..a3a45c2 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -5,9 +5,29 @@
<body>
<p>
-This chapter describes the use of package and slot moves.
+This chapter describes the use of package and slot moves. The package update
+mechanism is a powerful tool, and needs to be used with caution. In particular,
+the following must be noted:
</p>
+<ol>
+ <li>
+ Updates are <e>not one-shot</e> operations and they are not stateful. All
+ updates can be reapplied multiple times to the same system, and all old
+ updates are applied to fresh Gentoo installations.
+ </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.
+ </li>
+ <li>
+ Updates can only perform one-to-one moves. They cannot be used to merge
+ packages. Attempting to move two or more packages into a single name may
+ cause serious problems for users.
+ </li>
+</ol>
+
</body>
<section>
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2022-01-22 21:35 Sam James
0 siblings, 0 replies; 9+ messages in thread
From: Sam James @ 2022-01-22 21:35 UTC (permalink / raw
To: gentoo-commits
commit: dc5767a0404c1d60e67352202953d88931a6cedc
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 1 11:16:30 2022 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 22 21:34:45 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dc5767a0
ebuild-maintenance/package-moves: mention updating wiki pages
Signed-off-by: Sam James <sam <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 3 +++
1 file changed, 3 insertions(+)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index 93e0dcf..dc9fc6b 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -78,6 +78,9 @@ and update them. These include:
<li>
open bug summaries
</li>
+ <li>
+ wiki pages
+ </li>
</ul>
<p>
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2022-01-22 21:35 Sam James
0 siblings, 0 replies; 9+ messages in thread
From: Sam James @ 2022-01-22 21:35 UTC (permalink / raw
To: gentoo-commits
commit: ad87b9249ca686eee537e76d0bb6916ef22d9aa2
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 1 11:17:31 2022 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 22 21:34:46 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ad87b924
ebuild-maintenance/package-moves: mention optfeature
Signed-off-by: Sam James <sam <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index dc9fc6b..206436b 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -62,8 +62,8 @@ and update them. These include:
<ul>
<li>
<uri link="::general-concepts/dependencies">dependencies</uri>,
- <c>has_version</c> and <c>best_version</c> uses in other ebuilds
- and eclasses
+ <c>optfeature.eclass</c> uses, <c>has_version</c> and <c>best_version</c>
+ uses in other ebuilds and eclasses
</li>
<li>
all <c>profiles/</c> tree entries (e.g. <c>profiles/package.mask</c>)
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2022-01-22 21:35 Sam James
0 siblings, 0 replies; 9+ messages in thread
From: Sam James @ 2022-01-22 21:35 UTC (permalink / raw
To: gentoo-commits
commit: 20a8ffa9fdd1b9f30fd99346dc6c9f876a4af5f0
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Wed Jan 12 04:44:11 2022 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 22 21:34:47 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=20a8ffa9
ebuild-maintenance/package-moves: minor grammar and formatting nits
- Drop a comma
- Use <c>SLOT</c>
Signed-off-by: Sam James <sam <AT> gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/260
Signed-off-by: Sam James <sam <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index 206436b..4180c17 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -47,7 +47,7 @@ the package.
<p>
Afterwards, move the package files using <c>git mv</c>. Add the move entry
-to <c>profiles/updates/</c>, in the following format:
+to <c>profiles/updates/</c> in the following format:
</p>
<pre>
@@ -96,8 +96,8 @@ during the update.
<body>
<p>
-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
+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>
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2022-01-22 21:35 Sam James
0 siblings, 0 replies; 9+ messages in thread
From: Sam James @ 2022-01-22 21:35 UTC (permalink / raw
To: gentoo-commits
commit: 986ca8f1dd6eca7c9a1b099a9a652bc9710786b1
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 1 11:15:26 2022 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Jan 22 21:34:45 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=986ca8f1
ebuild-maintenance/package-moves: add common terms for pkgmove/slotmove
Signed-off-by: Sam James <sam <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 15 ++++++++-------
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index 21cd245..93e0dcf 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -35,12 +35,13 @@ the following must be noted:
<body>
<p>
-Moving or renaming a package requires several operations. Firstly, verify that
-the ebuilds will continue to work correctly after the move. If the category
-changes, you must verify all <c>${CATEGORY}</c> uses. If the package name
-changes, you must verify <c>${PN}</c>, <c>${P}</c>, etc. Whenever the old value
-is necessary, substitute the variable reference with the verbatim text, so that
-it won't get affected by the move. Commit the changes separately before moving
+Moving or renaming a package (sometimes called a "pkgmove" or just "move")
+requires several operations. Firstly, verify that the ebuilds will continue to
+work correctly after the move. If the category changes, you must verify all
+<c>${CATEGORY}</c> uses. If the package name changes, you must verify
+<c>${PN}</c>, <c>${P}</c>, etc. Whenever the old value is necessary,
+substitute the variable reference with the verbatim text, so that it won't get
+affected by the move. Commit the changes separately before moving
the package.
</p>
@@ -92,7 +93,7 @@ during the update.
<body>
<p>
-The process for changing the ebuild's SLOT is very similar to the
+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 <c>profiles/updates/</c> in
the Gentoo repository in the following format:
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2022-02-18 18:19 Sam James
0 siblings, 0 replies; 9+ messages in thread
From: Sam James @ 2022-02-18 18:19 UTC (permalink / raw
To: gentoo-commits
commit: 35b8e9ef476c31fdcaf58291e2d158e62f89616d
Author: Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Jan 22 23:31:33 2022 +0000
Commit: Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Fri Feb 18 18:19:19 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=35b8e9ef
ebuild-maintenance/package-moves: link to updates/ page
Bug: https://bugs.gentoo.org/388685
Signed-off-by: Sam James <sam <AT> gentoo.org>
Closes: https://github.com/gentoo/devmanual/pull/268
Signed-off-by: Sam James <sam <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index 4180c17..c5b278f 100644
--- a/ebuild-maintenance/package-moves/text.xml
+++ b/ebuild-maintenance/package-moves/text.xml
@@ -12,9 +12,10 @@ the following must be noted:
<ol>
<li>
- Updates are <e>not one-shot</e> operations and they are not stateful. All
- updates can be reapplied multiple times to the same system, and all old
- updates are applied to fresh Gentoo installations.
+ <uri link="::profiles/updates/">Updates</uri> are <e>not one-shot</e>
+ operations and they are not stateful. All updates can be reapplied multiple
+ times to the same system, and all old updates are applied to fresh Gentoo
+ installations.
</li>
<li>
Once an update entry is created, the old package name (or slot) cannot be
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2024-02-08 10:39 Ulrich Müller
0 siblings, 0 replies; 9+ messages in thread
From: Ulrich Müller @ 2024-02-08 10:39 UTC (permalink / raw
To: gentoo-commits
commit: 89b2bf7f24c04546bc9d25177ee7739f528f872c
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 21 14:41:51 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> 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 <mgorny <AT> gentoo.org>
[Replace Unicode subscripts by <sub> markup; rewrap paragraph]
Signed-off-by: Ulrich Müller <ulm <AT> 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:
</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>
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
@ 2024-02-08 11:15 Ulrich Müller
0 siblings, 0 replies; 9+ messages in thread
From: Ulrich Müller @ 2024-02-08 11:15 UTC (permalink / raw
To: gentoo-commits
commit: 5cb6b40137d1ce49d94f355dd15ddd512c2f8c7b
Author: Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Sun Jan 21 14:41:51 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Feb 8 11:14:10 2024 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5cb6b401
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 <AT> gentoo.org>
[Replace Unicode subscripts by <sub> markup]
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
ebuild-maintenance/package-moves/text.xml | 50 +++++++++++++++++++++++++++++--
1 file changed, 48 insertions(+), 2 deletions(-)
diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml
index eab8848..9c07db5 100644
--- 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
@@ -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>
^ permalink raw reply related [flat|nested] 9+ messages in thread
end of thread, other threads:[~2024-02-08 11:15 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-02-18 18:19 [gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/ Sam James
-- strict thread matches above, loose matches on Subject: below --
2024-02-08 11:15 Ulrich Müller
2024-02-08 10:39 Ulrich Müller
2022-01-22 21:35 Sam James
2022-01-22 21:35 Sam James
2022-01-22 21:35 Sam James
2022-01-22 21:35 Sam James
2020-01-23 8:24 Ulrich Müller
2020-01-23 8:24 Ulrich Müller
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox