Release notes process

From FedoraProject

Revision as of 03:48, 24 February 2009 by Ianweller (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
DocsProject Header docTeam1.png


Contents

Release Notes Process

This page explains the release notes process for the Fedora Project. Release notes are separated into beats for easier division and maintenance. Template:FedoraDict/Beat

Six Ways to Submit a Release Note

These are in order of preference, starting with the best option. Choose only one:

  1. Edit the content directly within the appropriate beat at Docs/Beats. This is the best option by far, since all account holders can edit the wiki as needed.
  2. Email relnotes@fedoraproject.org.
  3. Add relnotes@fedoraproject.org as a Cc: in an existing bug report.
  4. Change the fedora_requires_release_note flag on an existing Bugzilla entry to + How to use
  5. Enter a new release note request, comment, etc. into this pre-filled bugzilla request. NOTE: This Bugzilla link is NOT for problems with Fedora software, only for problems with the release notes themselves.
  6. Include the *docs* keyword in your CVS commit log. Read these guidelines on what to put in the commit message.

Read more details on all this at DocsProject/HighlightedForDocs . You can get more information about what to document.

We reserve the right to update this process in realtime, via the Wiki page and announcements to the developer announcement list.

Idea.png
Make Release Notes meaningful
The text "FooBar 1.2 is now included" is not a meaningful release note. What does the feature add from the user or developer's point of view? Follow up with details, but don't go overboard by listing every single change. Pick the most appealing new items to highlight. Indicate recommended usage if needed.


The Process

This content is maintained at DocsProject/ReleaseNotes/Process#The_Process .

  1. Content is updated in Docs/Beats throughout the development cycle under content-specific coverage areas (beats).
  2. For Fedora Alpha and Beta releases, the release notes are a one-sheet on the Wiki that summarizes the latest information about the release, with appropriate pointers. For the Preview release a full set of release notes is included in the distribution for preview and fixes before the final, Gold release notes are produced.
  3. Link to one-sheet should be included in releng's freeze reminder
    • Nagmail to f-maintainers and f-devel (automate?)
  4. One-sheet is linked from announcements
  5. One-sheet has link from within /usr/share/doc/HTML/index.html
  6. How do we link the one-sheet from /usr/share/doc/HTML/RELEASE-NOTES-*.html?
  7. A prominent link is placed in the one-sheet to Docs/Beats as an early preview of the Preview release notes. Contributions and etc. are invited.
  8. Coinciding with the Beta release and in preparation for the Preview release, content in Docs/Beats is checked and cleared out; a diff is generated using the Get Info tool in the Wiki, with the delta date around the previous Fedora release. Content is kept that was added after the release date or is a keep-for-a-few-releases piece, such as details on how to build a kernel from the src.rpm .
    • If a page has not changed but does not need to be released, the equivalent XML is left as-is in CVS
  9. For the Preview release notes, content is converted to XML and output to PO files for translation; scheduling is coordinated with the L10N project.
  10. This Preview is built into the fedora-release-notes package, which puts it in to the proper locations in /usr/share/doc/HTML/. This Preview needs to be widely promoted as the "beta" version of the release notes. Content should be >80% complete at this point to ease the burden on translators.
  11. Final changes come in from various locations prior to the final release of Fedora. The schedule is closely followed to make certain PO files arrive to translators on-time.
  12. Content that does not make the deadline is included in Docs/Beats . This location is prominently linked in the release notes, and is the source for any updates done to the fedora-release-notes package.
  13. A web-only update to the release notes is done on the day of Gold release for last minute changes; this is linked prominently from the in-ISO release notes.
    • Customarily this update is pushed as a zero-day package update to fedora-release-notes
    • Further fixes can be pushed in one or (rarely) more updates to fedora-release-notes

Using fedora_requires_release_note Bugzilla Flag

  1. Set the flag positive + to request a release note.
  2. A writer/editor sends in an acknowledgement in a comment, including a pointer to where the content landed
  3. If the content is not used, a writer/editor should set the value to negative -.

Help With the Release Notes

Current Wiki Users

To add content for the release notes, just edit the beats directly on the Wiki. This is explained at Docs/Beats/HowTo. You can find the list of beats at Documentation Beats.

FDP Writers, Editors, and New Members

If you are a writer/editor interested in working on part of the release notes:

  1. Join fedora-docs-list . You also want to read the DocsProject/NewWriters page.
  2. Visit the release notes beats page to read about release note beats and see the beat assignments. You can look at the active beats at Docs/Beats.
  3. Subscribe to the content flow mailing list that receives raw content from developers for relnotes and other documentation purposes.

Normally the release notes process uses bugzilla entries to track all requests, so nothing is lost between the cracks. You can see a list of all pending release notes bugs here in Bugzilla .

To publish the release notes from the Wiki, we take a snapshot of the Wiki, convert it to DocBook XML, have it translated, and included in the release. A snapshot is also taken and used as part of a Web-only latest release notes posted at the same time as general release. The latest release is linked prominently from the release notes that are linked from Fedora's Firefox default homepage.

Some philosophical notes on this process reside here .