Release Management/Relnotes rules: Difference between revisions
Jump to navigation
Jump to search
(draft of a documentation about the relnote-firefox flag) |
m (Remove indexing in category page) |
||
| (20 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
'''This | #REDIRECT [[Release_Management/Release_Notes]] | ||
This page describes the rules applied by the Release Team about the relnotes flag. | |||
= What are release notes? = | |||
The release notes page lists notable 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: | |||
* [https://www.mozilla.org/en-US/firefox/38.0/releasenotes/ Firefox 38.0 Desktop release notes] | |||
* [https://www.mozilla.org/en-US/firefox/37.0/releasenotes/ Firefox 37.0 Mobile beta release notes] | |||
= 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. | |||
= Release note writing process = | |||
* Gather the notes (2 weeks ahead of release) | |||
** Find note nominees from Bugzilla's relnote-firefox:? flag, and from the Firefox Trello board for the release. | |||
** Put into a Google doc draft. | |||
*** For reference: "[https://drive.google.com/open?id=0B3Po9bsZ673yNFRLTGwtRjZGN2s Drafts of release notes]" from previous releases | |||
** Relman + Marketing work on making sure the notes are accurate and have a verifiable source | |||
** Checking with devs and managers as necessary to clarify | |||
** Ask devs, managers, SUMO, or MDN editors to write posts and articles on mozilla.org sites so we can link to them from the notes | |||
* Relman emails out the draft for feedback (approx. 1 week ahead of release) | |||
* Second editing phase | |||
* Relman puts the edited notes into the Nucleus back end. Each note should have a bug number associated in Nucleus, if possible | |||
* Relman sends out the links to staging to the comms team | |||
* Final edit phase | |||
Relevant information from the bug should be added as an item in the [https://nucleus.mozilla.org/ Nucleus database] for a specific release. | |||
Look for the "fixed" or "verified" flag to make sure the issue is fixed for the first time in that release. | |||
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. (We do link to bugs in dot releases, though) | |||
* Be sure to include a link to | |||
** Developer notes on MDN; example: https://developer.mozilla.org/Firefox/Releases/60 | |||
** Security advisories; example: https://www.mozilla.org/security/advisories/mfsa2018-06/ | |||
* Relnotes are sentence fragments. Don't start them with 'The', 'A', etc. Don't use periods, in general, unless there is a good reason the note has more than one sentence. | |||
* 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. | |||
Latest revision as of 12:28, 6 April 2018
Redirect to:
This page describes the rules applied by the Release Team about the relnotes flag.
What are release notes?
The release notes page lists notable 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.
Release note writing process
- Gather the notes (2 weeks ahead of release)
- Find note nominees from Bugzilla's relnote-firefox:? flag, and from the Firefox Trello board for the release.
- Put into a Google doc draft.
- For reference: "Drafts of release notes" from previous releases
- Relman + Marketing work on making sure the notes are accurate and have a verifiable source
- Checking with devs and managers as necessary to clarify
- Ask devs, managers, SUMO, or MDN editors to write posts and articles on mozilla.org sites so we can link to them from the notes
- Relman emails out the draft for feedback (approx. 1 week ahead of release)
- Second editing phase
- Relman puts the edited notes into the Nucleus back end. Each note should have a bug number associated in Nucleus, if possible
- Relman sends out the links to staging to the comms team
- Final edit phase
Relevant information from the bug should be added as an item in the Nucleus database for a specific release. Look for the "fixed" or "verified" flag to make sure the issue is fixed for the first time in that release.
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. (We do link to bugs in dot releases, though)
- Be sure to include a link to
- Developer notes on MDN; example: https://developer.mozilla.org/Firefox/Releases/60
- Security advisories; example: https://www.mozilla.org/security/advisories/mfsa2018-06/
- Relnotes are sentence fragments. Don't start them with 'The', 'A', etc. Don't use periods, in general, unless there is a good reason the note has more than one sentence.
- 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.