News project/Guide

This guide details the process for creating the Gentoo Monthly Newsletter.

Overview
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 to the  URL of any newsletter. Or just open up a copy from your local CVS checkout in your editor of choice.

Files
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 directory:



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.

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

Gentoo news
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 nice example.

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

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.

Gentoo international
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 presence.

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.

Community news
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 material.

Statistics collection
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:

Bugzilla statistics
To generate the nice table of Bugzilla statistics (new bugs, closed bugs, distribution, etc.), do the following:

Generating Bugzilla statistics

The first script, , generates a statistics file called  after querying Bugzilla.

The second script, , creates and fills in the statistics table that you copy into the GMN. It also generates three graphs:,  , and. These three files come courtesy Google Chart (via  ). 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 (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.

Portage statistics
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  in.

First, you'll need to , and run one of its utilities as shown.

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. 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  on them:

Generating package adds/removes

In this example, the output of the command is saved to a file, rather than printed straight to the terminal. will create the GuideXML; all you have to do is paste it into the newsletter.

Developer statistics
You can get the developer statistics (total recruited, away, etc.) by first downloading the devaway XML file, and then by hand-editing the  script to point at your own CVS checkout directory.

Obtaining developer statistics

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 since the last issue. This information is available in CVS. It's also advisable to check the project pages as well. For projects that have been moved to Gentoo Wiki, use this link to get the list of people who joined a project, and this link for people who left one.

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

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

Final touches
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.

Committing
Write up the front page announcement for www.gentoo.org and add it to. See the August 2008 news item for how it's done. Add it to CVS.

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

Resources

 * 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 marked.
 * 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.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * nightmorph
 * hwoarang