Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 197814 - [TRACKER] 2008.0 Handbook Changes
Summary: [TRACKER] 2008.0 Handbook Changes
Status: RESOLVED FIXED
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Installation Handbook (show other bugs)
Hardware: All Linux
: Highest normal (vote)
Assignee: nm (RETIRED)
URL: http://www.gentoo.org/proj/en/gdp/doc...
Whiteboard:
Keywords: Tracker
Depends on: 179796 208738
Blocks:
  Show dependency tree
 
Reported: 2007-11-01 20:41 UTC by nm (RETIRED)
Modified: 2017-01-19 18:47 UTC (History)
14 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description nm (RETIRED) gentoo-dev 2007-11-01 20:41:02 UTC
Here it is. Send in any changes that need to be made to our installation handbooks and other related documentation, for all architectures.

As releng has mentioned, the final snapshot date is the 9th, so I'd appreciate you getting any requested changes or (EVEN BETTER) *patches* in to me by then.

This is a high-priority task, so I'd like to get everything in ASAP; I don't want to have to *drag* the changes out of people as I have in past releases; I want us to work together and keep the communication flowin'. :)

Arch teams: please refer to the document in the URL field. Notice the documents that are mentioned in Chapter 2--these are what will be changed, so take a look at the kind of information in them and tell me if it's now outdated for 2007.1.

Releng: as usual, let me know about things like boot parameters, new media/iso/stage sizes, hardware requirements, kernel versions, etc. Also maybe you and UberLord will know what version of baselayout is used, so that any new config changes in there can be propagated to the new handbook.

GDP: as always, time is short for us, so I'll see about handing out some tasks or otherwise getting you to "volunteer" your time, if possible. ;)

Thanks! Here's to a great release. :)
Comment 1 Chris Gianelloni (RETIRED) gentoo-dev 2007-11-02 18:24:57 UTC
...nice... thanks for the date leak...

What part of "this is private information" wasn't clear in my email to -core?  I don't even know why I try sometimes.  Oh well, I'll just direct people to you when they ask what's going on when the date slips.

There's one set of changes that I'm sure you'll need.  I've changed dolvm2 and doevms2 to dolvm and doevms.  The older ones will still work, but are deprecated.

We're using baselayout-1.12.9-r2 for the release unless there's some bug/change that we need between now and the release.
Comment 2 Robin Johnson archtester Gentoo Infrastructure gentoo-dev Security 2007-11-02 21:35:29 UTC
locking bug to devs
Comment 3 nm (RETIRED) gentoo-dev 2007-11-03 21:43:56 UTC
Thanks Chris for the boot info; I changed it in the appropriate networkless handbooks, which is the only place I found it listed. However, I did notice that the regular networked handbooks for at least x86/amd64 do mention "nolvm2" and "noevms2" or whatever; should those also be changed?

* * *

MIPS (and GDP): I kicked out the extraneous hb-install-mips-system file, opting to instead use a conditional "profile" key to display when browsing the main hb-install-system file that all the other arches use. Less maintenance headache, but do let me know if this is indeed okay. We already talk about profiles in the Gentoo Upgrading Guide, anyway. I'd like to kick out the mips-stage file too, but after review it looks quite hard to clean up to fit in to the all-arches stage.xml file, so it will stay in for this release.
Comment 4 Chris Gianelloni (RETIRED) gentoo-dev 2007-11-04 18:12:52 UTC
(In reply to comment #3)
> Thanks Chris for the boot info; I changed it in the appropriate networkless
> handbooks, which is the only place I found it listed. However, I did notice
> that the regular networked handbooks for at least x86/amd64 do mention "nolvm2"
> and "noevms2" or whatever; should those also be changed?

They should.

Everything has a do*/no* pair.  In most cases, only one or the other is "usable" since things are either defaulted to on or off, with everything enabled that won't potentially cause lock-ups.
Comment 5 Łukasz Damentko (RETIRED) gentoo-dev 2007-12-04 13:29:53 UTC
It wasn't November the 9th so no need to conceal the bug.
Comment 6 Andrew Gaffney (RETIRED) gentoo-dev 2007-12-05 01:51:24 UTC
For x86/amd64 GTK+ frontend section:

* Remove the following sections:
 - Welcome
 - Network mounts
 - make.conf
 - Kernel sources
 - Daemons
 - Bootloader

* Umm, that's about it. The only thing that really changed was networkless is
  now not a choice, so all the options for non-networkless are gone.
Comment 7 Preston Cody (RETIRED) gentoo-dev 2007-12-05 14:17:50 UTC
The same basic info as Andrew just posted goes for the gli-dialog as well.  Networkless mode is now no-longer a choice, and neither is there an "advanced" mode.  The installer is now much simpler and harder for a user to screw up.
Comment 8 Christian Faulhammer (RETIRED) gentoo-dev 2007-12-06 19:34:58 UTC
Doing a manual test installation (maybe I find time to test the installer) worked fine...I tried to read the handbook :) and actually found no errors...just fyi.
Comment 9 nm (RETIRED) gentoo-dev 2007-12-09 03:07:09 UTC
Status report:

