Gentoo Archives: gentoo-doc-cvs

From: Josh Saddler <nightmorph@××××××××××××.org>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] cvs commit: handbook-release.xml
Date: Fri, 19 Oct 2007 02:33:23
Message-Id: E1IihVJ-0004ji-Nk@stork.gentoo.org
1 nightmorph 07/10/19 02:22:25
2
3 Added: handbook-release.xml
4 Log:
5 added new guide on how to update the handbook and all other related documentation for each new release. it is a huge task, and this document will assist those who have the unenviable job of trying to do the release, often single-handedly.
6
7 Revision Changes Path
8 1.1 xml/htdocs/proj/en/gdp/doc/handbook-release.xml
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gdp/doc/handbook-release.xml?rev=1.1&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/gdp/doc/handbook-release.xml?rev=1.1&content-type=text/plain
12
13 Index: handbook-release.xml
14 ===================================================================
15 <?xml version="1.0" encoding="UTF-8"?>
16 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
17 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/handbook-release.xml,v 1.1 2007/10/19 02:22:25 nightmorph Exp $ -->
18
19 <guide link="/proj/en/gdp/doc/handbook-release.xml">
20 <title>Handbook Release Guide</title>
21
22 <author title="Author">
23 <mail link="nightmorph@g.o">Joshua Saddler</mail>
24 </author>
25
26 <abstract>
27 This guide details the process for updating the handbooks and related
28 documentation for each new Gentoo Linux release.
29 </abstract>
30
31 <!-- The content of this document is licensed under the CC-BY-SA license -->
32 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
33 <license/>
34
35 <version>1.0</version>
36 <date>2007-10-18</date>
37
38 <chapter>
39 <title>Introduction</title>
40 <section>
41 <title>Purpose</title>
42 <body>
43
44 <p>
45 This document is intended to help the handbook release coordinator (and/or other
46 GDP members and contributors) tackle the massive task of bringing all the
47 handbooks and related documentation up-to-date for the latest Gentoo Linux
48 release.
49 </p>
50
51 <p>
52 It's designed to take some of the pain and stress out of a free-form, unplanned
53 process and instead introduce a bit of logical order. All too often, the burden
54 of updating all documentation tends to fall on just one single person (as this
55 author can attest to on multiple occasions). Whether or not that happens for a
56 particular release, this guide still provides a smart, sensible plan for getting
57 docs ready to go.
58 </p>
59
60 <p>
61 This document will provide guidelines on <e>what</e> to do and <e>when</e> to do
62 it, though these are just guidelines; there are few hard rules, except when it
63 comes to GuideXML coding and commit rules, as explained in such documents as the
64 the <uri link="/doc/en/xml-guide.xml">GuideXML Guide</uri> and the <uri
65 link="/proj/en/gdp/doc/doc-tipsntricks.xml">Documentation Tips and
66 Tricks</uri>.
67 </p>
68
69 </body>
70 </section>
71 </chapter>
72
73 <chapter>
74 <title>What to Monitor</title>
75 <section>
76 <title>Release dates</title>
77 <body>
78
79 <p>
80 In order to plan your tasks and estimate completion dates for TODO items, you'll
81 need to have an idea of when the next release is. Gentoo operates on a so-called
82 <e>rolling release</e> schedule. Packages are updated constantly; a new release
83 of Gentoo is merely an update to the installation media, stages, Portage
84 snapshots, and so on. However, this always entails a huge change in the
85 Installation Handbook and other related documentation, as they have to be
86 brought in line with the new installation media.
87 </p>
88
89 <p>
90 New releases occur about every 6 months, though this is not set in stone, so be
91 sure to constantly check the <uri link="/proj/en/releng/index.xml">release
92 roadmap</uri> for updates. Also be sure to check with Release Engineering
93 (releng) team members in person as release time grows nearer, just in case the
94 roadmap hasn't been updated.
95 </p>
96
97 </body>
98 </section>
99 <section>
100 <title>Handbooks</title>
101 <body>
102
103 <p>
104 By far the most important items to update are the handbooks.
105 </p>
106
107 <ol>
108 <li>
109 <uri link="doc/en/handbook/handbook-x86.xml?part=1">Installation
110 Handbook</uri>: the biggest handbook. This is your first priority, as it's
111 where users go when they want to install Gentoo. The handbook for each
112 architecture requires time, energy, and TLC. The handbook comes in two
113 flavors, <e>networked</e> and <e>networkless</e>. Both are of about equal
114 priority, though just before release, you'll want to focus a bit more on
115 keeping the networkless handbook completely ready to go, as releng will need
116 tarballs of it to put on the LiveCDs in advance of the actual release date.
117 </li>
118 <li>
119 <uri link="/doc/en/handbook/handbook-x86.xml?part=2">Portage Handbook</uri>:
120 Doesn't change nearly as often as the Installation Handbook, but still needs
121 to be updated for new configuration files and names, such as
122 <path>/etc/make.conf</path> and <path>/etc/conf.d/</path> changes. The <uri
123 link="/doc/en/handbook/handbook-x86.xml?part=3">other Portage Handbook</uri>
124 is more in-depth. Check with the baselayout and Portage maintainers to make
125 sure the information is up-to-date.
126 </li>
127 <li>
128 <uri link="/doc/en/handbook/handbook-x86.xml?part=4">Network Handbook</uri>:
129 This will be updated about as often as the major networking configuration
130 sections of the Installation Handbook are updated, as some of the
131 information is similar. Again, check with the baselayout and Portage
132 maintainers to make sure the information is current.
133 </li>
134 </ol>
135
136 <note>
137 Not all the Portage/Networking handbook files will change, so it may be better
138 to just copy over only the ones you <e>know</e> will be changing when you start
139 updating them. Be sure of which files actually need to be changed. Again,
140 communication and coordination!
141 </note>
142
143 <p>
144 Variables and conditional includes are a lifesaver. Use them! Arch-specific
145 items that constantly change, such as ISO size, recommended CFLAGS, kernel
146 versions, etc. are kept in the handbook-$arch files, right at the top. Releng
147 will know about CD boot parameters, media/download size, and minimum system
148 requirements, as well as available media and their filenames. Arch teams will
149 know about CFLAGS and kernel names &amp; configuration, as well as suggested
150 partitioning schemes and specific tools to emerge/use.
151 </p>
152
153 <p>
154 Whenever possible, try to get arch team members to help you keep track of all
155 the changing information from release to release. See if they have a dedicated
156 liaison to assist with verifying documentation changes; it's even better if they
157 have someone who can submit GuideXML patches, so don't hesitate to ask! So be
158 sure to CC the arch teams on the handbook release tracker bug to keep them in
159 the loop.
160 </p>
161
162 <p>
163 Sometimes releases will offer enough changes that a new chapter or even a whole
164 new handbook has to be written, or may even be removed. As much as possible
165 while remaining <e>practical</e>, try not to duplicate information across
166 separate arch handbook files. Instead, see if you can combine them into a single
167 file through smart use of conditional includes. When these kinds of
168 additions/subtractions occur, you'll need to make the appropriate alterations to
169 the handbook-$arch files.
170 </p>
171
172 </body>
173 </section>
174 <section>
175 <title>Other documents</title>
176 <body>
177
178 <p>
179 Besides the handbooks, you will also need to simultaneously update the following
180 documents to keep them in line with the handbooks. Docs come and go but these
181 are currently the most critical files to keep track of.
182 </p>
183
184 <ul>
185 <li>
186 <b>Quick Install Guides</b>, including the ones for x86, Sparc, FreeBSD, and
187 any other arch for which we have a quick install guide in
188 <path>/doc/en/</path>. This includes any <uri
189 link="/doc/en/altinstall.xml">Alternative Installation Method</uri>-type
190 guides, <uri link="/doc/en/lvm2.xml">LVM2</uri> guides, <uri
191 link="doc/en/gentoo-x86-tipsntricks.xml">Installation Tips &amp;
192 Tricks</uri>, and the like.
193 </li>
194 <li>
195 <b>FAQs</b>, including the general <uri link="/doc/en/faq.xml">FAQ</uri> and
196 arch-specific FAQs, such as for AMD64, PPC, Sparc, etc. Also included here
197 are any arch-specific requirements or compatibility guides, such as for
198 MIPS. Anything for which support may change from release to release; you
199 will need to contact the various arch teams to find out.
200 </li>
201 <li>
202 <uri link="/doc/en/liveusb.xml">The LiveUSB HOWTO</uri>, for the folks that
203 want to use a USB key instead of installation CDs. Check to make sure that
204 boot parameters are still correct, as well as the process of creating the
205 media.
206 </li>
207 <li>
208 <b>Upgrade guides</b>, such as the <uri
209 link="/doc/en/gentoo-upgrading.xml">Gentoo Upgrading Guide</uri>, as this
210 doc contains profile upgrading information. Most releases include new
211 profiles and deprecate or remove old profiles. Also, any changes introduced
212 by baselayout between releases will have their upgrading information covered
213 here.
214 </li>
215 <li>
216 <uri link="/doc/en/kernel-config.xml">Kernel Configuration Guide</uri>. Keep
217 the available and recommended options in this file synchronized with what's
218 in the Installation Handbook.
219 </li>
220 <li>
221 <path>metadoc.xml</path>, which will contain updated links to the current
222 handbook files, both networked and networkless
223 </li>
224 </ul>
225
226 </body>
227 </section>
228 </chapter>
229
230 <chapter>
231 <title>Committing</title>
232 <section>
233 <title>General guidelines</title>
234 <body>
235
236 <p>
237 Remember, before you commit any change to a document, validate the file with
238 <c>xmllint --valid --noout</c>. Quality! Aim for technical and process
239 perfection. It <e>will</e> save you grief when it comes time for the actual
240 release.
241 </p>
242
243 <p>
244 Avoid mixing spelling, grammar, or GuideXML coding style fixes (non-content
245 changes) with procedural/informational fixes (content changes), otherwise
246 translators will get out their knives and come for you. You don't want that. Try
247 committing content fixes first, then the non-content fixes.
248 </p>
249
250 <p>
251 Don't bother bumping dates when you're working on your offline drafts. Save the
252 final date bump for the final "live" commit. However, you may want to make the
253 correct version bump ahead of the "live" commit, just to get it out of the way.
254 It's also a handy indication of whether or not you've remembered to touch the
255 file. When you're ready for the final commit, be sure to verify the version and
256 dates for each file. (Bring some caffeine; the process is tedious but
257 necessary.)
258 </p>
259
260 <p>
261 As much as possible, try to keep section text and layout (including order)
262 identical across the other arch handbooks, especially for shared content.
263 </p>
264
265 <p>
266 If you do include &lt;-- TODO comments --&gt; in the docs as notes to yourself,
267 be sure to remove them before committing the finished document; don't clutter
268 it up.
269 </p>
270
271 <p>
272 When you're ready for the "live" commit, don't forget to remove any draft
273 disclaimers from file links.
274 </p>
275
276 </body>
277 </section>
278 </chapter>
279
280 <chapter>
281 <title>Suggested Procedures</title>
282 <section>
283 <body>
284
285 <p>
286 The following procedures do not <e>have</e> to be done in the specified order,
287 but they are recommended. They will help you make efficient use of your time,
288 with as few errors as possible. This procedure order (or something close to it
289 ;)) has worked pretty well for the last few releases.
290 </p>
291
292 <impo>
293 The <e>very first</e> thing you should do is <e>open a handbook release tracker
294 bug</e>. CC the arch teams, releng, and anyone else essential to the process of
295 updating the handbooks; you'll need their help for the content, as well as the
296 help of your fellow GDP members to put it all together. Once that's done, you
297 can get down to the business of actually editing the documents. Keep the GDP and
298 other project members informed about your progress by posting status updates to
299 the bug and sending out email as necessary.
300 </impo>
301
302 </body>
303 </section>
304 <section>
305 <title>Editing drafts</title>
306 <body>
307
308 <p>
309 Start with the installation handbooks:
310 </p>
311
312 <ol>
313 <li>
314 Create the new networkless handbook directory; e.g.
315 <path>handbook/2007.1/</path>
316 </li>
317 <li>
318 Copy all current networkless handbook files into this new networkless
319 directory. It's okay that this is actually a "live" directory -- you just
320 won't be linking any of the files from index pages.
321 </li>
322 <li>
323 Copy the current networked handbook files into <path>handbook/draft/</path>
324 </li>
325 <li>
326 Commit these additions. Make it a straight copy with <b>no</b>
327 modifications! Otherwise, translators will hate you for making it hard to
328 follow your changes.
329 </li>
330 <li>
331 Edit the networkless handbook-$arch.xml pages, making sure they have the
332 draft disclaimer in their file link
333 </li>
334 <li>
335 Go through and renumber old release names/numbers to the upcoming one, e.g.
336 2007.0 --> 2007.1. Now is also a good time to make the major version mumber
337 bump for each page. Each new release gets a major &lt;version&gt; number
338 bump. Thus, 2007.0 references in <path>hb-install-kernel.xml</path> become
339 2007.1 and the file's &lt;version&gt; gets bumped from 7.4 to 8.0. If it's
340 4.3, it becomes 5.0, and so on.
341 </li>
342 <li>
343 Begin making content and non-content changes to the files, being careful not
344 to mix the two. Remember that most changes will apply to both networked and
345 networkless handbooks, but not all, so be careful when you're doubling up
346 your commits. Also, watch out for handbook changes that also need to be
347 propagated to non-handbook files, such as FAQs.
348 </li>
349 <li>
350 Make the necessary changes to non-handbook files, but try to keep those
351 changes offline, as explained below.
352 </li>
353 </ol>
354
355 <impo>
356 Be careful when working on files outside of <path>/handbook/</path>! If the
357 updated information you're adding to these documents won't hurt users <e>now</e>
358 and is not otherwise premature, go ahead and commit those changes to the live
359 documents. Otherwise, you should keep your changes offline, on your local
360 machine only. Also, be careful that you aren't altering the handbook files
361 inside the top-level <path>/handbook/</path> directory; make sure you're
362 committing your changes only to <path>/handbook/draft/</path> and
363 <path>/handbook/$new-release/</path>.
364 </impo>
365
366 </body>
367 </section>
368 <section>
369 <title>Preparing the on-disc networkless handbooks</title>
370 <body>
371
372 <p>
373 You'll need to have the networkless handbooks ready some days in advance of the
374 actual release date, as releng will be placing them into the disc ISOs ahead of
375 time. Obviously, you must keep the networkless handbooks as current and perfect
376 as possible; ideally with version bump, and even a date bump, just before it
377 comes time to roll them up into the tarball.
378 </p>
379
380 <p>
381 Unfortunately, the GDP no longer has a working script to convert handbooks into
382 the HTML version that goes on the disc. Instead, use the rendered HTML source
383 code online in <path>/handbook/$new-release/</path>. Download the all-in-one
384 <b>Printable</b> version of the required arch handbook's source code using your
385 favorite browser and save it as <path>handbook-&lt;arch&gt;.html</path>. The
386 following example uses the Sparc handbook.
387 </p>
388
389 <pre caption="Creating the on-disc handbook">
390 <comment>(Create the directory you'll be tarring up)</comment>
391 $ <i>mkdir -p handbook-sparc/handbook/html/css</i>
392 $ <i>cd handbook-sparc/handbook/html/</i>
393 <comment>(Move the HTML file here)</comment>
394 $ <i>mv ../../../handbook-sparc.html ./</i>
395 <comment>(Download Gentoo's CSS)</comment>
396 $ <i>wget http://www.gentoo.org/css/main.css -O css/main.css</i>
397 </pre>
398
399 <p>
400 Next you'll need to edit the HTML file with your favorite editor. Change the CSS
401 link in the document's head to <path>css/main.css</path> as shown:
402 </p>
403
404 <pre caption="Editing handbook-sparc.html">
405 &lt;link title="new" rel="stylesheet" href="<i>css/main.css</i>" type="text/css"&gt;
406 </pre>
407
408 <p>
409 Save your changes, then tar up the top-level <path>handbook-sparc</path>
410 directory you created. Save it as <path>handbook-sparc.tar.gz</path>, then pass
411 it on to releng. Repeat for each architecture that has a networkless
412 installation handbook.
413 </p>
414
415 </body>
416 </section>
417 <section>
418 <title>Committing, including the final release</title>
419 <body>
420
421 <ol>
422 <li>
423 Once you think you're ready for the release, go back through each of your
424 files and verify that the XML is valid and well-formed. <brite>Fix any
425 errors now</brite>, not when you go to make the final commit.
426 </li>
427 <li>Verify that the file version and date have been properly bumped</li>
428 <li>
429 Remove the draft disclaimers from the networkless handbook-$arch index
430 pages.
431 </li>
432 <li>Remove any &lt;-- TODO --&gt; comments or other notes to yourself.</li>
433 <li>
434 Make sure that you've tarred up the networkless handbooks and given them to
435 releng for the install CDs, as outlined previously.
436 </li>
437 <li>
438 Move the files from <path>handbook/draft/</path> into
439 <path>handbook/</path>, overwriting the old ones and removing outdated files
440 where necessary.
441 </li>
442 <li>Make sure <path>metadoc.xml</path> is correct</li>
443 <li>
444 Manually verify that each and every single file you touched is the way you
445 want it. (Got your caffeine handy?)
446 </li>
447 <li>
448 Make sure you haven't forgotten any patches or content from the handbook
449 release tracker bug.
450 </li>
451 <li>
452 Once you're satisfied that everything is ready, <c>cd</c> into the topmost
453 directory, usually <path>/doc/en/</path> and make an <e>atomic</e> commit;
454 that is, commit everything at once so it all goes "live" at the same time.
455 </li>
456 <li>
457 Communicate with your fellow developers: send announcements/status updates
458 to the tracker bug and to any required mailing lists
459 </li>
460 <li><e>Take a deep breath</e></li>
461 <li>
462 Go back and re-examine every single file you just committed. Have you been
463 watching gentoo-doc-cvs? ;) There's almost always something that was
464 overlooked; now is the time to make sure you aren't forgetting any content.
465 </li>
466 </ol>
467
468 <p>
469 Eventually, once the release is out the door and everything is more-or-less
470 straightened out, you can go ahead and close that tracker bug. Feels good,
471 doesn't it? Now you get to fix the user and developer bug reports as they come
472 in!
473 </p>
474
475 <p>
476 And then, before you know it, it'll be time to begin the release cycle <e>all
477 over again</e> . . . :)
478 </p>
479
480 </body>
481 </section>
482 </chapter>
483
484 <chapter>
485 <title>Pre-release Quick Checklist</title>
486 <section>
487 <body>
488
489 <p>
490 Here's an abbreviated version of most of the above, to be done immediately
491 before the final "live" commit:
492 </p>
493
494 <ul>
495 <li>
496 Networked handbook files in <path>handbook/draft/</path>. Check the
497 handbook-$arch pages. Fix inter/intra-document links, release version
498 numbers, and file/date revbumps.
499 </li>
500 <li>
501 The handbook <path>index.xml</path> pages; check the listed translations and
502 other info
503 </li>
504 <li>
505 Networkless handbook files in <path>handbook/$new-release/</path>. Same
506 checks as the networked files. Remove draft disclaimers.
507 </li>
508 <li>
509 Networking handbook check for <path>handbook/draft/</path>: current and
510 consistent
511 </li>
512 <li>
513 Portage handbook check for <path>handbook/draft/</path>: current and
514 consistent
515 </li>
516 <li>
517 Security handbook check for <path>/doc/en/security/</path>: this is
518 low-maintenance, but check anyway
519 </li>
520 <li>
521 Check <path>/doc/en/</path> for pending changes to these top-level files.
522 Includes quickinstalls, FAQs, upgrade guides, kernel guides, etc.
523 </li>
524 <li>
525 <path>metadoc.xml</path> check: verify the files that make up the new
526 release. Overwrite the old ones listed and revbump metadoc.
527 </li>
528 <li>
529 Validate every single file in <path>/doc/en/</path>,
530 <path>handbook/draft/</path>,and <path>handbook/$new-release/</path> with
531 <c>xmllint --valid --noout</c>. Yes, again. Fix errors.
532 </li>
533 <li>Check the handbook release tracker bug for any remaining tasks</li>
534 <li><c>cd</c> to <path>/doc/en/</path> and make your atomic commit.</li>
535 </ul>
536
537 </body>
538 </section>
539 </chapter>
540 </guide>
541
542
543
544 --
545 gentoo-doc-cvs@g.o mailing list