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 <fordf...@gentoo.org>
-Date: Wed Dec 18 19:56:03 2019 +0100
-
- media-libs/libclxclient: moved to x11-libs/libclxclient
-
- Signed-off-by: Miroslav Šulc <fordf...@gentoo.org>
-</pre>
-
</body>
</section>
