Release Notes Process

[John J. McDonough]

We have several new contributors, and we are right at the point of
getting serious with release notes, so I thought I would outline the
process specifically for a few new folks, but also to the list just in
case someone needs some blanks filled in.

Some of this will be old news to those of you who joined in the bug
stomping day, but not all of it!  And yes, it is way too long.  I have a
tendency to run off at the mouth (fingers).

The release notes are probably the largest project Docs routinely takes
on.  Some of the guides are quite a bit larger and more complex, but the
guides only get updated every release; release notes are a start from
scratch exercise every time.

We begin the release notes process by clearing out the "beats" and
emailing the beat writers asking them to look at their beats.  The sad
part is they rarely respond.

The beats are a set of wiki pages, indexed at:
http://fedoraproject.org/wiki/Documentation_Beats

Notice that some of the beats are crossed off.  These are beats that
haven't had any content for the past couple of releases, and don't look
like they have any this release, but might.  These beats aren't cast in
stone.  They simply represent areas of capability that have been
interesting in the past.  If there happens to be a sudden burst of
activity around, say, basket weaving software this release, then we will
add a basket weaving beat.  At the current time, however, I have not
discovered any basket weaving software in Fedora, so as a result, no
basket weaving beat.

What we do is capture information for the release notes in those beats.
These are easy to edit and it allows us to get more people involved in
collecting this information.  Sometimes developers, SIG members, all
kinds of people contribute.  We can easily add beats, rearrange things,
and generally get an overview of what the release notes will look like.

If there is an area that interests you, and nobody has picked up on the
beat, then feel free to dive in.  Do a little research on what is new
for Fedora 13, contact the developer, look at the upstream pages, and
write some prose in the beat that you think needs to be in the release
notes.

It is important to note that the release notes document "significant"
changes. There are over 13,000 packages in Fedora, and every release,
several thousand of those change.  Unfortunately, what is "significant"
to one person is arcane to another, so we need to apply a little
judgement or guesswork to figure out what it significant.

I will make a (large) table towards the end of the process that
identifies every change and has a link to the upstream web page where
(hopefully) the changes are documented, so the potential user at least
has a chance to see if his favorite fix/upgrade is in there.  But the
release notes will be translated into a lot of languages, so we want to
keep the actual prose down to some sensible size.  The large tables are
arranged so they need no translation.

At the beginning of each release, developers propose major upgrades
which are vetted and ultimately many are included in the next release.
In this process, the developers write "feature pages" describing the
feature, what it's impact is, discuss the risks, etc.  They also include
some proposed release notes language.  For each feature, I have put a
link to the feature page on the beat's wiki page, so for someone just
getting started, an easy thing to do would be to go to one of those
feature pages, review the page, and write some release notes on the beat
wiki page.  Often these features change over time, so you want to read
and understand the feature page (which is updated from time to time) and
not just copy the release notes prose from that page as that prose often
doesn't reflect the changes, and it is often from a developer's point of
view, and may need some work to reflect a user's point of view.

We need to get the wiki populated pretty quickly, so don't be shy about
rolling up your sleeves and diving in.

Next week we will begin translating the wiki to DocBook for the actual
release notes document.  This is mostly a manual process but actually
tends to go quite quickly.  On the 24th, we will produce the RPM for F13
beta.  Release notes are installed by default on Fedora, as well as
being available in a number of formats on
http://docs.fedoraproject.org

The DocBook source is kept in git, and if you want to push changes
yourself, you need to be a member of the FAS group, gitrelease-notes.
However, it is a simple matter to ask git to generate a patch and then
mail that patch to the list if you are a little uncomfortable about
making direct changes initially.

In any case, to work on the DocBook you will want to have git and
Publican installed.

Currently, the tip of the git repository contains the Fedora 12 release
notes.  We are waiting for an upgrade to the translation software before
making the Fedora 13 branch.

The Fedora 12 release notes are still built using Publican 0.44 which is
quite different from Publican 1.0, so until we make the F13 branch, you
can't make a test build to see how it works.  you can clone the
repository, however (about 60 megs) to poke around in the source and
play with git.

The way git works is you make a local repository.  You can the edit
files, build the document, commit changes to your local repository, and
generally do everything without affecting everyone else.  Then at some
point you can push your changes to the main repository.  This model
makes it pretty simple to start over if you really mess up.  Simply
remove your local repository and clone again.  Except for the initial
clone git is really fast.  You can do everything except push without
being a member of gitrelease-notes.

Once the release notes are more or less final, we build them in html,
html-single and pdf and post those versions on docs.fedoraproject.org.
We also make an RPM for inclusion on the Fedora CDs and DVDs.

A few documents that might be helpful:

Docs quick start, a little stale but not too bad:
http://docs.fedoraproject.org/documentation-quick-start/

The documentation guide is very stale and only interesting if you happen
to be the person pushing to docs.fp.o, although it does contain some
nice material for emacs users:
http://docs.fedoraproject.org/documentation-guide/en_US/

A git quick reference.  Not complete, but still probably more than you
need to know:
https://fedoraproject.org/w/index.php?title=Git_Quickref&printable=yes

An overview of the Docs Project (you probably already saw this one)
http://fedoraproject.org/wiki/DocsProject

The primary way to communicate is through the list and through IRC.  If
you have ANY questions, don't be afraid to ask.  Lots of people are
idling on #fedora-docs on freenode all the time.  If you ask there
someone will answer.  If you need a more detailed explanation, or if you
need an asynchronous answer, then the list is the place.  Chances are,
the list is usually the best place because if you have a question, most
likely someone else does, too.  But if you are shy, don't be afraid to
email me directly.  And in most cases, IRC is generally the quickest.

And don't forget, each Wednesday at 2300Z (7PM EDT) we have a meeting in
#fedora-meeting.

So please, jump right in.  It is surprisingly fun and very satisfying.

--McD