How to be a release notes beat writer

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Publican)
(Publican)
Line 69: Line 69:
  
 
{{Admon/note | Need to find citation.| This might be in the mailing list archives.}}
 
{{Admon/note | Need to find citation.| This might be in the mailing list archives.}}
 +
 +
{{Admon/note | Having a hard time locating the note | Found this but don't find the original
 +
https://www.redhat.com/archives/fedora-docs-list/2008-October/msg00136.html }}
  
 
=== DocBook ===
 
=== DocBook ===

Revision as of 12:38, 15 December 2008


There is plenty of information on the wiki about how to become a beat writer. We need people who will pick up a piece that interests them and help tell the world. What is lacking is help in how to execute the duties of a beat writer. This page hopes to address that. Please take care to note that these are the opinions of one beat writer, and perhaps something of an outlier at that.

Contents

The Process

During the release cycle, there are things that need to be done to stay on top of the release. Most of these, honestly, are pretty lightweight. They may seem a bit daunting at first, but really, they're not too bad. The hardest part, though, is understanding what is expected; this page hopes to address that.

Finding out what a Beat looks like

The beat page in the wiki ultimately becomes a section of the release notes for the next release of Fedora. It's primary objective is to help people understand what has changed. Depending on the beat, it might be helpful to begin with a 'short' synopsis of what is in the beat, but the main thrust should be to describe the changes between the next release and the previous.

Just how detailed this should be depends on the particular topic. For many packages a simple note mentioning a new version of a particular package, perhaps with a short description of new features is adequate. For a completely new package, you may want to be a little more detailed. Most packages come from an upstream project, so in general you want to include a link to the upstream's release notes.

Sometimes a package has changed in a way that requires action from a user. Perhaps the user must install an external package, perhaps (s)he must do some sort of file conversion. When this happens, the beat must include at least a warning, and a link to the details. In cases where there are probably many users, and especially when those users might be less experienced, then a detailed, step-by-step description of what needs to be done is in order.

Read through the current version of the release notes. You will see examples of both very brief descriptions and very detailed descriptions. As you read through the release notes, keep in mind that the audience for, say, gcc is a very different audience than that for the Flash plugin, for example, even though they end up in the same document.

Finding out what is in the Beat

This sounds simple, but is probably the hardest part. You took on (or are thinking of taking on) the Beat Writer duties because there is a subject within Fedora that you care about, and maybe are even familiar with. You probably already use some of the packages in your particular beat. The operative word there is some. Fedora now has well over 11,000 packages. Chances are there are packages in your area you don't know about. The good news is that you are likely to find packages you wish you knew about sooner!

PackageKit is one obvious place to start. PackageKit is not organized by Beats. As a result, not all packages are in obvious places in PackageKit, and many packages "belong" in multiple groups. But at least PackageKit is a start. The GUI for PackageKit wasn't really aimed at Beat Writers, so this process can be a little tedious.

When you are looking around in PackageKit, at least scan groups that don't seem to be related to your beat. The people who organized the groups in PackageKit had a different point of view. Even when a package at first seems way out of bounds for a particular group, usually if you give it a little thought, you can see the rationale, even though you may not agree with it.

A somewhat faster, but less friendly, way of searching the groups is to issue a yum grouplist command, find some groups that look relevant, and then do a yum groupinfo (groupname) to see a list of packages in the group. For packages that you aren't familiar with, you may still need to do a yum info on the package. With PackageKit you can simply select the package name to see the same description.

If your particular area of interest is supported by a SIG, then the SIG's page on the wiki is probably the best place to look. The SIG page not only has the current packages, but often has news of planned packages. Unfortunately, not all beats are supported by SIGs.

Finding out what has changed

The largest part of the job is keeping track of what has changed so that you can report on it for the release notes. The "company line" as it were is to stay in contact with developers and watch commits. Well, there are a couple of problems with that. If you can hook up with a developer that is obviously the optimum. Often, though, it isn't obvious who the developer is, and developers often have little interest in documentation, and even when they do, a developer's view of the world is quite a bit different than a user. The developer will often tend to be really excited about some change that is invisible to the end user, while ignoring significant new features. Still, maintaining a dialog with the developer is definitely the best approach.

Watching commits isn't a bad plan in theory, there is even an RSS feed. The problem is that with 11,000+ packages, there are a lot of commits. It isn't always all that easy to pick out the commits that you care about from the dozens or hundreds every day.

Probably the almost perfect situation again is if your beat has a SIG. The SIG page will probably link to a table listing packages and work being done on them. This is an ideal way to keep up with what is happening in your beat. The problem of course is the same as for identifying the packages in the first place; only a few beats have corresponding SIGs.

Probably the easiest, if a little tedious, is to look at the repositories. If you have a list of packages in your beat, you can make note of the versions for the previous release. Then from time to time you can look at the rawhide repositories for each of your packages and see what the current rawhide version is.

A variant on looking through the repository is to look in the yum database. Each repository has a primary.sqlite file that lists all the files in the repo and their versions. This is a SQL database and the sqlite3 program provides a text interface to the database. If you are comfortable with SQL, this is a much quicker approach than going through the rather long web page that describes the repository. There is a hack (tar here ) that attempts to make that a little easier.

Dale Bewley has a script for examining the koji files to see changes. He describes it here .

Once you know what package has changed, you now need to find out what has changed. Again, if your beat has a SIG or you are in contact with the developer, this is already pretty obvious to you. But if you are operating a little more at arms length it is a little less obvious. Again, the yum database comes to the rescue. If you issue the command yum info (packagename), yum will cough up a short description of the package, along with the URL of the package's project. Almost always that URL will lead you to the release notes for the upstream package.

Sometimes the upstream has weak or no release notes. Some insight into what has been done can be gleaned by looking at the change log in the RPM. If you have downloaded a copy of the RPM or have the package installed you can issue a rpm -q --changelog command and see the list of commits. The comments will give you a view into what has been happening with the package.

Depending on your capabilities and the resources available to you, it might be appropriate to install the rawhide package and explore it so you can write authoritatively.

Tools

The wiki

The primary method for providing release notes content is this wiki. The wiki is relatively easy to use, and since MediaWiki is a widely used wiki, it is well documented. There are a few Fedora unique styles and templates, these are described in the editing help page.

The main benefit of the wiki is that it allows so many people to contribute. You aren't likely to be familiar with all the packages in your beat, but those people who are likely to read your wiki page are exactly those people who are likely to be familiar with the packages. This allows you to pick up on a lot of details of some of the packages that may otherwise elude you.

Publican

The release notes are produced by a package called Publican, and you must have the latest version of Publican installed if you want to build the release notes. The good news is that there isn't a lot about Publican that you need to know. Publican basically creates an empty DocBook document. By the time you, as a beat writer, need to work with that tool, the Publican part is done.

Basically, Publican is a big, lumbering package and the release notes are produced in a zillion languages (well, OK, I count only 40). This means that should you inadvertently try to build all the languages, it will take a very long time. Once you have the release notes cloned from git, you can make just the U.S. English version by:

 make html-en_US

The process of cloning the common tools and release notes from the git repository is described elsewhere.

Note.png
Need to find citation.
This might be in the mailing list archives.
Note.png
Having a hard time locating the note
Found this but don't find the original https://www.redhat.com/archives/fedora-docs-list/2008-October/msg00136.html

DocBook

As the time for release closes in, you may need to make last-minute changes in DocBook. You may also find that updates will need to be made in DocBook from time to time. Fortunately, like Publican, you really don't need to know a lot about DocBook to use it.

The source for the release notes is consists of a number (roughly a couple dozen) XML files. These files can be edited with a normal text editor, although it may be a little easier to use an editor that understands XML like emacs. Since there is generally not a lot of formatting to be done anyway, and especially in the sorts of edits that are likely to be applied to XML, it is fairly simple to look at other parts of the document for guidance on how to make your changes.

Once you have changed the XML, you can rebuild the release notes with make as above, to see what the final result will look like. Be sure to carefully review the changes in the final form before committing them back to git.