[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 5cb6b40137d1ce49d94f355dd15ddd512c2f8c7b Author: Michał Górny gentoo org> AuthorDate: Sun Jan 21 14:41:51 2024 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Feb 8 11:14:10 2024 + 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 gentoo.org> [Replace Unicode subscripts by markup] Signed-off-by: Ulrich Müller 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: 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 @@ -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:S1 → A:S2, A → B; +we prefer to have the chain: A → B, B:S1 → B:S2. +All package and slot move entries must reside in the same file then, to +guarantee sequential processing. + + +
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 89b2bf7f24c04546bc9d25177ee7739f528f872c Author: Michał Górny gentoo org> AuthorDate: Sun Jan 21 14:41:51 2024 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Feb 8 10:37:26 2024 + 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:S1 → A:S2, A → B; +we prefer to have the chain: A → B, B:S1 → B:S2. +All package and slot move entries must reside in the same file then, to +guarantee sequential processing. + + +
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 35b8e9ef476c31fdcaf58291e2d158e62f89616d Author: Sam James gentoo org> AuthorDate: Sat Jan 22 23:31:33 2022 + Commit: Sam James gentoo org> CommitDate: Fri Feb 18 18:19:19 2022 + 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 gentoo.org> Closes: https://github.com/gentoo/devmanual/pull/268 Signed-off-by: Sam James 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: -Updates are not one-shot 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. +Updates are not one-shot +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. Once an update entry is created, the old package name (or slot) cannot be
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 20a8ffa9fdd1b9f30fd99346dc6c9f876a4af5f0 Author: Sam James gentoo org> AuthorDate: Wed Jan 12 04:44:11 2022 + Commit: Sam James gentoo org> CommitDate: Sat Jan 22 21:34:47 2022 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=20a8ffa9 ebuild-maintenance/package-moves: minor grammar and formatting nits - Drop a comma - Use SLOT Signed-off-by: Sam James gentoo.org> Closes: https://github.com/gentoo/devmanual/pull/260 Signed-off-by: Sam James 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. Afterwards, move the package files using git mv. Add the move entry -to profiles/updates/, in the following format: +to profiles/updates/ in the following format: @@ -96,8 +96,8 @@ 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 +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:
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 986ca8f1dd6eca7c9a1b099a9a652bc9710786b1 Author: Sam James gentoo org> AuthorDate: Sat Jan 1 11:15:26 2022 + Commit: Sam James gentoo org> CommitDate: Sat Jan 22 21:34:45 2022 + 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 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: -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 ${CATEGORY} uses. If the package name -changes, you must verify ${PN}, ${P}, 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 +${CATEGORY} uses. If the package name changes, you must verify +${PN}, ${P}, 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. @@ -92,7 +93,7 @@ during the update. -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 profiles/updates/ in the Gentoo repository in the following format:
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: ad87b9249ca686eee537e76d0bb6916ef22d9aa2 Author: Sam James gentoo org> AuthorDate: Sat Jan 1 11:17:31 2022 + Commit: Sam James gentoo org> CommitDate: Sat Jan 22 21:34:46 2022 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ad87b924 ebuild-maintenance/package-moves: mention optfeature Signed-off-by: Sam James 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: dependencies, -has_version and best_version uses in other ebuilds -and eclasses +optfeature.eclass uses, has_version and best_version +uses in other ebuilds and eclasses all profiles/ tree entries (e.g. profiles/package.mask)
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: dc5767a0404c1d60e67352202953d88931a6cedc Author: Sam James gentoo org> AuthorDate: Sat Jan 1 11:16:30 2022 + Commit: Sam James gentoo org> CommitDate: Sat Jan 22 21:34:45 2022 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dc5767a0 ebuild-maintenance/package-moves: mention updating wiki pages Signed-off-by: Sam James 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: open bug summaries + +wiki pages +
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 4b68e4039e4f0b1a484cac97c3a44c97e604b179 Author: Michał Górny gentoo org> AuthorDate: Mon Dec 30 17:10:32 2019 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Jan 23 08:22:08 2020 + 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 gentoo.org> Signed-off-by: Ulrich Müller 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 @@ -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: + + +Updates are not one-shot 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. + + +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. + + +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. + + +
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/
commit: 82debb8070ef7a417ae82aafcf9d0a8b2ce7c2cf Author: Michał Górny gentoo org> AuthorDate: Mon Dec 30 17:22:24 2019 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Jan 23 08:22:17 2020 + 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 gentoo.org> [Clarification added by committer to first paragraph of "Moving or renaming a package".] Signed-off-by: Ulrich Müller 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: -Moving a package +Moving or renaming a package -Moving a package in the tree requires several operations. Firstly, -the package directory needs to be moved to the correct category -using git mv. After this, a new entry needs to be added to -the latest file in profiles/updates/ 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 ${CATEGORY} uses. If the package name +changes, you must verify ${PN}, ${P}, 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. - -move old-category/package-name new-category/package-name - - -Following the update entry, ebuilds that have a -dependency -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 git mv. Add the move entry +to profiles/updates/, in the following format: - -Next is checking the files under profiles/ such as -profiles/package.mask and update them to reflect the ebuild -move. Various eclasses automatically provide some of the dependencies upon -inherit, so the files under eclass/ should be checked and updated -properly. If the package metadata.xml has tags with restrict -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 pkg tag which need to be -updated accordingly as well. Lastly, the titles of the open bugs -related to the package should be updated. - + +move old-category/old-name new-category/new-name + -Here is an example where the package -net-misc/fwbuilder is transparently moved to -net-firewall/fwbuilder: +Following the update entry, find all references to the old package name +and update them. These include: - - Issue git mv net-misc/fwbuilder net-firewall/fwbuilder + - - Add the following entry to the latest file in - profile/updates/: - -move net-misc/fwbuilder net-firewall/fwbuilder +dependencies, +has_version and best_version uses in other ebuilds +and eclasses - Update the reverse dependencies of the package -Update profiles/package.mask and other related files under -profiles/ +all profiles/ tree entries (e.g. profiles/package.mask) - Check the eclasses that may be referencing the package -Update all the -metadata.xml -files which contain a reference to this package using the -pkg tag or the restrict attribute. +restrict entries in package metadata.xml files, as well +as pkg/ tags -Stage all the changed files using git add. For example: git add -profiles/package.mask +news item Display-If-Installed -Commit all the changes in one commit using: git commit --gpg-sign --signoff +open bug summaries - -Update any news items -referencing the package in a Display-If-Installed header -or in the item's body (and increment their Revision). - - Update any open bugs related to the package - + -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. - -commit 7a699bcdce5c1412c02a2aa7717a31bc17c49058 -Author: Miroslav Šulc fordf...@gentoo.org -Date: Wed Dec 18 19:56:03 2019 +0100 - - media-libs/libclxclient:
[gentoo-commits] proj/devmanual:master commit in: ebuild-maintenance/package-moves/, ebuild-maintenance/, ...
commit: 198d314f12ef28b47be3b8e97966244336e0483a Author: Michał Górny gentoo org> AuthorDate: Mon Dec 30 16:44:21 2019 + Commit: Ulrich Müller gentoo org> CommitDate: Thu Jan 23 07:48:04 2020 + URL:https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=198d314f ebuild-maintenance: Move package & slot moves into sep chapter Signed-off-by: Michał Górny gentoo.org> [Fixed guide tag, use title case for chapter title.] Signed-off-by: Ulrich Müller gentoo.org> ebuild-maintenance/maintenance-tasks/text.xml | 120 --- ebuild-maintenance/package-moves/text.xml | 134 ++ ebuild-maintenance/text.xml | 1 + 3 files changed, 135 insertions(+), 120 deletions(-) diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml index 0de2f6d..b5b7359 100644 --- a/ebuild-maintenance/maintenance-tasks/text.xml +++ b/ebuild-maintenance/maintenance-tasks/text.xml @@ -245,126 +245,6 @@ to be in very poor taste and may result in disciplinary action. - -Moving a package - - - -Moving a package in the tree requires several operations. Firstly, -the package directory needs to be moved to the correct category -using git mv. After this, a new entry needs to be added to -the latest file in profiles/updates/ in the -following format: - - - -move old-category/package-name new-category/package-name - - - -Following the update entry, ebuilds that have a -dependency -to this package (in other words, the reverse dependencies of -the package to be moved) need to be updated properly. - - - -Next is checking the files under profiles/ such as -profiles/package.mask and update them to reflect the ebuild -move. Various eclasses automatically provide some of the dependencies upon -inherit, so the files under eclass/ should be checked and updated -properly. If the package metadata.xml has tags with restrict -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 pkg tag which need to be -updated accordingly as well. Lastly, the titles of the open bugs -related to the package should be updated. - - - -Here is an example where the package -net-misc/fwbuilder is transparently moved to -net-firewall/fwbuilder: - - - - Issue git mv net-misc/fwbuilder net-firewall/fwbuilder - - - Add the following entry to the latest file in - profile/updates/: - -move net-misc/fwbuilder net-firewall/fwbuilder - - Update the reverse dependencies of the package - -Update profiles/package.mask and other related files under -profiles/ - - Check the eclasses that may be referencing the package - -Update all the -metadata.xml -files which contain a reference to this package using the -pkg tag or the restrict attribute. - - -Stage all the changed files using git add. For example: git add -profiles/package.mask - - -Commit all the changes in one commit using: git commit --gpg-sign --signoff - - -Update any news items -referencing the package in a Display-If-Installed header -or in the item's body (and increment their Revision). - - Update any open bugs related to the package - - - -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: - - - -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 - - - - - - -Changing ebuild's SLOT - - -The process for changing the ebuild's SLOT 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: - - - -slotmove app-text/gtkspell 0 2 - - - -Make sure that you have fixed all the reverse dependencies and that -you have updated every file in profiles/ directory that -happens to contain an entry which may be affected by your change. - - - - - Removing ebuilds diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml new file mode 100644 index 000..0d20667 --- /dev/null +++ b/ebuild-maintenance/package-moves/text.xml @@ -0,0 +1,134 @@ + + + +Package and Slot Moves + + + +This chapter describes the use of package and slot moves. + + + + + +Moving a package + + + +Moving a package in the tree requires several operations. Firstly, +the package directory needs to be moved to the correct category +using git mv. After this, a new entry needs to be added to +the latest file in profiles/updates/ in the +following format: + + + +move old-category/package-name new-category/package-name + + + +Following the update