Release Notes Process

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