The Firefox release notes process

This page explains how the release management team prepares release notes for Firefox.

About Firefox Release Notes

Every four weeks, Firefox desktop and Firefox for Android release a new version of the browser. We publish release notes on mozilla.org for an audience of web developers, tech press, and advanced and technical users of Firefox who want to be informed about the changes in Firefox's latest updates. The release notes page lists notable new features, changes, or unfixed critical bugs for a specific release of Firefox. Adding release notes content is the responsibility of the release management team, as requested by engineering/product and reviewed by a product writer.

See Firefox Release Notes Nomination for information on how to nominate release notes for Firefox.

Examples of past release notes:

Here is the full list of past Firefox release notes.

Release notes on the Nightly channel are published on Merge Day at the start of a new cycle. They are maintained continuously during the Nightly cycle.

Release notes for the Beta channel are published on the day we ship the first Firefox Beta of the cycle. They are maintained continuously during the Beta cycle.

Release notes for the Release channel are published on the day we ship Firefox to our users. They are not maintained continuously during the Release Cycle. A new release note page is published for any dot releases during the release cycle. 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 #release-notes internal Slack channel.

Summarized process

Release management creates a Nightly release notes page in Nucleus for the upcoming version.
Release management makes the Nightly release notes public in Nucleus on Merge Day.
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 copies applicable notes from the Nightly to the Beta release notes.
Release management makes the Beta release notes public in Nucleus after pushing Beta 1 live.
Release management shares a link to the Beta release notes on #release-notes.
During the Beta cycle, Release management monitors the relnote-firefox flag on Bugzilla and adds release notes for Beta in Nucleus.
Product writer creates a shared document for an editorial review and then shares it on #release-notes and to a mailing list.
Product writer copy-pastes notes from Beta Release Notes 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.
Engineering/Product may add notes directly to the shared document.
Product writer performs an editorial review in the shared document.
Release management creates a release notes page in Nucleus for the upcoming version.
Release management copies the reviewed release notes from the shared document into Nucleus.
Release management adds links to security advisories and developer documentation for the release.
Release management shares a link to the staging release notes on #release-notes.
Release management makes the release notes public in Nucleus after pushing the Release live.

Gathering of notes during the cycle

For complex software such as Firefox with thousands of patches during a cycle and external contributors, tracking what should be noted in release notes is not always easy.

Here is the main list of actions the release management team and product writers do to prepare release notes:

Check bugs nominated for release note addition for Nightly and add them to Nightly release notes if necessary.
Check mozilla-central commits daily for features potentially note-worthy. Ping the patch author and ask them to nominate the bug for release notes addition.
Ask people on several engineering mailing lists to tell us what note-worthy fixes are upcoming.
Share the final version of the release notes draft, ask for a review, and if there are any suggested changes.

Notes creation

Writing Notes: step by step process

Release Management gathers the notes
- Check note nominees from Bugzilla's relnote-firefox:? Flag
- Check with developers and managers as necessary to clarify.
First editing phase - Nightly/Beta
- Depending on where we are in the release cycle, Release Management adds release notes to Nightly or Beta in Nuclueus.
- Release Management shares the Beta draft for feedback and incorporates feedback.
Second editing phase - Release
- Product Writer reviews and edits wording.
- Release Management adds the edited notes into Nucleus.
- Release Management adds a note for security fixes pointing to our security advisories, this link is provided by the Security team:
  - Fixed - Various security fixes
Final edit phase
- Release Management shares the Release draft for feedback and incorporates feedback.

Dot-Release Notes

There are a few specifics to release notes for a dot-release.

Example: 102.0.1 release notes

Notes do have the bug number indicated (and linked to) between parentheses at the end.
Put a link to the reference release notes for the major version e.g.: Reference link to 102.0 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.

Aim to write in plain language:
- Avoid using technical language. We should aim to make it easy for the reader to understand. Some technical terms may be necessary depending on the release note.
- 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".
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.
- 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 known issues focus on how the user is impacted. If a workaround exists ensure to use clear instructions on how to leverage the workaround.
All URLs in release notes should be de-localized. Typically this means removing the 'en-US/' portion of the URL.
A release note that applies to both Desktop and Android should be written once and associated with both releases.
Don't link to bugs in the finalized release notes.
- NOTE: Include links to bugs in dot release notes.
Group items that belong to a category together. For example, items with WebRTC can be grouped together.
Use full stops at the end of every note. The MDN Writing Style is a good reference to follow for capitalization, contractions, numbers and numerals, pluralization, apostrophes and quotation marks, commas, hyphens, and spelling.

Nucleus: our publishing tool

Release notes are written and managed in Nucleus.

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).

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:

Release: https://www.mozilla.org/firefox/notes/
Beta: https://www.mozilla.org/firefox/beta/notes/
Nightly: https://www.mozilla.org/firefox/nightly/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 25mins for release notes to be available worldwide.

Release notes Categories

In Nucleus you should associate each note with a category. The notes will be grouped by category in the templated page on mozilla.org.

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
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