Release Management/Relnotes rules
This page describes the rules applied by the Release Team about the relnotes flag.
- 1 What are release notes?
- 2 relnote-firefox tracking flag
- 3 How to decide whether a bug should be included in release notes?
- 4 “relnote-firefox” tracking flag values
- 5 What happens when a bug is accepted for Release Notes documentation?
- 6 Categories of release note entries
- 7 Best practices for writing release notes
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/
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
- Web Developer Release Notes are now added as one note and then point directly to MDN for that release (Example: https://developer.mozilla.org/en-US/Firefox/Releases/49#Changes_for_Web_developers).
- 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.