| Summary: | Changes to documentation to help ease end-user issues | ||
|---|---|---|---|
| Product: | [OLD] Docs-user | Reporter: | Chris Gianelloni (RETIRED) <wolf31o2> |
| Component: | Handbook | Assignee: | Sven Vermeulen (RETIRED) <swift> |
| Status: | VERIFIED FIXED | ||
| Severity: | normal | CC: | docs-team, fuzzyray, greg_g, gurligebis, yd |
| Priority: | High | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Package list: | Runtime testing required: | --- | |
| Attachments: | Patch to Gentoo docs regarding stage1/2 deprecation | ||
|
Description
Chris Gianelloni (RETIRED)
2005-09-13 08:21:53 UTC
I guess that installation stages 1 and 2 which have been a Gentoo feature
from the very beginning (IIRC), will be defended by a number of people,
as they've been created as an incarnation of the Gentoo philosophy for
freedom of choice and customization.
On the other hand, we have the error prone stage1 install that brings
headaches to both users and developers.
It seems that those who insist on being able to customize the build
process from the ground up may get that via stage3 install and subsequently
recompiling the toolchain, the system and the world (forgive me if I am
wrong). This will not be shorter, but might be less error prone.
So my suggestion: make a step in the Gentoo evolution and replace stage1
and stage2 with the appropriate rebuilds *after* a stage3 install (which
will be essentially the sole stage to be released by the Gentoo team).
Pros:
-- users will have a working stage3 system and *then* decide whether
to optimize it more than what they already have.
-- both developers and users will have simpler life with a single-stage
distro (seems an important trade-off).
-- lovers of extreme optimization can still get theirs, even via a more
robust (although possibly somewhat longer) procedure.
Cons:
-- the equivalent of the stage1 install will take longer than the
"original" stage1 install. But that should be within about 20% of
the whole time, so it seems quite acceptable.
I guess that installation stages 1 and 2 which have been a Gentoo feature
from the very beginning (IIRC), will be defended by a number of people,
as they've been created as an incarnation of the Gentoo philosophy for
freedom of choice and customization.
On the other hand, we have the error prone stage1 install that brings
headaches to both users and developers.
It seems that those who insist on being able to customize the build
process from the ground up may get that via stage3 install and subsequently
recompiling the toolchain, the system and the world (forgive me if I am
wrong). This will not be shorter, but might be less error prone.
So my suggestion: make a step in the Gentoo evolution and replace stage1
and stage2 with the appropriate rebuilds *after* a stage3 install (which
will be essentially the sole stage to be released by the Gentoo team).
Pros:
-- users will have a working stage3 system and *then* decide whether
to optimize it more than what they already have.
-- both developers and users will have simpler life with a single-stage
distro (seems an important trade-off).
-- lovers of extreme optimization can still get theirs, even via a more
robust (although possibly somewhat longer) procedure.
Cons:
-- the equivalent of the stage1 install will take longer than the
"original" stage1 install. But that should be within about 20% of
the whole time, so it seems quite acceptable.
(In reply to comment #2) > I guess that installation stages 1 and 2 which have been a Gentoo feature > from the very beginning (IIRC), will be defended by a number of people, > as they've been created as an incarnation of the Gentoo philosophy for > freedom of choice and customization. We aren't removing the option, we're just telling them that they better know what they're doing if they do start from stage1 or stage2. > It seems that those who insist on being able to customize the build > process from the ground up may get that via stage3 install and subsequently > recompiling the toolchain, the system and the world (forgive me if I am > wrong). This will not be shorter, but might be less error prone. It *is* shorter as you don't have to compile all of the toolchain (everything done by bootstrap.sh) twice. Trust me, it takes much less time to extract a stage3 tarball than it takes to compile glibc. > So my suggestion: make a step in the Gentoo evolution and replace stage1 > and stage2 with the appropriate rebuilds *after* a stage3 install (which > will be essentially the sole stage to be released by the Gentoo team). Like I said, we aren't planning on not offering a stage1, so I don't know where you got that idea. > Cons: > -- the equivalent of the stage1 install will take longer than the > "original" stage1 install. But that should be within about 20% of > the whole time, so it seems quite acceptable. A stage1 install takes *much* longer than a stage3 + customize + emerge -e world + emerge depclean. I've timed it myself. Having to compile all of gcc/binutils/glibc twice takes much longer than compiling it only once. All of the other packages would have needed to have been recompiled anyway during the course of going from stage1 to stage3 anyway, so you're talking about increasing time rather than decreasing it by using a stage1. You also don't end up with any advantages in using a stage1 over a stage3, as the net result is the same. Why is a stage3 + emerge -e world faster than a stage1? Personally, I don't think we should list this stage3-like option in the installation handbook. After all, its more of a Portage feature (rebuild everything) than an installation (since the installation has already been done). Better tell people that stage3 is the recommended method... which I thought we already did. OK, for the last time. When doing a bootstrap, you compile the following: bootstrap.sh: virtual/baselayout portage virtual/os-headers binutils gcc gettext (optional) virtual/libc texinfo zlib ncurses Now, none of this is built with --nodeps, so it also compiles other packages. After this, you do an "emerge -e system", correct? Now, doing a stage3 only install, you *only* do an "emerge -e system" without compiling your toolchain twice. This is much faster. If you really think we shouldn't be telling users that performing a stage1 is pretty much pointless, then I'm not really going to argue it anymore, but I'm getting sick of all of these bugs where users have used a stage1, and don't really understand anything about how bootstrapping works, and then complain to us when they break their systems. Basically, there should be a big fat warning on stage1 installs explaining that only users that are advanced and know what they're doing should use it, as they can potentially break their installation by selecting invalid options or making incompatible changes. At any rate, please do #1 and #2, as those would be very beneficial. I'll take this one, time for some handbook reviewing/auditing/improving :) As someone who just had to suffer through all the pain of the bug that spawned this bug, I just combed through the doco looking at this issue. Hopefully some of this will be helpful. The 3 places I see that must be changed in the handbook are: Section 5e, obviously. "Please make sure you have the _correct_ CHOST setting" should be changed to something more along the lines of "Please make sure your CHOST setting bears no relation to your system. It doesn't really do anything anyway; we just put it in there to mess with your head." Section 6b. For users of stage 3, there is no path in the current doco for doing an emerge -e at all. But the main one I want to make sure doesn't get forgotten about is 2b, where one of the pros of stage 1 is " Allows you to have total control over the optimization settings and optional build-time functionality that is initially enabled on your system" and one of the cons of stage 2 is "You cannot tweak as much as with a stage1". According to Chris, these statements are blatant lies. Also, apparently, "Choosing to go with a stage3 allows for the fastest install of Gentoo Linux, but also means that your base system will have the optimization settings that we chose for you ..." isn't really true either. Hope that helps Sven pin down where the changes need to go. Okay, first change on the queue: stage* description. Is http://dev.gentoo.org/~swift/tmp/medium.html a better one? It contains a fix I had in mind for some time (when to pick which one) and changes the wording a bit so regular users pick stage3. (In reply to comment #8) > Okay, first change on the queue: stage* description. > > Is http://dev.gentoo.org/~swift/tmp/medium.html a better one? It contains a fix > I had in mind for some time (when to pick which one) and changes the wording a > bit so regular users pick stage3. - stage1 takes a long time, even more than a stage3 followed by a full recompile + stage3 fastest way to get Gentoo up and running. Gives users the choice to keep default optimisations, change them and recompile all packages (long but still faster than stage1), or change them and let their system optimise itself over time as packages are upgraded. (In reply to comment #8) > Okay, first change on the queue: stage* description. > > Is http://dev.gentoo.org/~swift/tmp/medium.html a better one? 2005.0 and 2005.1's kernels were compiled for 586 (not Pentium) without "Generic x86" in them. This means it is possible that it will not boot on a 486 machine, or some other processors missing instructions. I think I would add a line after the "then a stage1 approach has no benefits for you." Something like the following: "You must also be prepared to resolve any issues that come up with your system, since you are going against the recommended and tested bootstrap setup by the developers." I also agree with Xavier's suggestion. <FuzzyRay> BTW, doing a default stage 3 + Gnome from the GRP followed by an emerge --update --deep --newuse is painful <wolf31o2-work> how so? <FuzzyRay> The upgrade to gcc 3.3.6 from 3.3.5-whatever breaks the libtool files, libIDL has to be re-emerged otherwise it is looking for i386-pc-linux-gnu-gcc when you have i686-pc-linux-gnu-gcc installed <sanchan> FuzzyRay: which GRP packages are you using? <FuzzyRay> packages-x86-2005.1.iso from gentoo.osuosl.org <wolf31o2-work> and which stage3? <FuzzyRay> i686 from the same place. I haven't had issues resolving the problems. But since I was following the handbook I can see how users run into problems <wolf31o2-work> x86 -> x86... i686 -> i686... <FuzzyRay> I realized that when I started hitting problems. We should probably make the handbook clearer on that though. I think he's right. We definitely need to make it clear that the PackageCD *must* match the stage used. I'm thinking big red flashing lights and a nice air-raid siren ought to be good enough... ;] (Same URL) better now? I would personally add an example to make it clearer. Something like the following: For example: If you use stage3-pentium4-2005.1.tar.bz2, you need to download and use packages-pentium4-2005.1.iso If I could keep it platform-independent that would be great; the entire section is completely shared across architectures (even though we currently use a copy/paste method since GuideXML doesn't allow sharing such stuff yet) and a good candidate for "real" sharing if we could improve GuideXML to that. I'd like to keep it that way. Changes are now live. I don't think the recommendations for stage3 usage are nearly strong enough... I now have 2 bugs related to issues with "emerge -e system" where problems occur due to USE flag settings. If, for any reason, any package that is in system has any package in its dependency tree that can *possibly* depend on a configured kernel, then we have a problem. I currently have a discussion going on over on gentoo-releng mailing list discussing possible permanent solutions to this problem. Unfortunately, I cannot think of any that work properly aside from telling users that we won't support anything less than a stage3 installation to not offering any stages prior to stage3 for download. As the complexity of Gentoo increases, the likelyhood of us hitting more and more of these errors that simple cannot be tested for in a reasonable amount of time is going to only increase. I would go so far as to add something in a <warn> block stating something similar to #3 my original post. Release Engineering does not recommend that *anyone* use *anything* but a stage3 tarball for *any* reason unless they are intimately familiar with toolchains and programming and are willing to troubleshoot and repair any possible problems that occur during their installations, as only the default set of USE flags are tested for any given architecture. There seems to be enough reason to reopen... Created attachment 72245 [details, diff]
Patch to Gentoo docs regarding stage1/2 deprecation
First attempt at deprecating stage1/2 from the handbook (but not from the
gentoo docs of course).
I'm not sure if I got this wrong. I have always been using a stage1 to do my installs, because I didn't know any better, and like being able to customize things. Leaving users with stage3 would be a bad thing, since several of the packages of the virtuals have been installed (like nano, instead of vim/emacs), so the user has to remove these and their dependencies manully, which might be more complicated that just using a stage2 and going from there with the virtuals you want. I'm I getting it wrong? It keeps surprising me why people often refuse to read... """ The stage1 or stage2 installations will remain possible and will even remain documented and officially maintained """ We are just going to put the information elsewhere, outside the handbook. Going, going, gone... Committed. Now, the bootstrapping/system stuff is part of the Gentoo FAQ. swift++ Thanks for getting this done. I'm hoping that having it removed from the Handbook will reduce the number of erroneous bug reports that get filed, along with the number of people wasting time with a stage1 installation. I like the changes made to the handbook - and they make a lot more sense - but it seems to me that there should be some section in there that mentions something to the effect of: "If you would like to better optimize your system (and get a system similar to one that was previously installed using a stage 1 tarball), you should run the following command: emerge -e world Note: This is an OPTIONAL step, and will take a LONG TIME" Maybe this would make best sense in the "Where to go from here" or "Finalizing your Gentoo Installation" sections I'd tend to agree... and definitely somewhere at the bottom... I'd probably say in the "Where to go from here" section, simply because we don't want people doing an "emerge -e world" on a networkless install... Though it is slightly out of scope for the *installation* part of the Handbook To me the changes tend to sound "debianish", in a sense that a complete newcomer cannot understand the buzz around the stages and the related /etc/make.conf variables. Example: "If the CHOST variable does not look correct to you, you might be using the wrong stage3 tarball." How can he tell what value of CHOST is wrong and what is right? One might well get the feeling that we are telling him something like: "Here's something you don't know about; and we won't explain what it is to a fool like you as you will never get it, but anyway, if it has the wrong value, you got the wrong stage3 tarball." I know, it's not said that way _at all_, but that might be an interpretation coming from the fact that essential information is missing. A decent explanation is due, or the handbook tends to sound unfriendly and obscure for noobs. Gentoo used to be the most open and friendly distro I could think of, with the most honest and transparent guide. I would volunteer with a suggestion for edition, if that would be at least considered. What does any of that have to do with *this* bug? If you think the CHOST section needs a bit of revamping, feel free to open a bug on it. The changes that I have requested have been fulfilled. > What does any of that have to do with *this* bug? At least _some_ of that has, if you read carefully. I treat the changes subject to *this* bug. The CHOST part is only an illustration. > If you think the CHOST section needs a bit of revamping, feel free to open > a bug on it. The changes that I have requested have been fulfilled. Good suggestion -- thanks; I'll consider it. I will appreciate if Release Engineering Team can provide and maintain two tracks of installation handbook: one is for the impatient who need only the flexibility of the gentoo installation--that's the stage 3 route; also that can be the recommended way of install a gentoo. The other is for those bravehearts who don't fear the wasted time and torture of some troubleshooting according to his/her knowledge/skills in GNU/linux(though it should be bug-free if s/he follow the handbook exactly), that can be called Advanced Gentoo Installation Handbook, if you like. In fact, many users (included me) switched from other distros of linux to gentoo just because the beauty of gentoo that can build up its dominance only from a few tools installed on any flatform(that's really a fascinating idea). Personally, I don't think FAQ is a right place to hold stage1 and stage2 installation as it is too short and not go up with every release. Also doing an information hiding of stage1 or stage2 won't reduce the silly questions asked by newusers as it deprives the chance of users to learn from the try-and-error process, that will make users dumber--that will bring up more problems during his/her using gentoo or make them dump the gentoo completely. To cultivate user I will appreciate if Release Engineering Team can provide and maintain two tracks of installation handbook: one is for the impatient who need only the flexibility of the gentoo installation--that's the stage 3 route; also that can be the recommended way of install a gentoo. The other is for those bravehearts who don't fear the wasted time and torture of some troubleshooting according to his/her knowledge/skills in GNU/linux(though it should be bug-free if s/he follow the handbook exactly), that can be called Advanced Gentoo Installation Handbook, if you like. In fact, many users (included me) switched from other distros of linux to gentoo just because the beauty of gentoo that can build up its dominance only from a few tools installed on any flatform(that's really a fascinating idea). Personally, I don't think FAQ is a right place to hold stage1 and stage2 installation as it is too short and not go up with every release. Also doing an information hiding of stage1 or stage2 won't reduce the silly questions asked by newusers as it deprives the chance of users to learn from the try-and-error process, that will make users dumber--that will bring up more problems during his/her using gentoo or make them dump the gentoo completely. To cultivate users ability to face problem bravely (and even solve some problems by themselves) step by step by expose all information to them is a great philosophy of gentoo. *sigh* This bug is CLOSED. The bug requestor has had his request filled. Quit posting your opinions to this bug. This is *not* a discussion forum. (In reply to comment #28) > I will appreciate if Release Engineering Team can provide and maintain two > tracks of installation handbook: one is for the impatient who need only the > flexibility of the gentoo installation--that's the stage 3 route; also that Release Engineering does not maintain the Handbook, which is why this bug is here in the first place. > be the recommended way of install a gentoo. The other is for those bravehearts > who don't fear the wasted time and torture of some troubleshooting according to > his/her knowledge/skills in GNU/linux(though it should be bug-free if s/he > follow the handbook exactly), that can be called Advanced Gentoo Installation So you want an "Advanced" Handbook that has exactly 0 "advanced" topics in it? Somehow, I think that would be a waste of time for our documentation team to keep up with. > Handbook, if you like. In fact, many users (included me) switched from other > distros of linux to gentoo just because the beauty of gentoo that can build up > its dominance only from a few tools installed on any flatform(that's really a Nobody is taking away that ability. This is what you seem to be missing out on here. I have already answered this *several* times in this bug. YOU ARE NOT LOSING ANYTHING WITH THIS CHANGE. Also, for those of you that bought into the "stage1 is good" misinformation, I regret to inform you that you bought into a lie and an illusion. I know that it hurts to be told that your beliefs are unfounded, but it is the truth. If you're doing a stage1 or even a stage2 installation, you are wasting your time. This is even more so if you are not *personally* modifying the bootstrap process to do something that *is not achievable* via portage. Following the old stage1 instructions is 100% achievable by doing a stage3, customizing, then running emerge -uDN world && emerge -v depclean. 100% achievable. > fascinating idea). Personally, I don't think FAQ is a right place to hold > stage1 and stage2 installation as it is too short and not go up with every > release. Also doing an information hiding of stage1 or stage2 won't reduce the > silly questions asked by newusers as it deprives the chance of users to learn > from the try-and-error process, that will make users dumber--that will bring Users do not learn a damn thing by typing in: scripts/bootstrap.sh emerge -e system I'm sorry, but that is a simple truth. Giving them the lower stage options *does* increase the chances of errors immensely. > more problems during his/her using gentoo or make them dump the gentoo > completely. To cultivate user *sigh* This bug is CLOSED. The bug requestor has had his request filled. Quit posting your opinions to this bug. This is *not* a discussion forum. (In reply to comment #28) > I will appreciate if Release Engineering Team can provide and maintain two > tracks of installation handbook: one is for the impatient who need only the > flexibility of the gentoo installation--that's the stage 3 route; also that Release Engineering does not maintain the Handbook, which is why this bug is here in the first place. > be the recommended way of install a gentoo. The other is for those bravehearts > who don't fear the wasted time and torture of some troubleshooting according to > his/her knowledge/skills in GNU/linux(though it should be bug-free if s/he > follow the handbook exactly), that can be called Advanced Gentoo Installation So you want an "Advanced" Handbook that has exactly 0 "advanced" topics in it? Somehow, I think that would be a waste of time for our documentation team to keep up with. > Handbook, if you like. In fact, many users (included me) switched from other > distros of linux to gentoo just because the beauty of gentoo that can build up > its dominance only from a few tools installed on any flatform(that's really a Nobody is taking away that ability. This is what you seem to be missing out on here. I have already answered this *several* times in this bug. YOU ARE NOT LOSING ANYTHING WITH THIS CHANGE. Also, for those of you that bought into the "stage1 is good" misinformation, I regret to inform you that you bought into a lie and an illusion. I know that it hurts to be told that your beliefs are unfounded, but it is the truth. If you're doing a stage1 or even a stage2 installation, you are wasting your time. This is even more so if you are not *personally* modifying the bootstrap process to do something that *is not achievable* via portage. Following the old stage1 instructions is 100% achievable by doing a stage3, customizing, then running emerge -uDN world && emerge -v depclean. 100% achievable. > fascinating idea). Personally, I don't think FAQ is a right place to hold > stage1 and stage2 installation as it is too short and not go up with every > release. Also doing an information hiding of stage1 or stage2 won't reduce the > silly questions asked by newusers as it deprives the chance of users to learn > from the try-and-error process, that will make users dumber--that will bring Users do not learn a damn thing by typing in: scripts/bootstrap.sh emerge -e system I'm sorry, but that is a simple truth. Giving them the lower stage options *does* increase the chances of errors immensely. > more problems during his/her using gentoo or make them dump the gentoo > completely. To cultivate users ability to face problem bravely (and even Again, we aren't out to make market share. If some users are upset by these decisions, while we hate to see them go, that is their choice. We are not planning on leaving around a broken process simply so a few misinformed users can have their warm fuzzies. > some problems by themselves) step by step by expose all information to them is > a great philosophy of gentoo. You're more than welcome to build your own stage1 tarballs and support them yourselves. The Release Engineering team will not be supporting them. At some point in the near future, we probably will not even be releasing stage1 tarballs, possibly as soon as the next release. Again, I am sorry if you bought into the illusion that you're actually gaining anything from watching compiler text scroll by faster than you could possibly read it. I would like to conclude this by saying, once again, that this is not a discussion forum. This is a bug. The bug poster has had his request filled by the appropriate party and his request has been fulfilled. If you want to continue to discuss this, take it to a mailing list or the forums. Do not post any more opinions to this bug, they aren't being asked for, nor are they warranted. To keep from having to see more of this, I'm filtering emails from this bug, so there is no point in responding, as again, this is not a discussion. Also, for the rest of the comments that are here or will be, chances are high that a bootstrapping guide will emerge from the input I'm gathering about bootstrapping: when is it needed, how to do it properly, what it entails, etc. /And/ the stage12 stuff is at http://www.Gentoo.org/doc/en/faq.xml#stage12 |