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 & 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 & |
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 <-- TODO comments --> 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 <version> number |
338 |
bump. Thus, 2007.0 references in <path>hb-install-kernel.xml</path> become |
339 |
2007.1 and the file's <version> 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-<arch>.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 |
<link title="new" rel="stylesheet" href="<i>css/main.css</i>" type="text/css"> |
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 <-- TODO --> 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 |