Handbook Release Guide
This document is intended to help the handbook release coordinator (and/or other
GDP members and contributors) tackle the massive task of bringing all the
handbooks and related documentation up-to-date for the latest Gentoo Linux
It's designed to take some of the pain and stress out of a free-form, unplanned
process and instead introduce a bit of logical order. All too often, the burden
of updating all documentation tends to fall on just one single person (as this
author can attest to on multiple occasions). Whether or not that happens for a
particular release, this guide still provides a smart, sensible plan for getting
docs ready to go.
This document will provide guidelines on what to do and when to do
it, though these are just guidelines; there are few hard rules, except when it
comes to GuideXML coding and commit rules, as explained in such documents as the
the GuideXML Guide and the Documentation Tips and
What to Monitor
In order to plan your tasks and estimate completion dates for TODO items, you'll
need to have an idea of when the next release is. Gentoo operates on a so-called
rolling release schedule. Packages are updated constantly; a new release
of Gentoo is merely an update to the installation media, stages, Portage
snapshots, and so on. However, this always entails a huge change in the
Installation Handbook and other related documentation, as they have to be
brought in line with the new installation media.
New releases occur about every 6 months, though this is not set in stone, so be
sure to constantly check the release
roadmap for updates. Also be sure to check with Release Engineering
(releng) team members in person as release time grows nearer, just in case the
roadmap hasn't been updated.
By far the most important items to update are the handbooks.
Handbook: the biggest handbook. This is your first priority, as it's
where users go when they want to install Gentoo. The handbook for each
architecture requires time, energy, and TLC. The handbook comes in two
flavors, networked and networkless. Both are of about equal
priority, though just before release, you'll want to focus a bit more on
keeping the networkless handbook completely ready to go, as releng will need
tarballs of it to put on the LiveCDs in advance of the actual release date.
Doesn't change nearly as often as the Installation Handbook, but still needs
to be updated for new configuration files and names, such as
/etc/make.conf and /etc/conf.d/ changes. The other Portage Handbook
is more in-depth. Check with the baselayout and Portage maintainers to make
sure the information is up-to-date.
This will be updated about as often as the major networking configuration
sections of the Installation Handbook are updated, as some of the
information is similar. Again, check with the baselayout and Portage
maintainers to make sure the information is current.
Not all the Portage/Networking handbook files will change, so it may be better
to just copy over only the ones you know will be changing when you start
updating them. Be sure of which files actually need to be changed. Again,
communication and coordination!
Variables and conditional includes are a lifesaver. Use them! Arch-specific
items that constantly change, such as ISO size, recommended CFLAGS, kernel
versions, etc. are kept in the handbook-$arch files, right at the top. Releng
will know about CD boot parameters, media/download size, and minimum system
requirements, as well as available media and their filenames. Arch teams will
know about CFLAGS and kernel names & configuration, as well as suggested
partitioning schemes and specific tools to emerge/use.
Whenever possible, try to get arch team members to help you keep track of all
the changing information from release to release. See if they have a dedicated
liaison to assist with verifying documentation changes; it's even better if they
have someone who can submit GuideXML patches, so don't hesitate to ask! So be
sure to CC the arch teams on the handbook release tracker bug to keep them in
Sometimes releases will offer enough changes that a new chapter or even a whole
new handbook has to be written, or may even be removed. As much as possible
while remaining practical, try not to duplicate information across
separate arch handbook files. Instead, see if you can combine them into a single
file through smart use of conditional includes. When these kinds of
additions/subtractions occur, you'll need to make the appropriate alterations to
the handbook-$arch files.
Besides the handbooks, you will also need to simultaneously update the following
documents to keep them in line with the handbooks. Docs come and go but these
are currently the most critical files to keep track of.
Quick Install Guides, including the ones for x86, Sparc, FreeBSD, and
any other arch for which we have a quick install guide in
/doc/en/. This includes any Alternative Installation Method-type
guides, LVM2 guides, Installation Tips &
Tricks, and the like.
FAQs, including the general FAQ and
arch-specific FAQs, such as for AMD64, PPC, Sparc, etc. Also included here
are any arch-specific requirements or compatibility guides, such as for
MIPS. Anything for which support may change from release to release; you
will need to contact the various arch teams to find out.
The LiveUSB HOWTO, for the folks that
want to use a USB key instead of installation CDs. Check to make sure that
boot parameters are still correct, as well as the process of creating the
Upgrade guides, such as the Gentoo Upgrading Guide, as this
doc contains profile upgrading information. Most releases include new
profiles and deprecate or remove old profiles. Also, any changes introduced
by baselayout between releases will have their upgrading information covered
Kernel Configuration Guide. Keep
the available and recommended options in this file synchronized with what's
in the Installation Handbook.
metadoc.xml, which will contain updated links to the current
handbook files, both networked and networkless
Remember, before you commit any change to a document, validate the file with
xmllint --valid --noout. Quality! Aim for technical and process
perfection. It will save you grief when it comes time for the actual
Avoid mixing spelling, grammar, or GuideXML coding style fixes (non-content
changes) with procedural/informational fixes (content changes), otherwise
translators will get out their knives and come for you. You don't want that. Try
committing content fixes first, then the non-content fixes.
Don't bother bumping dates when you're working on your offline drafts. Save the
final date bump for the final "live" commit. However, you may want to make the
correct version bump ahead of the "live" commit, just to get it out of the way.
It's also a handy indication of whether or not you've remembered to touch the
file. When you're ready for the final commit, be sure to verify the version and
dates for each file. (Bring some caffeine; the process is tedious but
As much as possible, try to keep section text and layout (including order)
identical across the other arch handbooks, especially for shared content.
If you do include <-- TODO comments --> in the docs as notes to yourself,
be sure to remove them before committing the finished document; don't clutter
When you're ready for the "live" commit, don't forget to remove any draft
disclaimers from file links.
The following procedures do not have to be done in the specified order,
but they are recommended. They will help you make efficient use of your time,
with as few errors as possible. This procedure order (or something close to it
;)) has worked pretty well for the last few releases.
The very first thing you should do is open a handbook release tracker
bug. CC the arch teams, releng, and anyone else essential to the process of
updating the handbooks; you'll need their help for the content, as well as the
help of your fellow GDP members to put it all together. Once that's done, you
can get down to the business of actually editing the documents. Keep the GDP and
other project members informed about your progress by posting status updates to
the bug and sending out email as necessary.
Start with the installation handbooks:
Create the new networkless handbook directory; e.g.
Copy all current networkless handbook files into this new networkless
directory. It's okay that this is actually a "live" directory -- you just
won't be linking any of the files from index pages.
Copy the current networked handbook files into handbook/draft/
Commit these additions. Make it a straight copy with no
modifications! Otherwise, translators will hate you for making it hard to
follow your changes.
Edit the networkless handbook-$arch.xml pages, making sure they have the
draft disclaimer in their file link
Go through and renumber old release names/numbers to the upcoming one, e.g.
2007.0 --> 2007.1. Now is also a good time to make the major version mumber
bump for each page. Each new release gets a major <version> number
bump. Thus, 2007.0 references in hb-install-kernel.xml become
2007.1 and the file's <version> gets bumped from 7.4 to 8.0. If it's
4.3, it becomes 5.0, and so on.
Begin making content and non-content changes to the files, being careful not
to mix the two. Remember that most changes will apply to both networked and
networkless handbooks, but not all, so be careful when you're doubling up
your commits. Also, watch out for handbook changes that also need to be
propagated to non-handbook files, such as FAQs.
Make the necessary changes to non-handbook files, but try to keep those
changes offline, as explained below.
Be careful when working on files outside of /handbook/! If the
updated information you're adding to these documents won't hurt users now
and is not otherwise premature, go ahead and commit those changes to the live
documents. Otherwise, you should keep your changes offline, on your local
machine only. Also, be careful that you aren't altering the handbook files
inside the top-level /handbook/ directory; make sure you're
committing your changes only to /handbook/draft/ and
Preparing the on-disc networkless handbooks
You'll need to have the networkless handbooks ready some days in advance of the
actual release date, as releng will be placing them into the disc ISOs ahead of
time. Obviously, you must keep the networkless handbooks as current and perfect
as possible; ideally with version bump, and even a date bump, just before it
comes time to roll them up into the tarball.
Unfortunately, the GDP no longer has a working script to convert handbooks into
the HTML version that goes on the disc. Instead, use the rendered HTML source
code online in /handbook/$new-release/. Download the all-in-one
Printable version of the required arch handbook's source code using your
favorite browser and save it as index.html.
Code Listing 4.1: Creating the on-disc handbook
$ mkdir -p handbook/html/css
$ cd handbook/html/
$ mv ../../index.html ./
$ wget http://www.gentoo.org/css/main.css -O css/main.css
Next you'll need to edit the HTML file with your favorite editor. Change the CSS
link in the document's head to css/main.css as shown:
Code Listing 4.2: Editing handbook-sparc.html
<link title="new" rel="stylesheet" href="css/main.css" type="text/css">
Save your changes, then tar up the top-level handbook directory you
created. Save it as handbook-arch.tar.gz (where arch is
the name of the architecture), then pass it on to releng. Repeat for each
architecture that has a networkless installation handbook.
Committing, including the final release
Once you think you're ready for the release, go back through each of your
files and verify that the XML is valid and well-formed. Fix any
errors now, not when you go to make the final commit.
- Verify that the file version and date have been properly bumped
Remove the draft disclaimers from the networkless handbook-$arch index
- Remove any <-- TODO --> comments or other notes to yourself.
Make sure that you've tarred up the networkless handbooks and given them to
releng for the install CDs, as outlined previously.
Move the files from handbook/draft/ into
handbook/, overwriting the old ones and removing outdated files
- Make sure metadoc.xml is correct
Manually verify that each and every single file you touched is the way you
want it. (Got your caffeine handy?)
Make sure you haven't forgotten any patches or content from the handbook
release tracker bug.
Once you're satisfied that everything is ready, cd into the topmost
directory, usually /doc/en/ and make an atomic commit;
that is, commit everything at once so it all goes "live" at the same time.
Communicate with your fellow developers: send announcements/status updates
to the tracker bug and to any required mailing lists
- Take a deep breath
Go back and re-examine every single file you just committed. Have you been
watching gentoo-doc-cvs? ;) There's almost always something that was
overlooked; now is the time to make sure you aren't forgetting any content.
Eventually, once the release is out the door and everything is more-or-less
straightened out, you can go ahead and close that tracker bug. Feels good,
doesn't it? Now you get to fix the user and developer bug reports as they come
And then, before you know it, it'll be time to begin the release cycle all
over again . . . :)
Pre-release Quick Checklist
Here's an abbreviated version of most of the above, to be done immediately
before the final "live" commit:
Networked handbook files in handbook/draft/. Check the
handbook-$arch pages. Fix inter/intra-document links, release version
numbers, and file/date revbumps.
The handbook index.xml pages; check the listed translations and
Networkless handbook files in handbook/$new-release/. Same
checks as the networked files. Remove draft disclaimers.
Networking handbook check for handbook/draft/: current and
Portage handbook check for handbook/draft/: current and
Security handbook check for /doc/en/security/: this is
low-maintenance, but check anyway
Check /doc/en/ for pending changes to these top-level files.
Includes quickinstalls, FAQs, upgrade guides, kernel guides, etc.
metadoc.xml check: verify the files that make up the new
release. Overwrite the old ones listed and revbump metadoc.
Validate every single file in /doc/en/,
handbook/draft/,and handbook/$new-release/ with
xmllint --valid --noout. Yes, again. Fix errors.
- Check the handbook release tracker bug for any remaining tasks
cd to /doc/en/ and make your atomic commit.
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.
Page updated April 22, 2008
This guide details the process for updating the handbooks and related
documentation for each new Gentoo Linux release.
Donate to support our development efforts.