273
edits
Release Management/Release Notes: Difference between revisions
Release Management/Release Notes (view source)
Revision as of 14:43, 6 December 2023
, 6 December 2023Included steps for when adding a release note in Nucleus with a rollout
No edit summary |
(Included steps for when adding a release note in Nucleus with a rollout) |
||
| (8 intermediate revisions by 2 users not shown) | |||
| Line 30: | Line 30: | ||
== Summarized process == | == Summarized process == | ||
# Release management creates a Nightly release notes page in Nucleus | # Release management creates a Nightly release notes page in Nucleus, makes the Nightly release notes public on Merge Day, and shares a link to the Nightly release notes on #release-notes. | ||
# During the Nightly cycle, Release management monitors the relnote-firefox flag on Bugzilla and adds release notes for Nightly in Nucleus. | # During the Nightly cycle, Release management monitors the relnote-firefox flag on Bugzilla and adds release notes for Nightly in Nucleus. | ||
# Release management creates a Beta release notes page in Nucleus for the upcoming version | # Release management creates a Beta release notes page in Nucleus for the upcoming version, copies applicable notes from the Nightly to the Beta release notes, makes the Beta release notes public in Nucleus after pushing Beta 1 live, and shares a link to the Beta release notes on #release-notes. | ||
# Release management creates a shared document for an editorial review, copy-pastes notes from Beta Release Notes to the shared document, and shares it on #release-notes and to the release-notes mailing list, | |||
# Release management creates a shared document for an editorial review and | |||
# Engineering/Product may add notes directly to the shared document. | # Engineering/Product may add notes directly to the shared document. | ||
# Release management continues to monitor the relnote-firefox flag on Bugzilla and add release notes in Nucleus and the shared document. | # Release management continues to monitor the relnote-firefox flag on Bugzilla and add release notes in Nucleus and the shared document. | ||
# Release management/Engineering/Product performs an editorial review in the shared document. | # Release management/Engineering/Product performs an editorial review in the shared document. | ||
# Release management creates a release notes page in Nucleus for the upcoming version | # Release management creates a release notes page in Nucleus for the upcoming version, and copies the reviewed release notes into Nucleus. | ||
# Release management adds links to security advisories and developer documentation for the release, and shares a link to the staging release notes on #release-notes. | |||
# Release management adds links to security advisories and developer documentation for the release | |||
# Release management makes the release notes public in Nucleus after pushing the release live. | # Release management makes the release notes public in Nucleus after pushing the release live. | ||
| Line 76: | Line 68: | ||
** Check the patches that landed. If the changes are behind a pref then check if the pref value is IS_NIGHTLY_BUILD, or IS_EARLY_BETA_OR_EARLIER | ** Check the patches that landed. If the changes are behind a pref then check if the pref value is IS_NIGHTLY_BUILD, or IS_EARLY_BETA_OR_EARLIER | ||
** Add the release note in Nucleus. | ** Add the release note in Nucleus. | ||
*** Add the appropriate Tag. | |||
*** Add the bug number in the Bug field. | |||
*** If the note is Nightly only use a html tag to indicate it’s nightly only. | *** If the note is Nightly only use a html tag to indicate it’s nightly only. | ||
** | ** If the release note is not Nightly only comment on the bug to inform it was added to nightly. | ||
*** "Thanks, added to Nightly release notes. Keeping the relnote? flag open to keep it on the radar for inclusion in our final release notes." | *** "Thanks, added to the Nightly release notes. Keeping the relnote? flag open to keep it on the radar for inclusion in our final release notes." | ||
** If the release note is Nightly only: | |||
*** Set the relnote flag to ''nightly+'' and add a comment: | |||
**** "Thanks, added to the Nightly release notes" | |||
== Beta - Refining notes during the Beta cycle == | == Beta - Refining notes during the Beta cycle == | ||
| Line 86: | Line 83: | ||
** Copy the release notes from nightly that are riding the train. | ** Copy the release notes from nightly that are riding the train. | ||
* Copy release notes to the release notes draft document. | * Copy release notes to the release notes draft document. | ||
* Publish the release notes after | * Publish the release notes after pushing Beta 1 live. | ||
* Share a link to the Beta Release Notes on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. | * Share a link to the Beta Release Notes on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. | ||
** "FxNNN beta preliminary release notes: https://www.mozilla.org/firefox/NNN.0beta/releasenotes/. If you know of anything worth mentioning but is not yet listed, please reach out or nominate it for a release note in Bugzilla. We will follow | ** "FxNNN beta preliminary release notes: https://www.mozilla.org/firefox/NNN.0beta/releasenotes/. If you know of anything worth mentioning but is not yet listed, please reach out or nominate it for a release note in Bugzilla. We will follow up with a link to the Firefox NNN Release Notes document." | ||
* Share a link to the draft release notes doc on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. Include a link to the draft document and the submission deadline. | * Share a link to the draft release notes doc on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. Include a link to the draft document and the submission deadline. | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
| Hi! We're at the start of the FxNNN Beta cycle, which means it is time for a new release notes cycle! | | Hi! We're at the start of the FxNNN Beta cycle, which means it is time for a new release notes cycle! | ||
Draft template for the Firefox NNN Release Notes | Draft template for the Firefox NNN Release Notes is here. | ||
The DEADLINE for submissions is ''Month Day, Year''. | The DEADLINE for submissions is ''Month Day, Year''. | ||
This will give us time to make necessary edits and/or changes before publishing on ''Month Day, Year''. | This will give us time to make necessary edits and/or changes before publishing on ''Month Day, Year''. | ||
| Line 105: | Line 102: | ||
** Check if the wording is appropriate. | ** Check if the wording is appropriate. | ||
** Add the release note in Nucleus and the draft document. | ** Add the release note in Nucleus and the draft document. | ||
** Comment on the bug to inform that the note was added to Beta | *** Add the appropriate Tag. | ||
*** Add the bug number in the Bug field. | |||
** Comment on the bug to inform that the note was added to Beta. | |||
* If an uplift in beta is to enable a feature to ride the train, ensure to remove the nightly only note from the current nightly release notes where applicable. | * If an uplift in beta is to enable a feature to ride the train, ensure to remove the nightly only note from the current nightly release notes where applicable. | ||
| Line 123: | Line 122: | ||
===Day before the release notes deadline=== | ===Day before the release notes deadline=== | ||
* Send a reminder on the [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. Reply to a thread of the previous reminder, but select to also send | * Send a reminder on the [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. Reply to a thread of the previous reminder, but select to also send to channel. | ||
===Day after the release notes deadline=== | ===Day after the release notes deadline=== | ||
* Add a release note for new contributors | |||
** See [https://github.com/mozilla/Relman/wiki/Running-new-contributor-script Running new contributor script] for instructions on the script. | |||
** Use the Community category when adding the release note. | |||
* Review the draft release notes document. | * Review the draft release notes document. | ||
* Inform the Release Management team the document is ready for peer review. | |||
** Another member of the team will review the release notes for clarity and/or to suggest improvements. | |||
* Create a new release in Nucleus for Desktop, Android, and iOS. | * Create a new release in Nucleus for Desktop, Android, and iOS. | ||
* | * Add release notes from the draft release notes document. | ||
** Add the appropriate Tag. | |||
** Order the release notes via the ''sort num'', the order will be from highest number to lowest. Otherwise, the default order is based when the release notes were added to the release. | ** Order the release notes via the ''sort num'', the order will be from highest number to lowest. Otherwise, the default order is based when the release notes were added to the release. | ||
** Group items that belong to a category | ** Group items that belong to a category in the same order. For example, items with WebRTC can be grouped together. | ||
** If the release note covers a feature that is part of a rollout and not enabled by default then enable '''Progressive rollout'''. | |||
*** If rollout is only targetted at specific countries then select ''Relevant countries'' from the list of '''Available relevant countries''' | |||
* Set the relnote tracking flag to XXX+ | * Set the relnote tracking flag to XXX+ | ||
* Share a link to the staged Release Notes on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. | * Share a link to the staged Release Notes on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. | ||
| Line 137: | Line 144: | ||
| NNN.0 Release notes are now available on the staging server. | | NNN.0 Release notes are now available on the staging server. | ||
If there are any wording suggestions or last minute additions, please reply to this thread. | If there are any wording suggestions or last minute additions, please reply to this thread. | ||
* ''link to staging Desktop | * ''link to staging Desktop release notes'' | ||
* ''link to staging Android | * ''link to staging Android release notes'' | ||
* ''link to staging iOS | * ''link to staging iOS release notes'' | ||
|} | |} | ||
* When available | * When available add links to security advisories and developer documentation. | ||
== Dot-Release Notes == | == Dot-Release Notes == | ||
| Line 148: | Line 155: | ||
===During dot release preperation=== | ===During dot release preperation=== | ||
* Evaluate if an uplift requires a release note | * Evaluate if an uplift requires a release note | ||
* Create a release in | * Create a release in Nucleus. | ||
** Add the release notes. | ** Add the release notes. Include the bug number indicated in a link between parentheses at the end. | ||
* | * Add 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]. | ||
* | * Share a link to the staged Release Notes on [https://mozilla.slack.com/archives/C9L102H6X #release-notes] internal Slack channel. | ||
== Known Issues == | == Known Issues Release Notes == | ||
For some defects reported post-release go-live, it should be evaluated if it is useful to add a known issue to the release notes. | For some defects reported post-release go-live, it should be evaluated if it is useful to add a known issue to the release notes. | ||
* Update the release notes to add a Known Issue. | * Update the release notes to add a Known Issue. | ||
| Line 159: | Line 166: | ||
** If there are multiple releases on the same version include the Known Issue in the release and all dot release versions. | ** If there are multiple releases on the same version include the Known Issue in the release and all dot release versions. | ||
* After a fix for the issue has been released, edit the Known Issue: | * After a fix for the issue has been released, edit the Known Issue: | ||
** Format the release note text to strikethrough | ** Format the release note text to strikethrough. | ||
** Append the text with information in bracket that includes the version that released the fix, for example “(Fixed in 120.0.1)” | ** Append the text with information in a bracket that includes the version that released the fix, for example “(Fixed in 120.0.1)” | ||
== Style Guide == | == Release Notes Style Guide == | ||
Readers need to know what features are introduced/changed, the technical meaning of the feature, and the impact the feature will have on users. | Readers need to know what features are introduced/changed, the technical meaning of the feature, and the impact the feature will have on users. | ||
| Line 169: | Line 176: | ||
** Avoid using colloquialisms or idioms. These can be confusing for readers depending on their region or their native language. | ** Avoid using colloquialisms or idioms. These can be confusing for readers depending on their region or their native language. | ||
** Avoid using abbreviations. For example, "pref" should be "preference". | ** Avoid using abbreviations. For example, "pref" should be "preference". | ||
* Avoid mentioning about:config prefs | |||
* For new or changed features focus on how it affects the user’s experience of Firefox, not what the software itself is doing. | * For new or changed features focus on how it affects the user’s experience of Firefox, not what the software itself is doing. | ||
** Example: To prevent session loss for inexperienced macOS users, Firefox now requests the user’s permission to install itself if it is being run from a mounted .dmg file. This request is only made the first time Firefox is run on a user’s computer. | ** Example: "To prevent session loss for inexperienced macOS users, Firefox now requests the user’s permission to install itself if it is being run from a mounted .dmg file. This request is only made the first time Firefox is run on a user’s computer." | ||
** This could be written as To prevent session loss for macOS users who are running Firefox from a mounted .dmg file, they’ll now be prompted to finish installation. This permission prompt only appears the first time these users run Firefox on their computer. | ** This could be written as "To prevent session loss for macOS users who are running Firefox from a mounted .dmg file, they’ll now be prompted to finish installation. This permission prompt only appears the first time these users run Firefox on their computer." | ||
* For bugs focus on how the user was impacted. Start the release note with a verb in the past tense, for example Fixed, Added, Removed. | * For bugs focus on how the user was impacted. Start the release note with a verb in the past tense, for example Fixed, Added, Removed. | ||
* For known issues focus on how the user is impacted. If a workaround exists ensure to use clear instructions on how to leverage the workaround. | * For known issues focus on how the user is impacted. If a workaround exists ensure to use clear instructions on how to leverage the workaround. | ||
| Line 180: | Line 188: | ||
* Use full stops at the end of every note. The MDN [https://developer.mozilla.org/docs/MDN/Writing_guidelines/Writing_style_guide#writing_style Writing Style] is a good reference to follow for capitalization, contractions, numbers and numerals, pluralization, apostrophes and quotation marks, commas, hyphens, and spelling. | * Use full stops at the end of every note. The MDN [https://developer.mozilla.org/docs/MDN/Writing_guidelines/Writing_style_guide#writing_style Writing Style] is a good reference to follow for capitalization, contractions, numbers and numerals, pluralization, apostrophes and quotation marks, commas, hyphens, and spelling. | ||
== Nucleus | == Nucleus Additonal Information== | ||
Release notes are written and managed in [https://nucleus.mozilla.org Nucleus]. | Release notes are written and managed in [https://nucleus.mozilla.org Nucleus]. | ||
| Line 193: | Line 201: | ||
* ESR: https://www.mozilla.org/firefox/organizations/notes/ | * ESR: https://www.mozilla.org/firefox/organizations/notes/ | ||
Mozilla.org syncs with Nucleus every 15mins, depending on CDN caching it may take up to | Mozilla.org syncs with Nucleus every 15mins, depending on CDN caching it may take up to 30mins for release notes to be available worldwide. | ||
In Nucleus you should associate each note with a category. The notes will be grouped by category in the templated page on mozilla.org. | In Nucleus you should associate each note with a category. The notes will be grouped by category in the templated page on mozilla.org. | ||
{| class="wikitable" | {| class="wikitable" | ||
|- | |||
! Tag (Category) !! Use Case | |||
|- | |- | ||
| New || New features | | New || New features | ||
| Line 208: | Line 217: | ||
|- | |- | ||
| HTML5 || Issues related to Web platform | | HTML5 || Issues related to Web platform | ||
|- | |- | ||
| Enterprise || Used to link to the enterprise release notes | | Enterprise || Used to link to the enterprise release notes | ||
| Line 217: | Line 224: | ||
|} | |} | ||
The ''Is known issue'' checkbox is used for issues that are not resolved in this release. They are categorized under ''Unresolved'' in the templated page on mozilla.org. | |||
=== Adding Images === | |||
Release notes can include images as follows: | |||
* Compress the image png with [https://tinypng.com/ tinypng.com] | |||
* Use an appropriate filename that includes the release version. | |||
* Commit the image to https://github.com/mozilla/release-notes-media/ | |||
** Please see the repo README for additional details. | |||
* Use the image URL in the Nucleus release note with appropriate alt text. | |||
* Example: | |||
** Image Source: 'https://github.com/mozilla/release-notes-media/blob/main/media/115_devtools.png' | |||
** Image URL: 'https://www.mozilla.org/media/img/firefox/releasenotes/note-images/115_devtools.png' | |||
** Release Note: https://nucleus.mozilla.org/admin/rna/note/789608/change/ | |||
* The <code><img></code> tag can also be used, which also allows the use of <code>height</code> and <code>width</code> attributes if resizing is necessary. | |||
** NOTE: The <code>height</code> and <code>width</code> attributes <b>must</b> be specified before the <code>alt</code> attribute or the image will not appear in the preview pane. It will still appear as expected in Bedrock, however. | |||
[[category:Release_Management|Release Notes]] | [[category:Release_Management|Release Notes]] | ||
[[category:Release_Management:Processes|Release Notes]] | [[category:Release_Management:Processes|Release Notes]] | ||