Release Management/Relnotes rules

From MozillaWiki
Jump to: navigation, search

This page describes the rules applied by the Release Team about the relnotes flag.

What are release notes?

The release notes page lists all the new features, changes or unfixed critical bugs for a specific release of Firefox (desktop/mobile, beta/release, etc). Their edition and content are under the responsibility of the release team.

Release notes from past Firefox releases: https://www.mozilla.org/en-US/firefox/releases/

Examples:

relnote-firefox tracking flag

It is multi-state flag that currently has several values which indicate whether a bug has been included in firefox release/beta/aurora/nightly release-notes. Bugs nominated for “relnote-firefox” (by setting the flag to “?”) are bugs that are deemed to have a high end-user impact and and should be included in the release notes on firefox release/beta/aurora/nightly release.

How to decide whether a bug should be included in release notes?

The different categories of bugs that should be included in releases notes include:

  • New features for end users (example: pocket)
  • New features for developers (ex:WebSocket now available in Web Workers)
  • New features for user of the developer tools (ex: performances tools)
  • New locales
  • Important changes for end user (ex: changes in the interface for the android app)
  • Important changes for developers or sysadmin

“relnote-firefox” tracking flag values

  • ?” This bug has been nominated for inclusion in Firefox release notes. Please fill out the template so as to help release-drivers with formulating the actual release note content.
  • -” (minus) - Drivers have determined this bug does not meet the bar for inclusion in release notes. A comment in the bug will explain why.
  • N+” - Drivers have determined this bug will be included in FirefoxN release notes.
  • N+1+” - Drivers have determined this bug will be included in FirefoxN+1 release notes.
  • N+2+” - Drivers have determined this bug will be included in FirefoxN+2 release notes.
  • N+3+” - Drivers have determined this bug will be included in FirefoxN+3 release notes.
  • N+4+” - Drivers have determined this bug will be included in FirefoxN+4 release notes.

What happens when a bug is accepted for Release Notes documentation?

Relevant information from the bug should be added as an item in the Nucleus database for a specific release. Look for the field Target Milestone or Version to find out in which version it will be available.

Legacy: in the past, the "relnote" keyword was used. It has been disabled from Bugzilla and should not be available.

Categories of release note entries

  • New - new features
  • Fixed - List of known Issues that have been fixed
  • Changed - Important changes to browser interface/behavior that will be valuable for Firefox end-users to know about.
  • Developer - Issues that are of special interest to Firefox Developer audience
  • HTML5 - Issues related to Web platform (will be renamed)
  • Unresolved - List of known issues that are not resolved in this release.

Best practices for writing release notes

  • All URLs in relnotes should be de-localized. Typically this means removing the 'en-US/' portion of the URL.
  • A relnote that applies to both desktop and android should be written once and associated with both releases.
  • Don't link to bugs.
  • Relnotes are sentence fragments. Don't start them with 'The', 'A', etc. Don't use periods.
  • Keep relnotes as short as possible. If you find yourself wanting to start a new sentence, figure out a way to rephrase the note.
  • Do not use abbreviations. For example, "pref" should be "preference".
  • Group items that belong to a category together. For example, items with WebRTC can be grouped together.
  • "Developer" tag is for "Developer Tools".
  • Get the release notes ready for review by requesting feedback across Mozilla. The audience reviewing this includes RelMan, release-drivers, fx-team, front-end team, SUMO team, platform-devs, QE, etc. Please follow up and close on the review feedback comments promptly.