Handbook Release Guide

Joshua Saddler  Author

Updated April 22, 2008

1.  Introduction

Purpose

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 release.

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 Tricks.

2.  What to Monitor

Release dates

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.

Handbooks

By far the most important items to update are the handbooks.

  1. Installation 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.
  2. Portage Handbook: 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.
  3. Network Handbook: 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.

Note: 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 the loop.

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.

Other documents

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.

3.  Committing

General guidelines

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 release.

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 necessary.)

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 it up.

When you're ready for the "live" commit, don't forget to remove any draft disclaimers from file links.

4.  Suggested Procedures

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.

Important: 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.

Editing drafts

Start with the installation handbooks:

  1. Create the new networkless handbook directory; e.g. handbook/2007.1/
  2. 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.
  3. Copy the current networked handbook files into handbook/draft/
  4. Commit these additions. Make it a straight copy with no modifications! Otherwise, translators will hate you for making it hard to follow your changes.
  5. Edit the networkless handbook-$arch.xml pages, making sure they have the draft disclaimer in their file link
  6. 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.
  7. 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.
  8. Make the necessary changes to non-handbook files, but try to keep those changes offline, as explained below.

Important: 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 /handbook/$new-release/.

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

(Create the directory you'll be tarring up)
$ mkdir -p handbook/html/css
$ cd handbook/html/
(Move the HTML file here)
$ mv ../../index.html ./
(Download Gentoo's CSS)
$ 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

  1. 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.
  2. Verify that the file version and date have been properly bumped
  3. Remove the draft disclaimers from the networkless handbook-$arch index pages.
  4. Remove any <-- TODO --> comments or other notes to yourself.
  5. Make sure that you've tarred up the networkless handbooks and given them to releng for the install CDs, as outlined previously.
  6. Move the files from handbook/draft/ into handbook/, overwriting the old ones and removing outdated files where necessary.
  7. Make sure metadoc.xml is correct
  8. Manually verify that each and every single file you touched is the way you want it. (Got your caffeine handy?)
  9. Make sure you haven't forgotten any patches or content from the handbook release tracker bug.
  10. 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.
  11. Communicate with your fellow developers: send announcements/status updates to the tracker bug and to any required mailing lists
  12. Take a deep breath
  13. 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 in!

And then, before you know it, it'll be time to begin the release cycle all over again . . . :)

5.  Pre-release Quick Checklist

Here's an abbreviated version of most of the above, to be done immediately before the final "live" commit:


The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.