Release Notes - A New Era

[Karsten Wade]

It's time to start gathering notes for FC5 test1 and final release
notes.

There are some very good changes and additions to the process, to make
participation easier.  There are also some new things that you, as
developers, must do.

Highlights:

* Wiki used to gather notes,
  - not just bugzilla!

* Using *docs* keyword in CVS commit logs
  - new magic from Elliot!

* Translations of relnotes included in fedora-release package

* Sub-projects responsible for supplying a beat writer
  - You can coerce them, you can hijack them, but you have
    no content in the relnotes without them

http://fedoraproject.org/wiki/Docs/Beats/HowTo covers much of this same
material.

Don't know what the relnotes beats are?

http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Beats

* Changes *

** Wiki Used to Gather Notes **

Beat writers are now able to use the tree at
http://fedoraproject.org/wiki/Docs/Beats to gather raw input and form it
into content for the release notes.

These pages have a light structure that generally goes one layer deep,
for example, Docs/Beats/Kernel is for the kernel portion of the release
notes.  This maps nicely to one <section> or <chapter> in XML.

Beat writers are free to add and change sub-pages, as they need.   Other
contributors can do the same.  The only requirement to edit is that the
user be registered and logged in.

These beat notes are ongoing workspaces.  A snapshot is taken just prior
to freeze for translation, and the content is merged into the overall
DocBook/XML-based release notes.  These XML release notes are canonical,
but necessarily behind the raw Wiki pages.

Beat writers need to keep the content cleaned-up and relevant.  You want
to watch your page and all sub-pages using the pattern
Docs/Beats/Beatname.* in your "Subscribed wiki pages" of your
UserPreferences.

Wiki-help for beat contributions is on-topic for #fedora-docs.


** Highlighting Your CVS Commit for Documentation **

The next time that you make a CVS commit that fulfills a feature, fixes
a bug, or otherwise is worth noting in the relnotes, try this trick.

Put the keyword *docs* in the commit log message, and a copy of the
commit is sent to relnotes(a)fedoraproject.org .  The beat writers and
editors parse the note into the proper place, or open a bugzilla report
to track the note suggestion.

This is a must-do for Core packages, look for opportunities.  Extras
packages are encouraged to use this at milestone events, etc.

This page tells more about what to highlight for *docs*:

http://fedoraproject.org/wiki/DocsProject/WhatToDocument


** Use Bugzilla to Highlight an Existing Report **

Just add relnotes(a)fedoraproject.org to the Cc: field.  We'll parse this
into the proper place.


** File a Bug Report **

This small URL is for a pre-filled bugzilla report.  This is a great way
to submit a note or idea for the release notes, since conversations and
solutions are logged.  Bugs are set to block a master tracker for the
release.

http://tinyurl.com/89dkk


** Translations With Release **

The schedule for the release notes now includes time for translation, so
that the translated content can appear within the fedora-release
package.

At the top of the shipping release notes is a prominent link to the
latest online version of the relnotes.  This helps to counter the
problem of having to freeze the release notes so long before test and
release.  We'll do a Web-launch of a latest set of release notes to time
with the distro releases.


* New For Developers *

You are responsible within your Fedora sub-project to produce content
for the FC release notes.

Someone from your team needs to step-up and take the role of beat
writer, or find someone interested in helping your project to take that
role.

Being a beat writer is a _fantastic_ and reasonable way to get involved
with an open source project.  It's designed to be bite-sized for the
average volunteer.

Ultimately, the amount and quality of content in the release notes is
your responsibility.

The FDP takes all the rest of the responsibility -- merge, edit, convert
to XML, get translated, build multiple output formats, package for
fedora-release, publish to Web, make downloads available, and support
with ongoing updates as needed.


** Deadline to Pick Beat Writer **

By 23 September, all sub-projects need to have picked the person who is
the beat writer for your part of the release notes.  This is effective
for FC5 and forward.  In other words, a beat may be handed-off, it may
not be abandoned.

Cheers - Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/