-x86/amd64
Updated boot parameters (comment #4)
Updated gtkfe handbook (comment #6)
Updated dialog handbook (comment #7)

There are more updates pending for the Sparc and IA64 handbooks.

- MIPS: what's up? Any changes?

- PPC/PPC64: Still want to merge the handbooks for this release? I'd at least like to get the content changes in and worry about the internal formatting afterward. I don't mind continued partial duplication. Well, not all that much.

- Alpha: I got an email indicating that you'll have networkless media for this release. If this is indeed the case, then I need you to review the 2006.1 networkless handbook (http://www.gentoo.org/doc/en/handbook/2006.1/handbook-alpha.xml) and report any changes to be made, ASAP.

- ARM: vapier, anything new?
Comment 10 Xavier Neys (RETIRED) gentoo-dev 2007-12-15 14:00:18 UTC
(In reply to comment #8)
> Doing a manual test installation (maybe I find time to test the installer)
> worked fine...I tried to read the handbook :) and actually found no
> errors...just fyi.

Much appreciated. Thanks for your feedback.

(In reply to comment #7)
> The same basic info as Andrew just posted goes for the gli-dialog as well. 
> Networkless mode is now no-longer a choice, and neither is there an "advanced"
> mode.  The installer is now much simpler and harder for a user to screw up.

Since the 20xx.y/* handbooks are specifically linked to for networkless installs, it's about time we ditched those handbooks. All they need is a mention in the regular handbook, something like "If you are using the LiveCD, now either start the installer and follow the on-screen instructions or keep on reading to perform a regular manual installation."
Comment 11 Jason Alexander 2008-01-27 22:45:27 UTC
Configuring the Kernel:
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=7

There should be an option here, possibly part of the manual, that explains how to use genkernel on an existing .config.  If you follow the manual steps on this chapter, you will not get an initramfs.  Creating one manually is time consuming and unnecessary, since genkernel will do it.

An alternative to "make && make modules_install" would be to do "genkernel --no-clean --install-all", or at least point the user to look at the genkernel options to use it to build with an existing .config.

It was a little unhelpful for me, as I was installing luks/lvm on the root partition and needed a custom kernel (and did not realize genkernel could do what it did for me).  There were some instructions on luks in other places, but they were unnecessarily tedious.  All I had to do was configure in the right kernel options and do: 
genkernel --no-clean --luks --lvm2 --no-splash --install all

Thanks.
Comment 12 Chris Gianelloni (RETIRED) gentoo-dev 2008-01-28 15:45:13 UTC
Indeed.  Only amd64/x86 use the installer currently, but I'd like to eventually change that.  Most architectures haven't been shipping GRP packages, anyway, so only the distfiles on the Universal are usable for a networkless  install.
Comment 13 nm (RETIRED) gentoo-dev 2008-01-28 18:42:06 UTC
(In reply to comment #11)
> There should be an option here, possibly part of the manual, that explains how
> to use genkernel on an existing .config.  If you follow the manual steps on
> this chapter, you will not get an initramfs.  Creating one manually is time
> consuming and unnecessary, since genkernel will do it.

. . . except the handbook is about *initial* installation, without a previous .config from a prior install/existing installation. We don't need to cover using genkernel for these corner cases.

A better place for such information would be the genkernel guide at http://www.gentoo.org/doc/en/genkernel.xml. Most of the stuff you mentioned is already present in that guide. However, since we haven't had any content updates for the guide in a few years, we had to mark it "obsolete". If someone cares to do a thorough review & rewrite for all the genkernel changes since 2005, we'd be happy to update it with new stuff. Until then, though . . .
 
> An alternative to "make && make modules_install" would be to do "genkernel
> --no-clean --install-all", or at least point the user to look at the genkernel
> options to use it to build with an existing .config.

Did you notice that there's a separate section with separate install instructions for genkernel? Search for "genkernel all".

RESO WONTFIX.
Comment 14 nm (RETIRED) gentoo-dev 2008-01-30 10:53:13 UTC
Renamed the bug.

Also, I need a GDP member to (sanely) rename all our 2007.1/ directories in CVS and move 'em over to 2008.0. Or to just call the thing "networkless" and not bother to archive them ever again. Which I am all in favor for; it would make updates far, far easier.

Along with that is the usual s/2007.1/2008.0 for the text inside the files.
Comment 15 Andrew Gaffney (RETIRED) gentoo-dev 2008-02-25 02:40:25 UTC
There are a few global changes on top of what we had for 2007.1:

* new kernel (currently 2.6.23-gentoo-r8)
* new genkernel initramfs options:
  - dosshd (starts sshd)
  - passwd=foo (sets whatever is after the = as the root password)
* new profile structure

The new profile structure is the doosey. Chris will be able to give you a lot more details on the profiles.
Comment 16 Chris Gianelloni (RETIRED) gentoo-dev 2008-02-25 03:23:08 UTC
Actually, the profiles are easy.  I changed default-linux to default/linux.  If you were using:
  default-linux/amd64/2007.0/desktop
you would now use:
  default/linux/amd64/2008.0/desktop

It isn't much of a change from the way things are done now.  What *has* changed fairly dramatically is the layout of the profiles and their inheritance structure, which is transparent to the end user.
Comment 17 Dawid Węgliński (RETIRED) gentoo-dev 2008-02-29 08:23:23 UTC
Can we also get rid of using `USE="foo" emerge bar` in 2008.0 handbook in favour of using package.use file? I mean listing 4.1 in Installing Necessary System Tools chapter:

# USE="-gtk" emerge evms
Comment 18 Santiago M. Mola (RETIRED) gentoo-dev 2008-02-29 09:35:34 UTC
(In reply to comment #17)
> Can we also get rid of using `USE="foo" emerge bar` in 2008.0 handbook in
> favour of using package.use file? I mean listing 4.1 in Installing Necessary
> System Tools chapter:
> 
> # USE="-gtk" emerge evms
> 

The use of USE environment variable is quite correct during the instalation, when the user wants to install something without installing all X packages. But later, when they system is installed, they'll want to use USE="gtk X" and such.
Comment 19 nm (RETIRED) gentoo-dev 2008-02-29 13:14:16 UTC
GDP: Today (Feb 29) is our deadline to get at least the networkless & Portage handbooks done. I'll have to tarball them up by the end of the day and send them off to releng. (We ship an everything-on-one-page handbook for the appropriate arch).

I need one of you to make the appropriate 2007.1 --> 2008.0 version number changes in each file. It's just a small thing, but this small thing will drive me crazy. I could really use the help. I'll see about handling the *content* changes; I just need someone to fix the version numbers.

Arch teams, especially alpha, hppa, ia64, sparc: Who has a networkless release this year? Any other info that needs changing? Like kernel versions on the install media.

PPC/PPC64: you guys have been completely silent this whole time on what needs changing. What's up?

MIPS: Any changes for you? Drop the handbook completely? What?
Comment 20 nm (RETIRED) gentoo-dev 2008-03-01 08:30:32 UTC
Status report:

- Networkless handbooks are done. Emailed tarballs to releng.
- Portage handbooks are done
- Updated kernel versions and renamed everything to to 2008.0 (comments 14, 15, 19)
- Added new boot options (comment #15)
- Updated profiles from default-linux/ to default/linux/ (comment #16)
- No change (comment #17)

Most of the networked handbooks are done too. Biggest thing for them is bug 179796, since it's listed as a blocker.

TODO: non-handbook files in /doc/en/
- gentoo-upgrading.xml
- metadoc.xml

Also:
- /main/en/where.xml
Comment 21 Łukasz Damentko (RETIRED) gentoo-dev 2008-03-06 18:28:33 UTC
In 2008.0/index.xml there's a bunch of links to 2008.0 national handbooks. The problem is that some of them don't exist yet and I doubt some of them will ever be created. 

Link not found - /doc/id/handbook/2008.0/
Link not found - /doc/it/handbook/2008.0/
Link not found - /doc/zh_cn/handbook/2008.0/

Please fix this page to have only links to existent documents. We will add them when translators actually create them.
Comment 22 Xavier Neys (RETIRED) gentoo-dev 2008-03-06 18:55:25 UTC
(In reply to comment #21)
> In 2008.0/index.xml there's a bunch of links to 2008.0 national handbooks.
> Please fix this page to have only links to existent documents. We will add them
> when translators actually create them.

Did you lose your commit rights?
Comment 23 Łukasz Damentko (RETIRED) gentoo-dev 2008-03-06 20:05:25 UTC
Nope. I just prefer to tell people before I start touching their things.
Comment 24 Davide Cendron (RETIRED) gentoo-dev 2008-03-08 18:38:37 UTC
/doc/it/handbook/2008.0/* online 8)

Sorry for the delay.

(i've seen that /doc/zn_ch/handbook/2008.0/* is ready, too)
Comment 25 Andrew Gaffney (RETIRED) gentoo-dev 2008-03-10 11:43:41 UTC
nightmorph, I believe you had mentioned getting us updated docs tarballs for the beta. Should we still be waiting on that, or should we just use what you gave us previously?
Comment 26 nm (RETIRED) gentoo-dev 2008-03-10 17:26:11 UTC
(In reply to comment #25)
> nightmorph, I believe you had mentioned getting us updated docs tarballs for
> the beta. Should we still be waiting on that, or should we just use what you
> gave us previously?

Yeah, just use the ones I originally sent in. I took another look at 'em, and there weren't really any showstopping procedural changes, mostly just internal XML stuff.

I'll send you updated tarballs for the final release by the 26th, as per the timeline.
Comment 27 Dawid Węgliński (RETIRED) gentoo-dev 2008-03-13 20:08:06 UTC
Just a quick note, current stable gentoo-sources on x86 is 2.6.24-r3.
Comment 28 Dawid Węgliński (RETIRED) gentoo-dev 2008-03-13 20:10:21 UTC
Sorry for bugspam, think you would like to refer bug #213283 for more info about other architectures.
Comment 29 Davide Cendron (RETIRED) gentoo-dev 2008-03-23 20:33:45 UTC
(In reply to comment #24)
> /doc/it/handbook/2008.0/* online 8)
> 
> Sorry for the delay.
> 
> (i've seen that /doc/zn_ch/handbook/2008.0/* is ready, too)
> 

PING

I wouldn't open a new bug for this thing, like #214347. Please, can you also add the link to Italian 2008.0 Handbook? It's ready to rock from several days 8)
Comment 30 nm (RETIRED) gentoo-dev 2008-04-01 09:01:43 UTC
Alright, the beta is released, so the handbooks are published. Note that they're still marked with disclaimer="draft", until it's time for the final release. However, they are live.

You may commit changes and fixes to them as usual, though there shouldn't be any ATM. We're back to normal version/date bumps, too, since I already made the major version bump.
Comment 31 Wim Muskee 2008-04-13 08:28:15 UTC
(In reply to comment #27)
> Just a quick note, current stable gentoo-sources on x86 is 2.6.24-r3.
> 

And from this kernel on, IDE disks are handled differently than before, so the following:

"Code Listing 3.4: Activating DMA

Device Drivers --->
  ATA/ATAPI/MFM/RLL support --->
    [*] Generic PCI bus-master DMA support"

should be removed from "Configuring the Kernel" as it is no longer there in 2.6.24
Comment 32 nm (RETIRED) gentoo-dev 2008-04-13 20:00:58 UTC
(In reply to comment #31)
Fixed.
Comment 33 Wim Muskee 2008-04-19 12:30:51 UTC
In hb-install-x86+amd64-medium.xml in the section on "Booting the Installation CD", gentoo-nofb is not listed as one of the available kernels for the amd64.

It is listed for the x86 and it is an available kernel option on the amd64 2008.0_beta1 minimal cd.
Comment 34 nm (RETIRED) gentoo-dev 2008-04-20 00:26:00 UTC
(In reply to comment #33)
> In hb-install-x86+amd64-medium.xml in the section on "Booting the Installation
> CD", gentoo-nofb is not listed as one of the available kernels for the amd64.
> 
> It is listed for the x86 and it is an available kernel option on the amd64
> 2008.0_beta1 minimal cd.

Actually, we already mention it:
"Specifying a kernel? Yes, we provide several kernels on our Installation CDs.
The default one is gentoo. Other kernels are for specific hardware needs
and the -nofb variants which disable framebuffer."

. . . it's just not listed in the table. Fixed in both handbooks.
Comment 35 Theo Chatzimichos (RETIRED) archtester Gentoo Infrastructure gentoo-dev Security 2008-06-05 19:44:31 UTC
In chapter Choosing the Right Installation Medium for Alpha (file hb-install-alpha-medium.xml) for network-based installation in 2.a section (subsection: Booting the Installation CD) there is a link to taviso's web site which doesn't exist any more
Comment 36 nm (RETIRED) gentoo-dev 2008-06-05 21:36:56 UTC
(In reply to comment #35)
> In chapter Choosing the Right Installation Medium for Alpha (file
> hb-install-alpha-medium.xml) for network-based installation in 2.a section
> (subsection: Booting the Installation CD) there is a link to taviso's web site
> which doesn't exist any more

I removed the link to taviso's devspace; he retired some time ago.

Alpha guys: is there any alternative for getting precompiled MILO images?

Comment 37 Tobias Klausmann gentoo-dev 2008-06-05 22:25:04 UTC
Since we lack the ability to test MILO stuff, we really don't quite support it anymore. If a user comes up with a problem, we'll try to help, but beyond that, no. So nuke the reference (and it's direct descendants) without replacement.
Comment 38 Theo Chatzimichos (RETIRED) archtester Gentoo Infrastructure gentoo-dev Security 2008-06-17 11:34:08 UTC
in hb-working-use.xml line 141 the 2004.3 profile's use flags are shown. don't you think this is a little outdated? :)
Comment 39 Theo Chatzimichos (RETIRED) archtester Gentoo Infrastructure gentoo-dev Security 2008-06-17 12:05:01 UTC
(In reply to comment #38)
> in hb-working-use.xml line 141 the 2004.3 profile's use flags are shown. don't
> you think this is a little outdated? :)
> 

same file, line 334 "These are the packages that would be merged, in order:" instead of "These are the packages that I would merge, in order:"
Comment 40 Christian Faulhammer (RETIRED) gentoo-dev 2008-07-06 09:25:03 UTC
Can we close this bug now?
Comment 41 nm (RETIRED) gentoo-dev 2008-07-06 10:09:42 UTC
(In reply to comment #40)
> Can we close this bug now?
> 

No. I'll leave it open for awhile in case there are some release document-related issues that pop up.
Comment 42 nm (RETIRED) gentoo-dev 2008-07-20 00:39:44 UTC
No issues reported; closing.