Get Gentoo!
gentoo.org sites
gentoo.org Wiki Bugs Forums Packages
Planet Archives Sources
Infra Status

Gentoo Archives: gentoo-commits

From: "Joshua Saddler (nightmorph)" <nightmorph@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/pr/gmn: gmn-howto.xml index.xml
Date: Tue, 09 Sep 2008 07:32:49
Message-Id: E1KcxiP-00061N-Du@stork.gentoo.org
1 nightmorph 08/09/09 07:32:45
2
3 Modified: index.xml
4 Added: gmn-howto.xml
5 Log:
6 added the GMN Howto, a document that details how to produce the GMN. also updated the index, including a much-needed link to the actual GMN archive.
7
8 Revision Changes Path
9 1.4 xml/htdocs/proj/en/pr/gmn/index.xml
10
11 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/pr/gmn/index.xml?rev=1.4&view=markup
12 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/pr/gmn/index.xml?rev=1.4&content-type=text/plain
13 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/pr/gmn/index.xml?r1=1.3&r2=1.4
14
15 Index: index.xml
16 ===================================================================
17 RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/pr/gmn/index.xml,v
18 retrieving revision 1.3
19 retrieving revision 1.4
20 diff -u -r1.3 -r1.4
21 --- index.xml 21 May 2008 01:21:17 -0000 1.3
22 +++ index.xml 9 Sep 2008 07:32:44 -0000 1.4
23 @@ -6,10 +6,10 @@
24 <project>
25 <name>gmn</name>
26 <longname>Gentoo Monthly Newsletter</longname>
27 -<date>2008-05-20</date>
28 +<date>2008-09-09</date>
29
30 <author title="Author">
31 - <mail link="anant@g.o">Anant Narayanan</mail>
32 + <mail link="anant"/>
33 </author>
34
35 <description>
36 @@ -39,4 +39,8 @@
37 <dev role="lead" description="Project Lead and Editor">anant</dev>
38 <dev role="member" description="Author and Editor">nightmorph</dev>
39
40 +<!-- Project Specific Pages/Documentation -->
41 +<resource link="gmn-howto.xml">Gentoo Monthly Newsletter Howto</resource>
42 +<resource link="/news/en/gmn/">Archived monthly newsletters</resource>
43 +
44 </project>
45
46
47
48 1.1 xml/htdocs/proj/en/pr/gmn/gmn-howto.xml
49
50 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/pr/gmn/gmn-howto.xml?rev=1.1&view=markup
51 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/pr/gmn/gmn-howto.xml?rev=1.1&content-type=text/plain
52
53 Index: gmn-howto.xml
54 ===================================================================
55 <?xml version="1.0" encoding="UTF-8"?>
56 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
57 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/pr/gmn/gmn-howto.xml,v 1.1 2008/09/09 07:32:44 nightmorph Exp $ -->
58
59 <guide>
60 <title>Gentoo Monthly Newsletter Howto</title>
61
62 <author title="Author">
63 <mail link="nightmorph"/>
64 </author>
65
66 <abstract>
67 This guide details the process for creating the Gentoo Monthly Newsletter.
68 </abstract>
69
70 <!-- The content of this document is licensed under the CC-BY-SA license -->
71 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
72 <license/>
73
74 <version>1</version>
75 <date>2008-09-09</date>
76
77 <chapter>
78 <title>Overview</title>
79 <section>
80 <body>
81
82 <p>
83 So, you want to be a GMN editor, eh? This guide will show you how to write a
84 Gentoo Monthly Newsletter from start to finish. It's more or less structured
85 like the newsletter itself.
86 </p>
87
88 <p>
89 It's very important to familiarize yourself with <uri
90 link="/doc/en/xml-guide.xml">GuideXML</uri>, the language the GMN's written in.
91 Pay careful attention to coding style; you want the code to be nice and easy to
92 read, both for yourself, and for your teammates. So take the time to read <uri
93 link="/news/en/gmn/">past issues</uri>, and especially view the source code! You
94 can view the source online by appending <path>?passthru=1</path> to the
95 <path>.xml</path> URL of any newsletter. Or just open up a copy from your local
96 CVS checkout in your editor of choice.
97 </p>
98
99 </body>
100 </section>
101 <section>
102 <title>Files</title>
103 <body>
104
105 <p>
106 Putting together a newsletter requires several scripts and files. These can be
107 found in our <uri
108 link="http://sources.gentoo.org/viewcvs.py/gentoo/src/gwn/">code
109 repository</uri>. Be sure to save the following files to your GMN working
110 directory:
111 </p>
112
113 <ul>
114 <li><c>gmn_bugzie.py</c></li>
115 <li><c>gmn_bugzie_aggregate.py</c></li>
116 <li><c>get_packages_url.py</c></li>
117 <li><c>print-dev-stats.py</c></li>
118 <li><c>gmn2text.xsl</c></li>
119 <li><c>pygooglechart.py</c></li>
120 </ul>
121
122 <p>
123 There's also a <uri link="skel-newsletter.xml">skeleton newsletter</uri>
124 available. This template will let you get a quick start on each monthly
125 newsletter. Adjust the dates, times, locations, links, and numbers for each new
126 edition. It's pretty straightforward.
127 </p>
128
129 </body>
130 </section>
131 </chapter>
132
133 <chapter>
134 <title>Articles</title>
135 <section>
136 <body>
137
138 <p>
139 Feature articles are arguably the heart of the newsletter. However, articles
140 don't usually just fall from the sky: you may have to actively scour the
141 internet looking for articles, news releases, blogs, etc. pertaining to Gentoo.
142 However, rather than do all this work yourself, you can make better use of your
143 time by actively soliciting help from the user community and your fellow
144 developers. Get <e>them</e> to send in articles and links of interest. The more
145 they write up ahead of time, the better, as you'll need to do less editing. When
146 someone sends interesting material your way, be sure to give them an author or
147 contributor credit in the GMN. Participation should be fun <e>and</e> rewarding.
148 </p>
149
150 </body>
151 </section>
152 <section>
153 <title>Gentoo news</title>
154 <body>
155
156 <p>
157 Lead off the GMN (after the usual introduction) with general distribution news.
158 The GMN is the first place people look for things like Gentoo release
159 announcements, <uri link="/proj/en/council">Council</uri> and <uri
160 link="/foundation/en/">Trustees</uri> meetings, and other important news.
161 Oftentimes critical systemwide changes or security notes may be found here, such
162 as the mask &amp; removal of PHP4, stabilization of the latest Portage version,
163 baselayout changes, and similar. Or mention projects that Gentoo is
164 participating in, such as Google Summer of Code; see the <uri
165 link="/news/en/gmn/20080424-newsletter.xml">April 2008</uri> newsletter for a
166 nice example.
167 </p>
168
169 <p>
170 The Council and Trustees post meeting summaries, minutes, and agenda both to the
171 mailing lists and to their individual project pages. Use the summaries (with
172 links to the full documents) here; this way you don't waste time duplicating
173 their efforts. Occasionally there will be an important project meeting for
174 security, desktop, Portage, etc. Make sure to include such meeting notes.
175 Pester the project secretaries/leads for minutes and summaries if you have to.
176 Remember, you don't have much time to play investigative journalist. Try to get
177 the other projects to cooperate with you. Publicity should good for them, after
178 all.
179 </p>
180
181 <p>
182 Next: the mini-calendar with the next month or three's events. Upcoming events
183 might include monthly <uri link="/proj/en/bugday/">bugdays</uri>, Gentoo IRC
184 meetings, and Linux/FOSS trade shows.
185 </p>
186
187 </body>
188 </section>
189 <section>
190 <title>Gentoo international</title>
191 <body>
192
193 <p>
194 The Gentoo International chapter reports the
195 happenings at events around the world in which Gentoo and its developers have a
196 presence. Pictures are always good!
197 </p>
198
199 <p>
200 In the past, the GMN has extensively covered events such as FOSDEM, SCALE,
201 FliSol, LinuxTag, and various development summits in which Gentoo has a
202 presence.
203 </p>
204
205 <p>
206 There won't always be a Gentoo International chapter to include, as events
207 happen just a few times a year. But when they do, make sure to cover them! Talk
208 to the developers and teams who went; check their blogs, etc.
209 </p>
210
211 </body>
212 </section>
213 <section>
214 <title>Community news</title>
215 <body>
216
217 <p>
218 The community news chapter can consist of:
219 </p>
220
221 <ul>
222 <li>
223 Interviews with individuals, companies, and other folks who use Gentoo for
224 work, play, school, etc. This is one of the best ways to highlighting the
225 things Gentoo is capable of, and how it's being used. Google Summer of Code
226 interviews are another favorite for this chapter.
227 </li>
228 <li>
229 Articles focusing on a particular bit of community-produced Gentoo-related
230 software, like <uri link="http://www.haskell.org/himerge/">Himerge</uri>.
231 Interest pieces on things that affect the community of developers and users
232 alike, such as <uri link="http://overlays.gentoo.org">Sunrise</uri> or
233 Bugzilla, may be found here. However, the GMN doesn't really cover things
234 like individual non-Gentoo-specific applications, or applications that are
235 not in the tree. "Community news" shouldn't be a general advertising space.
236 </li>
237 <li>
238 <uri link="http://planet.gentoo.org">Planet Gentoo</uri>, an aggregator of
239 Gentoo developer blogs. Pick the best of the Gentoo-related posts from the
240 past month and include one or two sentence summaries.
241 </li>
242 <li>
243 "Gentoo in the News" is a good place to share sightings of Gentoo. Reviews,
244 enterprise Gentoo usage, magazine appearances, new distributions based on
245 Gentoo, and other Gentoo links &amp; references go here. The more the
246 merrier, even if they're just short tidbits.
247 </li>
248 </ul>
249
250 </body>
251 </section>
252 <section>
253 <title>Tips and tricks</title>
254 <body>
255
256 <p>
257 This chapter contains useful information for administering your system, keeping
258 things up-to-date, tweaking applications, monitoring boxes, and so on. If you're
259 lucky, you can get users and other developers to email some collected tips or
260 "best practices" each month. You may want to cull the forums for useful
261 material.
262 </p>
263
264 </body>
265 </section>
266 </chapter>
267
268 <chapter>
269 <title>Statistics collection</title>
270 <section>
271 <body>
272
273 <p>
274 The first half of the newsletter features articles, and those vary quite a bit
275 month-to-month. The second half contains general statistics on Bugzilla,
276 the Portage tree, developer changes, and so on. It's very formulaic,
277 straightforward, but also can be the most time consuming part of the newsletter
278 to write. This is where you'll use all the scripts we have to round out the GMN.
279 </p>
280
281 <p>
282 The statistical chapters are assembled as follows:
283 </p>
284
285 </body>
286 </section>
287 <section>
288 <title>Bugzilla statistics</title>
289 <body>
290
291 <p>
292 To generate the nice table of <uri link="http://bugs.gentoo.org">Bugzilla</uri>
293 statistics (new bugs, closed bugs, distribution, etc.), do the following:
294 </p>
295
296 <pre caption="Generating Bugzilla statistics">
297 $ <i>touch breport</i>
298 $ <i>python gmn_bugzie.py > breport</i>
299 $ <i>python gmn_bugzie_aggregate.py > gmn-bugzilla.txt</i> <comment>(For safekeeping)</comment>
300 </pre>
301
302 <p>
303 The first script, <c>gmn_bugzie.py</c>, generates a statistics file called
304 <path>breport</path> after querying Bugzilla.
305 </p>
306
307 <p>
308 The second script, <c>gmn_bugzie_aggregate.py</c>, creates and fills in the
309 statistics table that you copy into the GMN. It also generates three graphs:
310 <path>activity.png</path>, <path>opened.png</path>, and <path>closed.png</path>.
311 These three files come courtesy <uri
312 link="http://code.google.com/apis/chart/">Google Chart</uri> (via
313 <c>pygooglechart.py</c>). Save the graphs to your working directory; you'll be
314 adding them to CVS later on.
315 </p>
316
317 <p>
318 Once you've got your statistics output saved to <path>gmn-bugzilla.txt</path>
319 (or whatever you named it), you can paste it into the appropriate GMN section.
320 Make sure to properly link in the generated graphs. Take a look at the code for
321 the <uri link="/news/en/gmn">past issues</uri> to see how it goes.
322 </p>
323
324 </body>
325 </section>
326 <section>
327 <title>Portage statistics</title>
328 <body>
329
330 <p>
331 To create the Portage statistics (number of packages by keyword, distribution,
332 etc.), you'll need an unmodified Portage installation. This means you shouldn't
333 be using PORTDIR_OVERLAY or anything else that affects the number of categories
334 and packages reported. Also, you'll have to use the downloaded metadata cache
335 obtained from syncing, so you can't set various fun things like
336 <c>portdbapi.auxdbmodule = cache.metadata_overlay.database</c> in
337 <path>/etc/portage/modules</path>.
338 </p>
339
340 <p>
341 First, you'll need to <c>emerge portage-utils</c>, and run one of its utilities
342 as shown.
343 </p>
344
345 <pre caption="Obtaining Portage statistics">
346 $ <i>qcache -s</i>
347 </pre>
348
349 <p>
350 Save the output to a file, as you'll need it in just a bit. Before you can
351 create the Portage statistics graph, you'll need to manually edit
352 <c>get_packages_url.py</c>. Fill in the values in the arrays declared on the
353 first two lines to correspond with the values generated by <c>qcache -s</c>.
354 Yes, it's a pain to manually edit the script every time you want to use it, but
355 it'll do for now. (If you have a better way, be sure to email us!)
356 </p>
357
358 <p>
359 Once you've edited the script, run it:
360 </p>
361
362 <pre caption="Creating the Portage graph">
363 $ <i>python get_packages_url.py</i>
364 </pre>
365
366 <p>
367 This script creates the URL to a Google chart. Download the chart and save it to
368 your working directory as <path>keywords.png</path>. You'll be committing this file
369 with the rest of the charts soon. Again, make sure to add the proper link to
370 this file within the GMN.
371 </p>
372
373 </body>
374 </section>
375 <section>
376 <title>Developer statistics</title>
377 <body>
378
379 <p>
380 You can get the developer statistics (total recruited, away, etc.) by first
381 downloading the devaway XML file, and then by hand-editing the
382 <c>print-dev-stats.py</c> script to point at your own CVS checkout directory.
383 </p>
384
385 <pre caption="Obtaining developer statistics">
386 $ <i>wget http://www.gentoo.org/dyn/devaway/devaway.xml?passthru=1 -O devaway.xml</i>
387 $ <i>python print-dev-stats.py</i>
388 </pre>
389
390 <p>
391 Once you've done this, paste the numbers into the developers summary section
392 (number recruited, active, and away).
393 </p>
394
395 <p>
396 For developer changes (joining/leaving projects or teams), run a diff of the
397 changes to <path>herds.xml</path> since the last issue. This information is
398 available <uri
399 link="http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml">in
400 CVS</uri>.
401 </p>
402
403 <p>
404 You should also keep a close eye on new developer emails sent to the
405 gentoo-dev-announce and/or gentoo-dev mailing lists. You should receive
406 automated retirement notices generated by Infra sent directly to the GMN email
407 alias.
408 </p>
409
410 </body>
411 </section>
412 </chapter>
413
414 <chapter>
415 <title>Finishing up</title>
416 <section>
417 <body>
418
419 <p>
420 As a courtesy to your fellow Gentoo developers, solicit feedback on the latest
421 issue by writing to the gentoo-core mailing list at least one day in advance of
422 publication. Be sure to provide them with a working URL to the issue; your
423 devspace on dev.gentoo.org is good enough, as dev.gentoo.org automatically
424 renders GuideXML into HTML.
425 </p>
426
427 </body>
428 </section>
429 <section>
430 <title>Final touches</title>
431 <body>
432
433 <p>
434 Once you've applied the final fixes from gentoo-core, you'll need to add a few
435 more bits to the issue <e>immediately</e> before committing. Time is important
436 here, as the webnodes take awhile to update.
437 </p>
438
439 <p>
440 First, make sure the dates inside the GMN issue are set to the correct date of
441 publication. You'll also need to adjust the submission deadline date for the
442 next issue; this information is found at the very end of the newsletter. You
443 should also verify that the volume and issue numbers are correct; these are
444 scattered through the first part of the GMN.
445 </p>
446
447 <p>
448 Next, post an announcement topic to the <uri
449 link="http://forums.gentoo.org">Gentoo Forums</uri>. Let the users know a new
450 issue has been published; be sure to include a link (even though the newsletter
451 isn't there <e>yet</e>. This forum thread is a convenient way for users to
452 discuss the issue and provide feedback. Refer to the announcements for the <uri
453 link="http://forums.gentoo.org/viewtopic-t-706123.html">August 2008</uri> and
454 <uri link="http://forums.gentoo.org/viewtopic-t-701922.html">July 2008</uri>
455 issues to see how it's done.
456 </p>
457
458 <p>
459 <e>As soon as you post the announcement</e>, add the link to the discussion
460 thread to the issue. The forum link appears at the very beginning and very end
461 of the issue, so make sure you fix both places.
462 </p>
463
464 <p>
465 Next, run <c>gmn2txt.xsl</c>. This script will create a plain-text version of
466 the newsletter suitable for emailing to the GMN subscribers. See the usage notes
467 inside the script itself if you need help.
468 </p>
469
470 </body>
471 </section>
472 <section>
473 <title>Committing</title>
474 <body>
475
476 <p>
477 Now go into your CVS checkout. You'll be committing several things all at once,
478 so stay sharp. <b>First</b>, update the GMN index page at
479 <path>gentoo/xml/htdocs/news/en/gmn/</path> with a link to the latest issue.
480 </p>
481
482 <p>
483 <b>Second</b>, write up the front page announcement for www.gentoo.org and add
484 it to <path>gentoo/xml/htdocs/news/</path>. See the <uri
485 link="/news/20080831-gmn.xml">August 2008 news item</uri> for how it's done. Add
486 it to CVS (<c>cvs add</c>).
487 </p>
488
489 <p>
490 <b>Third</b>, <c>cvs add</c> the completed issue itself to
491 <path>gentoo/xml/htdocs/news/en/gmn/</path>, and the images (including all those
492 graphs you generated) to <path>gentoo/xml/images/&lt;issue-date&gt;/</path>.
493 </p>
494
495 <p>
496 <b>Finally</b>, <c>cvs commit</c> the whole thing in one go. Back up to
497 <path>gentoo/xml/</path> and make an atomic commit from this top-level
498 directory. This ensures that the front-page announcement, issue + accompanying
499 images, and the GMN index all get updated at the same time. Hopefully not too
500 much time has passed between creating the forum announcement and actually
501 releasing the GMN.
502 </p>
503
504 <p>
505 Now that the online edition of the GMN is published, you can send out the
506 plain-text email version. Log in to dev.gentoo.org and upload the text version
507 of the GMN so you can email it. Once logged in, run:
508 </p>
509
510 <pre caption="Sending out the email newsletter">
511 $ <i>mutt -s "Gentoo Monthly Newsletter: XX XXXX 200X" -i 200XXXXX-newsletter.txt gentoo-gmn@g.o</i>
512 <comment>(For example: "31 August 2008" and "20080831-newsletter.txt")</comment>
513 </pre>
514
515 <p>
516 Confirm the address, subject, and content. Press <c>Ctrl-T</c> to change the
517 charset of the content to <c>utf-8</c>. This is important, because by default
518 the charset is <c>unknown-8bit</c>. Press <c>y</c> to send the newsletter. A
519 moderator of the list will confirm and the message will be sent.
520 </p>
521
522 <p>
523 There . . . the front page and forum announcements are in place, the newsletter
524 is online, the email edition is sent . . . now you can take a break! At least
525 until the emails for the next issue arrive. And it all starts over again . . .
526 </p>
527
528 </body>
529 </section>
530 </chapter>
531
532 <chapter>
533 <title>Resources</title>
534 <section>
535 <body>
536
537 <ul>
538 <li>
539 <uri link="skel-newsletter.xml">GMN skeleton newsletter</uri>: use this
540 template for each monthly issue. You'll find that pretty much all possible
541 sections have been added; if you don't have a certain section, just delete
542 it. Be sure to fill in appropriate dates, issue numbers, and links where
543 marked.
544 </li>
545 <li><uri link="/proj/en/pr/gmn/">GMN project page</uri></li>
546 <li><uri link="/news/en/gmn">Index of GMN issues</uri></li>
547 <li><uri link="/doc/en/xml-guide.xml">GuideXML Guide</uri></li>
548 <li>
549 <uri link="http://forums.gentoo.org">Gentoo Forums</uri>: the Gentoo Chat
550 subforum contains discussion and feedback threads for the GMN; you may want
551 to search the archives.
552 </li>
553 </ul>
554
555 </body>
556 </section>
557 </chapter>
558 </guide>
Report Message
Find on MARC Find on Google Groups