MozillaWiki

Release Management/Release Notes: Difference between revisions

Page Discussion

Release Management/Release Notes (view source)

Revision as of 14:14, 30 August 2022

2,310 bytes removed ,  30 August 2022
Minor Update
(Minor Update)
(Minor Update)
Line 40: Line 40:
The release management team maintains release notes for Firefox Desktop and Firefox for Android only. Release notes for other products are not in our scope at the moment.
The release management team maintains release notes for Firefox Desktop and Firefox for Android only. Release notes for other products are not in our scope at the moment.


For questions on the process please reach out on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel.


== How to decide whether a change should be included in release notes? ==
== How to decide whether a change should be included in release notes? ==
Line 89: Line 90:
== Notes creation ==
== Notes creation ==
=== Writing Notes: step by step process ===
=== Writing Notes: step by step process ===
* Gather the notes (2 weeks ahead of release)
* Release Management gathers the notes
** Find note nominees from Bugzilla's ''relnote-firefox:? ''flag, and from the Firefox Trello board for the release.
** Check note nominees from Bugzilla's relnote-firefox:? Flag
** Put into a Google doc draft.
** Check with developers and managers as necessary to clarify.
** Release Management & Marketing work on making sure the notes are accurate and have a verifiable source
* First editing phase - Nightly/Beta
** Checking with developerss and managers as necessary to clarify
** Depending on where we are in the release cycle, Release Management adds release notes to Nightly or Beta in Nuclueus.
** Ask developerss, managers, SUMO, or MDN editors to write posts and articles on mozilla.org sites so we can link to them from the notes
** Release Management shares the Beta draft for feedback and incorporates feedback.
* Release Management emails out the draft for feedback (approximately 1 week ahead of release)
* Second editing phase - Release
* Second editing phase
** Product Writer reviews and edits wording.
* Release Management puts the edited notes into the Nucleus back end. Each note should have a bug number associated in Nucleus, if possible
** Release Management adds the edited notes into Nucleus.
* Add a note for developer pointing to the MDN page for developers for the release:
** Release Management adds a note for security fixes pointing to our security advisories, this link is provided by the Security team:
**'''Developer''' - Changes affecting [https://developer.mozilla.org/en-US/Firefox/Releases/59 developers]
*** '''Fixed''' - Various [https://www.mozilla.org/security/advisories/mfsa2018-06/ security fixes]
* Add a note for security fixes pointing to our security advisories, this link is provided by the Security team:
** '''Fixed''' - Various [https://www.mozilla.org/security/advisories/mfsa2018-06/ security fixes]
* Release Management sends out the links to staging to the communications team
* Final edit phase
* Final edit phase
 
** Release Management shares the Release draft for feedback and incorporates feedback.  
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 in Bugzilla to make sure the issue is fixed for the first time in that release.


=== Dot-Release Notes ===
=== Dot-Release Notes ===
There are a few specifics to notes for a dot-release.
There are a few specifics to release notes for a dot-release.
 
Example: [https://www.mozilla.org/en-US/firefox/60.0.1/releasenotes/ 60.0.1 release notes]


* Notes '''do''' have the bug number indicated (and linked to) between parenthesis at the end, ex: ''WebVR has been disabled by default on macOS ([https://bugzilla.mozilla.org/show_bug.cgi?id=1459362 Bug 1459362])''
Example: [https://www.mozilla.org/firefox/102.0.1/releasenotes/ 102.0.1 release notes]
* Put a link to the reference release notes for the major version with this sentence, ex: ''Reference link to [https://www.mozilla.org/firefox/60.0/releasenotes/ 60.0 release notes]''
* Notes do have the bug number indicated (and linked to) between parentheses at the end.
* In Nucleus make the note pointing to the reference mailing list as "release-specific" and don't associate any tag to it
* Put a link to the reference release notes for the major version e.g.: Reference link to [https://www.mozilla.org/firefox/102.0/releasenotes/ 102.0 release notes].


=== Best practices for writing release notes ===
=== 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 notes should be de-localized. Typically this means removing the 'en-US/' portion of the URL.
* All URLs in notes should be de-localized. Typically this means removing the 'en-US/' portion of the URL.
* A note that applies to both Desktop and Android should be written once and associated with both releases.
* A note that applies to both Desktop and Android should be written once and associated with both releases.
* Don't link to bugs in the note (we do link to bugs in dot releases).
* Don't link to bugs in the note (we do link to bugs in dot releases).
* Notes 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 notes 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".
* 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.
* 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.


== Nucleus: our publishing tool ==
== Nucleus: our publishing tool ==
Release notes are written and managed in [https://nucleus.mozilla.org Nucleus].
Release notes are written and managed in [https://nucleus.mozilla.org Nucleus].
The specific release notes process for the Nightly cycle is detailed in the [[Release_Management/Nightly|Nightly cycle process]] page.


=== Nucleus and mozilla.org ===
=== Nucleus and mozilla.org ===
The release notes page on mozilla.org for a specific version will not be available while the ''is_public'' flag is not selected in Nucleus but it will be available on the staging instance of mozilla.org (www-dev.allizom.org).
The release notes page on mozilla.org for a specific version will not be available while the is_public flag is not selected in Nucleus but it will be available on the staging instance of mozilla.org (www-dev.allizom.org).


If a release is created in Nucleus but the release notes page doesn't have the ''is_public'' flag set to true, a "coming soon" page is displayed on mozilla.org.
If a release is created in Nucleus but the release notes page doesn't have the is_public flag set to true, a "coming soon" page is displayed on mozilla.org.


There are simplified URLs for release notes that do not contain the version number and will always redirect to the latest version for the channel as provided in product-details:
There are simplified URLs for release notes that do not contain the version number and will always redirect to the latest version for the channel as provided in product-details:
Line 145: Line 132:
* ESR: https://www.mozilla.org/firefox/organizations/notes/
* ESR: https://www.mozilla.org/firefox/organizations/notes/


Mozilla.org synces with Nucleus every 15mn, depending on CDN caching it may take up to 25mn to get release notes available worldwide.
Mozilla.org syncs with Nucleus every 15mins, depending on CDN caching it may take up to 25mins for release notes to be available worldwide.
 
=== Creating a new release notes page ===
For the first beta release, from the nucleus interface:
* Copy the nightly release (is_public is going to be disabled)
* Update the title
* Update the date
* Update the description text
* Enable ''is_public'' on the beta release day
 
For the release, from the nucleus interface:
* Copy the beta release (is_public is going to be disabled)
* Update the title
* Update the date
* Update the description text
* Update the notes
* Once the notes have been signed off and the release is live, select ''is_public''.
 
Note that the System Requirements page for a release is also managed from Nucleus. If Firefox system requirements change, don't forget to update them for the release affected.


=== Release notes Categories ===
=== Release notes Categories ===
Line 182: Line 151:
|-
|-
| Unresolved || List of known issues that are not resolved in this release
| Unresolved || List of known issues that are not resolved in this release
|-
| Enterprise || Used to link to the enterprise release notes
|-
| Community || List of bugs fixed by community contributors this release
|-
|-
|}
|}
Dmeehan
406

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/1243796"