Gentoo Monthly Newsletter Howto
So, you want to be a GMN editor, eh? This guide will show you how to write a
Gentoo Monthly Newsletter from start to finish. It's more or less structured
like the newsletter itself.
It's very important to familiarize yourself with GuideXML, the language the GMN's written in.
Pay careful attention to coding style; you want the code to be nice and easy to
read, both for yourself, and for your teammates. So take the time to read past issues, and especially view the source code! You
can view the source online by appending ?passthru=1 to the
.xml URL of any newsletter. Or just open up a copy from your local
CVS checkout in your editor of choice.
Putting together a newsletter requires several scripts and files. These can be
found in our code
repository. Be sure to save the following files to your GMN working
There's also a skeleton newsletter
available. This template will let you get a quick start on each monthly
newsletter. Adjust the dates, times, locations, links, and numbers for each new
edition. It's pretty straightforward.
Feature articles are arguably the heart of the newsletter. However, articles
don't usually just fall from the sky: you may have to actively scour the
internet looking for articles, news releases, blogs, etc. pertaining to Gentoo.
However, rather than do all this work yourself, you can make better use of your
time by actively soliciting help from the user community and your fellow
developers. Get them to send in articles and links of interest. The more
they write up ahead of time, the better, as you'll need to do less editing. When
someone sends interesting material your way, be sure to give them an author or
contributor credit in the GMN. Participation should be fun and rewarding.
Lead off the GMN (after the usual introduction) with general distribution news.
The GMN is the first place people look for things like Gentoo release
announcements, Council and Trustees meetings, and other important news.
Oftentimes critical systemwide changes or security notes may be found here, such
as the mask & removal of PHP4, stabilization of the latest Portage version,
baselayout changes, and similar. Or mention projects that Gentoo is
participating in, such as Google Summer of Code; see the April 2008 newsletter for a
The Council and Trustees post meeting summaries, minutes, and agenda both to the
mailing lists and to their individual project pages. Use the summaries (with
links to the full documents) here; this way you don't waste time duplicating
their efforts. Occasionally there will be an important project meeting for
security, desktop, Portage, etc. Make sure to include such meeting notes.
Pester the project secretaries/leads for minutes and summaries if you have to.
Remember, you don't have much time to play investigative journalist. Try to get
the other projects to cooperate with you. Publicity should good for them, after
Next: the mini-calendar with the next month or three's events. Upcoming events
might include monthly bugdays, Gentoo IRC
meetings, and Linux/FOSS trade shows.
The Gentoo International chapter reports the
happenings at events around the world in which Gentoo and its developers have a
presence. Pictures are always good!
In the past, the GMN has extensively covered events such as FOSDEM, SCALE,
FliSol, LinuxTag, and various development summits in which Gentoo has a
There won't always be a Gentoo International chapter to include, as events
happen just a few times a year. But when they do, make sure to cover them! Talk
to the developers and teams who went; check their blogs, etc.
The community news chapter can consist of:
Interviews with individuals, companies, and other folks who use Gentoo for
work, play, school, etc. This is one of the best ways to highlighting the
things Gentoo is capable of, and how it's being used. Google Summer of Code
interviews are another favorite for this chapter.
Articles focusing on a particular bit of community-produced Gentoo-related
software, like Himerge.
Interest pieces on things that affect the community of developers and users
alike, such as Sunrise or
Bugzilla, may be found here. However, the GMN doesn't really cover things
like individual non-Gentoo-specific applications, or applications that are
not in the tree. "Community news" shouldn't be a general advertising space.
Planet Gentoo, an aggregator of
Gentoo developer blogs. Pick the best of the Gentoo-related posts from the
past month and include one or two sentence summaries.
"Gentoo in the News" is a good place to share sightings of Gentoo. Reviews,
enterprise Gentoo usage, magazine appearances, new distributions based on
Gentoo, and other Gentoo links & references go here. The more the
merrier, even if they're just short tidbits.
Tips and tricks
This chapter contains useful information for administering your system, keeping
things up-to-date, tweaking applications, monitoring boxes, and so on. If you're
lucky, you can get users and other developers to email some collected tips or
"best practices" each month. You may want to cull the forums for useful
The first half of the newsletter features articles, and those vary quite a bit
month-to-month. The second half contains general statistics on Bugzilla,
the Portage tree, developer changes, and so on. It's very formulaic,
straightforward, but also can be the most time consuming part of the newsletter
to write. This is where you'll use all the scripts we have to round out the GMN.
The statistical chapters are assembled as follows:
To generate the nice table of Bugzilla
statistics (new bugs, closed bugs, distribution, etc.), do the following:
Code Listing 3.1: Generating Bugzilla statistics
$ touch breport
$ python gmn_bugzie.py > breport
$ python gmn_bugzie_aggregate.py > gmn-bugzilla.txt
The first script, gmn_bugzie.py, generates a statistics file called
breport after querying Bugzilla.
The second script, gmn_bugzie_aggregate.py, creates and fills in the
statistics table that you copy into the GMN. It also generates three graphs:
activity.png, opened.png, and closed.png.
These three files come courtesy Google Chart (via
pygooglechart.py). Save the graphs to your working directory; you'll be
adding them to CVS later on.
Once you've got your statistics output saved to gmn-bugzilla.txt
(or whatever you named it), you can paste it into the appropriate GMN section.
Make sure to properly link in the generated graphs. Take a look at the code for
the past issues to see how it goes.
To create the Portage statistics (number of packages by keyword, distribution,
etc.), you'll need an unmodified Portage installation. This means you shouldn't
be using PORTDIR_OVERLAY or anything else that affects the number of categories
and packages reported. Also, you'll have to use the downloaded metadata cache
obtained from syncing, so you can't set various fun things like
portdbapi.auxdbmodule = cache.metadata_overlay.database in
First, you'll need to emerge portage-utils, and run one of its utilities
Code Listing 3.2: Obtaining Portage statistics
This script creates the table suitable for direct inclusion in the GMN post
and a URL to a Google chart. Download the chart and save it to
your working directory as keywords.png. You'll be committing this file
with the rest of the charts soon. Again, make sure to add the proper link to
this file within the GMN.
The package adds/removes are generated by saving the logs emailed by
infrastructure, and running gwn_adds_removes.py on them:
Code Listing 3.3: Generating package adds/removes
$ python gwn_adds_removes.py add-removals.1220227200.log > foo.txt
In this example, the output of the command is saved to a file, rather than
printed straight to the terminal. gwn_adds_removes.py will create the
GuideXML; all you have to do is paste it into the newsletter.
You can get the developer statistics (total recruited, away, etc.) by first
downloading the devaway XML file, and then by hand-editing the
print-dev-stats.py script to point at your own CVS checkout directory.
Code Listing 3.4: Obtaining developer statistics
$ python print-dev-stats.py
Once you've done this, paste the numbers into the developers summary section
(number recruited, active, and away).
For developer changes (joining/leaving projects or teams), run a diff of the
changes to herds.xml since the last issue. This information is
You should also keep a close eye on new developer emails sent to the
gentoo-dev-announce and/or gentoo-dev mailing lists. You should receive
automated retirement notices generated by Infra sent directly to the GMN email
As a courtesy to your fellow Gentoo developers, solicit feedback on the latest
issue by writing to the gentoo-core mailing list at least one day in advance of
publication. Be sure to provide them with a working URL to the issue.
Once you've applied the final fixes from gentoo-core, you'll need to add a few
more bits to the issue immediately before committing. Time is important
here, as the webnodes take awhile to update.
Finally, make sure the dates inside the GMN issue are set to the correct date of
publication. You'll also need to adjust the submission deadline date for the
next issue; this information is found at the very end of the newsletter. You
should also verify that the volume and issue numbers are correct; these are
scattered through the first part of the GMN.
Write up the front page announcement for www.gentoo.org and add
it to gentoo/xml/htdocs/news/. See the August 2008 news item for how it's done. Add
it to CVS (cvs add).
Now that the online edition of the GMN is published, you can send out the
plain-text email version. Log in to dev.gentoo.org and upload the text version
of the GMN so you can email it. Once logged in, run:
There . . . the front page and forum announcements are in place, the newsletter
is online, the email edition is sent . . . now you can take a break! At least
until the emails for the next issue arrive. And it all starts over again . . .
GMN skeleton newsletter: use this
template for each monthly issue. You'll find that pretty much all possible
sections have been added; if you don't have a certain section, just delete
it. Be sure to fill in appropriate dates, issue numbers, and links where
- GMN project page
- Index of GMN issues
- GuideXML Guide
Gentoo Forums: the Gentoo Chat
subforum contains discussion and feedback threads for the GMN; you may want
to search the archives.
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.