The Firefox release notes process
This page explains how the release management team prepares release notes for Firefox.
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.
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.
Examples of past release notes:
- Firefox 103 for Android
- Firefox 103 for Desktop
- Firefox 103 Beta for Desktop
- Firefox Nightly 103 for Desktop
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.
How to decide whether a change should be included in release notes?
If you think your feature should be added to release notes, it's a good idea to nominate it for addition as soon as it is on the nightly channel.
If your feature is ready for testing on the nightly channel but is behind a feature flag and it isn't planned to ship on Beta/Release soon, please nominate it so that we can expose it to our alpha-testers. The r+ flag will be set by release management only when it ships to beta/release.
The changes that should be included in release notes include:
- New features for end users and web developers
- Important changes for end users and web developers
- Important stability and security fixes
- Important system requirements changes (ex: end of support for an OS version)
- New locales
How to nominate a bug for release notes addition?
Nomination in Bugzilla
1. Nominate a bug. Go to a bug in Bugzilla, and nominate fixes or changes for release notes. Expand the "Tracking Flags" section. Then set the relnote-firefox: flag to "?". Release management checks this flag regularly.
A form will pop up in the Bugzilla comments box, asking for your suggested wording for the note and an optional URL to link to further documentation.
2. Explain the fix. If your fix or another project should be in release notes, tell us what it did, what it means, and what the users and tech press should know. Details are very useful here.
A short video showing the above process.
Note that most of the changes impacting web developers (tooling, web standard support, and new technologies) are documented on MDN which has specific pages for releases aimed at developers. The MDN team tracks these bugs with the dev-doc-needed keyword.
The relnote-firefox tracking flag values
| --- | This bug has not been nominated for inclusion in Firefox release notes |
| ? | 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. |
| X+ | Release Management have determined this bug will be included in Firefox X release notes. |
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
- 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.
- Release Management & Marketing work on making sure the notes are accurate and have a verifiable source
- Checking with developerss and managers as necessary to clarify
- 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 emails out the draft for feedback (approximately 1 week ahead of release)
- Second editing phase
- Release Management puts the edited notes into the Nucleus back end. Each note should have a bug number associated in Nucleus, if possible
- Add a note for developer pointing to the MDN page for developers for the release:
- Developer - Changes affecting developers
- Add a note for security fixes pointing to our security advisories, this link is provided by the Security team:
- Fixed - Various security fixes
- Release Management sends out the links to staging to the communications 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 in Bugzilla to make sure the issue is fixed for the first time in that release.
Dot-Release Notes
There are a few specifics to notes for a dot-release.
Example: 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 (Bug 1459362)
- Put a link to the reference release notes for the major version with this sentence, ex: Reference link to 60.0 release notes
- In Nucleus make the note pointing to the reference mailing list as "release-specific" and don't associate any tag to it
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.
- 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).
- 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".
- 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
Release notes are written and managed in Nucleus.
The specific release notes process for the Nightly cycle is detailed in the Nightly cycle process page.
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 synces with Nucleus every 15mn, depending on CDN caching it may take up to 25mn to get release notes 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
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 |