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>
