Hello, Recently I've found some users complaining on the forums about problems with updating their system (breakage involved). I thought that I'll just point them to the Handbook in order to show them how the updating process is described and how to avoid pitfalls and typical problems. However, on the page "1. A Portage Introduction", in the section "1.c. Maintaining Software", subsection "Updating your System" (see URL provided) there are no examples involving "--pretend" nor "--ask" switches. Only "emerge --update world", "emerge --update --deep world" and "emerge --update --deep --newuse world". After using Gentoo for over two years already, I can tell you that this is not enough. Instead good practices should be described there, like: * always use "--pretend" or at least "--ask" when doing updates (and use 'less' if the output is too long, like "emerge -pvuD world | less") * don't update the working system, unless you really need to, or if you have enough time for repairing it should the problems arise * don't try to live on the edge and withhold the urge to update your system every day to the newest "stable" packages - as they are sometimes marked back as "testing" quite quickly if users start complain in the b.g.o (this is an organizational issue BTW, and the devs really do that sometimes!) * explain what does the "NN files in /etc/ need updating" message mean, and describe (at least shortly) the etc-update and dispatch-conf * remind with big red font, that if one accepts happily ALL changes suggested by these tools, it may have a catastrophic effect for the system (e.g. fstab overwritten, xorg refuses to start, and the like) * make binary package(s) before upgrading (using 'quickpkg') for the case when something goes wrong - this way there is at least a possibility to restore a previous, working version(s) (and remember to remove outdated binary packages occasionally) * learn other useful emerge's options, like "--tree", "--changelog", "--empty-tree", "--usepkg", "--usepkgonly", "--nodeps", "--resume", and "--skipfirst". Simply: use the power, err... use the "man emerge" :-) * other simple yet valuable methods used by the more experienced users and described ad infinitum in the forums ----- One thing to note is that in the event of the upcoming GLEP-42, such practices should include also: * read the critical news before you do the upgrade And with the newer Portage some of my suggestions may quite likely be obsoleted. In fact that would be actually a Good Thing, because these are only workarounds for some currently present Portage problems.
(In reply to comment #0) > * don't update the working system, unless you really need to, or if you have > enough time for repairing it should the problems arise > > * don't try to live on the edge and withhold the urge to update your system > every day to the newest "stable" packages - as they are sometimes marked > back as "testing" quite quickly if users start complain in the b.g.o > (this is an organizational issue BTW, and the devs really do that sometimes!) Stable system is designed to run stable. If you have issues with some package, make a bugreport. This is not the documentation's job. > * make binary package(s) before upgrading (using 'quickpkg') for the > case when something goes wrong - this way there is at least a possibility > to restore a previous, working version(s) > (and remember to remove outdated binary packages occasionally) Waste of time. Users should follow the messages emerge gives them and if there's anything requiring the `quickpkg` step, users should be asked to. Again, please report bugs against the respective packages. > And with the newer Portage some of my suggestions may quite likely be > obsoleted. In fact that would be actually a Good Thing, because these are only > workarounds for some currently present Portage problems. Not a docs-team issue. We can't do anything with that.
(In reply to comment #1) > (In reply to comment #0) > > * don't update the working system, unless you really need to, or if you have > > enough time for repairing it should the problems arise > > > > * don't try to live on the edge and withhold the urge to update your system > > every day to the newest "stable" packages - as they are sometimes marked > > back as "testing" quite quickly if users start complain in the b.g.o > > (this is an organizational issue BTW, and the devs really do that sometimes!) > > Stable system is designed to run stable. If you have issues with some package, > make a bugreport. This is not the documentation's job. I think some advice along these lines is required in official docs to calm down the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG world-and-everything` daily, or worse, in a cron job.
(In reply to comment #1) > > * don't update the working system, unless you really need to ... > > * don't try to live on the edge and withhold the urge to update your system > > every day to the newest "stable" packages ... > Stable system is designed to run stable. If you have issues with some package, > make a bugreport. This is not the documentation's job. And I've filed quite a bit of them already :-) I know the rules, really. [ But the packages are revoked (i.e. "x86" -> "~x86") and that's the fact. Sometimes even the same day after I sync the portage tree several hours later, before going home. This makes "emerge -avuD world" to show that some of the recently merged packages have to be downgraded and in effect wastes the cpu cycles of my machine(s)... Just my POV. ] > > * make binary package(s) before upgrading ... > Waste of time. Users should follow the messages emerge gives them and if > there's anything requiring the `quickpkg` step, users should be asked to. > Again, please report bugs against the respective packages. Nah. Don't be too harsh. Those were only my personal suggestions. Skip'em if you don't like'em. > > these are only workarounds for some currently present Portage problems. > > Not a docs-team issue. We can't do anything with that. At least you agreed to some point that there ARE issues with Portage :-) Which makes this report somewhat justified, I think. Thanks anyway for the response.
(In reply to comment #2) > I think some advice along these lines is required in official docs to calm down > the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG > world-and-everything` daily, or worse, in a cron job. There's nothing wrong with `emerge --sync` from a cronjob, for example for getting GLSAs for your packages, btw. Anyway, feel free to make a patch :-).
(In reply to comment #3) > And I've filed quite a bit of them already :-) I know the rules, really. > > [ But the packages are revoked (i.e. "x86" -> "~x86") and that's the fact. > Sometimes even the same day after I sync the portage tree several hours > later, before going home. This makes "emerge -avuD world" to show that some > of the recently merged packages have to be downgraded and in effect wastes > the cpu cycles of my machine(s)... Just my POV. ] Great. What do you want the documentation team to do? This is *not* our responsibility and we really can't do anything at all about that. Submitting bugs to us won't help. > > > * make binary package(s) before upgrading > ... > > Waste of time. Users should follow the messages emerge gives them and if > > there's anything requiring the `quickpkg` step, users should be asked to. > > Again, please report bugs against the respective packages. > > Nah. Don't be too harsh. Those were only my personal suggestions. > Skip'em if you don't like'em. I usually state a reason if I refuse to do something. Skip the explanation if you don't like it :-). > At least you agreed to some point that there ARE issues with Portage :-) > Which makes this report somewhat justified, I think. Such bugreports don't belong to docs-team, again. > Thanks anyway for the response. You're welcome ;-).
(In reply to comment #2) > I think some advice along these lines is required in official docs to calm down > the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG > world-and-everything` daily, or worse, in a cron job. Since when do we support ricers? Any kind of warning will not calm down ricers anyway. Besides, we should not add something like
(In reply to comment #2) > I think some advice along these lines is required in official docs to calm down > the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG > world-and-everything` daily, or worse, in a cron job. Since when do we support ricers? Any kind of warning will not calm down ricers anyway. Besides, we should not add something like ´Don't upgrade your system too hastily because our devs commit untested material to the tree`, should we? It does not happen often and when it does, users & devs slap the culprit. > One thing to note is that in the event of the upcoming GLEP-42 We do not document vaporware
(In reply to comment #6) > (In reply to comment #2) > > > I think some advice along these lines is required in official docs to calm down > > the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG > > world-and-everything` daily, or worse, in a cron job. > > Since when do we support ricers? I don't know for how long the suggestion to update world all the time has been in the handbook, I think it's since the rewrite of handbook part 2 into parts 2 and 3. I just think, like I assume OP did, that current doc will seem to end users like it's suggesting this kind of foolishness, even though I'm sure the original instruction swere only meant to be a reference of how to do things. > Any kind of warning will not calm down ricers anyway. That I'm painfully aware of. I've been trying to explain the thing to forum users too many times already to even attempt to provide a patch here. > Besides, we should not add something like
(In reply to comment #6) > (In reply to comment #2) > > > I think some advice along these lines is required in official docs to calm down > > the forum ricers who advice everyone to do `emerge sync && emerge UuDNGRMPHOMG > > world-and-everything` daily, or worse, in a cron job. > > Since when do we support ricers? I don't know for how long the suggestion to update world all the time has been in the handbook, I think it's since the rewrite of handbook part 2 into parts 2 and 3. I just think, like I assume OP did, that current doc will seem to end users like it's suggesting this kind of foolishness, even though I'm sure the original instruction swere only meant to be a reference of how to do things. > Any kind of warning will not calm down ricers anyway. That I'm painfully aware of. I've been trying to explain the thing to forum users too many times already to even attempt to provide a patch here. > Besides, we should not add something like ´Don't upgrade your system too > hastily because our devs commit untested material to the tree`, should we? > It does not happen often and when it does, users & devs slap the culprit. I think the problem more commonly raises with tested and working packages, that are just vulnerable, like toolchain. With current instructions the users are easily lead to think that updating everything as soon as new packages appear in world is good thing, while I'd think it might not always be the case. It is of course still correct, that it is the most likely just a vocal minority of misguided users who really fall in to this wrong impression, but it's starting to become frustratingly common in forums, so I thought I'd give a comment anyway. A food for flame perhaps, but hopefully a constructive one :-)
(In reply to comment #7) > > I don't know for how long the suggestion to update world all the time has > been in the handbook, I think it's since the rewrite of handbook part 2 > into parts 2 and 3. > > I just think, like I assume OP did, that current doc will seem to end users > like it's suggesting this kind of foolishness, even though I'm sure the > original instruction swere only meant to be a reference of how to do things. Please see the topic "My worst nightmare in Gentoo, a true story..." at: http://forums.gentoo.org/viewtopic-t-408192.html Would you then consider enhancing the docs to at least explain what the "--pretend | -p" and "--ask | -a" switches do? Pretty please? Here's my rough idea of how the enhancements may look like. ===== BEGIN PROPOSAL ===== Updating your System subsection: <current_text> To keep your system in perfect shape (and not to mention install the latest security updates) you need to update your system regularly. Since Portage only checks the ebuilds in your Portage tree you first have to update your Portage tree. When your Portage tree is updated, you can <proposed_addition> find out what packages Portage <i>would</i> update, by adding the --pretend and (optional) --verbose switches. For instance: <code> <comment>(Preview the list of updates)</comment> # emerge --pretend --update world <comment>(Alternatively, browse the long list of updates with less.) (The -pvu is the short form of --pretend --verbose --update switches.) </comment> # emerge -pvu world | less </code> It is a good habit to see the list of updates first, before accepting them. If the list looks sane, then you can </proposed_addition> update your system with emerge --update world: </current_text> Code Listing 14: <current_text> <proposed_addition> <comment>(Preview the list of updates)</comment> # emerge --pretend --update --deep world <comment>(Merge the updates)</comment> </proposed_addition> # emerge --update --deep world </current_text> Code Listing 15: <current_text> <proposed_addition> <comment>(Preview the list of updates)</comment> # emerge --pretend --update --deep --newuse world <comment>(Merge the updates)</comment> </proposed_addition> # emerge --update --deep --newuse world </current_text> And at the end: <proposed_addition> You can also combine both steps (pretending and approving the merges) into one, by using the --ask switch (or -a in short form). For instance: <code> # emerge --ask --update world </code> </proposed_addition> ===== END PROPOSAL ===== This is the very first time when I propose wording for the handbook. I always thought that the docs team is best at implementing such changes, after describing what might be done. But I really wanted to show what I had on my mind (good practices) when I issued this RFE. Of course, you can do better than that :-) And BTW. since we're getting closer to this wonderful time, I'd like to wish you all a merry christmas and a happy new year!
Updating the entire system /is/ recommended practice; without it, you'll risk security issues, stability improvements, etc. The pretend switch is explained in the beginning (Installing Software) and, imo, not a requirement for the concept of updating the system. I do agree on the --ask, I'll put that in the handbook close to the upgrading instructions in such a way that users do read it.
Fixed in CVS.
