feat: change to one release page per version

.github/CODEOWNERS

@@ -5,4 +5,6 @@
 # For more information, see:
 # https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners
 
-* @bsmth
+* @bsmth
+
+/release-notes/ @bsmth @mkaply

.github/workflows/schema-sync.yml

@@ -1,8 +1,8 @@
-name: Weekly schema sync
+name: Daily schema sync
 
 on:
   schedule:
-    # Mondays at 07:00 UTC
+    # Daily at 08:30 UTC
     - cron: "30 8 * * *"
   workflow_dispatch:
 
@@ -59,9 +59,9 @@ jobs:
           else
             gh pr create \
               --title "chore(schema): sync from upstream" \
-              --body "Automated weekly sync of \`schema/policies-schema.json\`.
+              --body "Automated daily sync of \`schema/policies-schema.json\`.
 
-          Review the diff for new, removed, or changed policies before merging.
+          Review the diff for new, removed, or changed policies before merging. A new policy here usually needs a matching entry in \`release-notes/firefox.md\`.
 
           _Opened by the [\`.github/workflows/schema-sync.yml\`](https://github.com/${{ github.repository }}/tree/main/.github/workflows/schema-sync.yml) workflow._" \
               --label schema-sync \

.vscode/project-words.txt

@@ -36,6 +36,7 @@ Intune
 Jamf
 jnlp
 knowledgebase
+ksecdd
 localfilelinks
 managedfirefox
 mathml
@@ -66,17 +67,21 @@ sitepermission
 socksproxy
 SPNEGO
 sslproxy
+SSPI
 subkeys
 subresources
+SUMO
 systemconfig
 topsites
 topstories
 trackingprotection
+Trellix
 ublock
 unsubmitted
 urlbar
 userprefs
 videocontrols
+webauthn
 webrtc
 webserial
 whattrainisitnow

CHANGELOG.md

@@ -1,89 +1,11 @@
-# enterprise-firefox-admin-docs
+# Changelog
 
-<!-- markdownlint-disable MD024 -->
+Release notes for Firefox administrators live in
+[`release-notes/firefox.md`](release-notes/firefox.md), published at
+<https://firefox-admin-docs.mozilla.org/release-notes/>.
 
-## Unreleased
+They are organized by major Firefox release rather than by release train, so a single entry covers
+everything enterprise-relevant in that release cycle, including any Firefox point releases and the
+Firefox ESR release that shipped alongside it.
 
-### Added
-
-- `DefaultBrowserSettingEnabled` policy: Control whether the user can set Firefox as the default browser.
-- `DisableLocalPolicies` policy: Disable all local policy sources (policies.json, Windows GPO and macOS plist). [#216](https://github.com/mozilla/enterprise-admin-reference/pull/216)
-
-### Changed
-
-- `CrashReportsSubmit` policy: Update policy structure to remove `ForceAutoSubmit` key in favor of `Enabled` key ([#222](https://github.com/mozilla/enterprise-admin-reference/pull/222))
-- Replace the hand-maintained `Windows (Intune)` sections with an `OMA-URI` link to the [Firefox ADMX OMA-URIs for Intune](https://mozilla.github.io/policy-templates/oma-uris) reference, which is generated from `firefox.admx`.
-
-<!-- unpublished for now
-
-## ent-149.0.2
-
-### Added
-
-- `AIControls` policy: Configure AI controls. [#103](https://github.com/mozilla/enterprise-admin-reference/pull/103)
-
-## ent-149.0.0
-
-### Added
-
-- `AccessConnector` policy: Configure an Access Connector for proxying web traffic. [#102](https://github.com/mozilla/enterprise-admin-reference/pull/102)
-- `AIChatbot` policy: Configure the AI chatbot sidebar. [#106](https://github.com/mozilla/enterprise-admin-reference/pull/106)
-- `CrashReportsSubmit` policy: Configure crash report submission settings. [#86](https://github.com/mozilla/enterprise-admin-reference/pull/86)
-- `Sync` policy: Enable or disable sync and define which data to include. [#70](https://github.com/mozilla/enterprise-admin-reference/pull/70)
-
--->
-
-## esr-153.0.0
-
-### Added
-
-- `AIControls`: Configure AI controls. ([#103](https://github.com/mozilla/enterprise-admin-reference/pull/103))
-- `BrowserDataBackup`: Disable backup or restore of profile data. ([#33](https://github.com/mozilla/enterprise-admin-reference/pull/33))
-- `DefaultSerialGuardSetting`: Control use of the Web Serial API. ([#125](https://github.com/mozilla/enterprise-admin-reference/pull/125))
-- `DisableRemoteImprovements`: Prevent Firefox from applying performance, stability, and feature changes between updates. ([#64](https://github.com/mozilla/enterprise-admin-reference/pull/64))
-- `DisableRemoteSettingsAndAcceptSecurityConsequences`: Disable Remote Settings updates, stopping Firefox from receiving updated data such as blocklists, and accept the resulting security consequences. ([#236](https://github.com/mozilla/enterprise-admin-reference/pull/236))
-- `IPProtectionAvailable`: Prevent the built-in VPN from being available to users. ([#112](https://github.com/mozilla/enterprise-admin-reference/pull/112))
-- `LocalNetworkAccess`: Configure local network access security features. ([#67](https://github.com/mozilla/enterprise-admin-reference/pull/67))
-- `RelaunchRequired`: Require Firefox to be relaunched within a given period and notify the user of the upcoming relaunch. ([#127](https://github.com/mozilla/enterprise-admin-reference/pull/127))
-- `SitePolicies`: Defines policies scoped to specific sites. ([#82](https://github.com/mozilla/enterprise-admin-reference/pull/82))
-- `VisualSearchEnabled`: Enable or disable visual search. ([#33](https://github.com/mozilla/enterprise-admin-reference/pull/33))
-- `XSLTEnabled`: Enable or disable support for the XSLTProcessor JavaScript API and the XSLT processing instruction. ([#128](https://github.com/mozilla/enterprise-admin-reference/pull/128))
-
-## fx-151.0.0
-
-### Added
-
-- `DefaultSerialGuardSetting`: Control use of the Web Serial API. ([#125](https://github.com/mozilla/enterprise-admin-reference/pull/125))
-- `XSLTEnabled`: Enable or disable support for the XSLTProcessor JavaScript API and the XSLT processing instruction. ([#128](https://github.com/mozilla/enterprise-admin-reference/pull/128))
-
-## fx-150.0.0
-
-### Added
-
-- `RelaunchRequired`: Require Firefox to be relaunched within a given period and notify the user of the upcoming relaunch. ([#127](https://github.com/mozilla/enterprise-admin-reference/pull/127))
-- `SitePolicies`: Defines policies scoped to specific sites. ([#82](https://github.com/mozilla/enterprise-admin-reference/pull/82))
-
-## fx-149.0.2
-
-### Added
-
-- `AIControls` policy: Configure AI controls. [#103](https://github.com/mozilla/enterprise-admin-reference/pull/103)
-- `IPProtectionAvailable` policy: Prevent the built-in VPN from being available to users. [#112](https://github.com/mozilla/enterprise-admin-reference/pull/112)
-
-## fx-148.0.0
-
-### Added
-
-- `DisableRemoteImprovements`: Prevent Firefox from applying performance, stability, and feature changes between updates. ([#64](https://github.com/mozilla/enterprise-admin-reference/pull/64))
-
-## fx-145.0.0
-
-### Added
-
-- `LocalNetworkAccess`: Configure local network access security features. ([#67](https://github.com/mozilla/enterprise-admin-reference/pull/67))
-
-## fx-119.0.0
-
-### Added
-
-- `DisableAccounts`: Disable account-based services, including sync. ([#68](https://github.com/mozilla/enterprise-admin-reference/pull/68))
+See the Release notes section of [`CONTRIBUTING.md`](CONTRIBUTING.md) before editing.

CONTRIBUTING.md

@@ -85,42 +85,69 @@ Two lists hardcode policies that get no addition:
 - `MISSING_UPSTREAM` — may need one but missing from `firefox.admx`. These log a build warning.
   Remove a name once it lands upstream and the link starts rendering.
 
-## Changelog
+## Release notes
 
-The changelog is based on **Firefox versions**, not documentation versions.  
-If something changes, it should be recorded under the software version where an admin would expect to see those changes.
+Release notes live in `release-notes/firefox.md` and are published at `/release-notes/`.
+We publish **one page per major Firefox release**, covering everything enterprise-relevant in that release cycle: the major release itself, any point releases, and the Firefox ESR release that ships alongside it.
 
-### Version prefixes
+That means a page for release 153 has a `New in Firefox 153` section and a `New in Firefox ESR 153.0.0` section, because Firefox ESR 153.0.0 shipped alongside Firefox 153.
+The 149 page covers Firefox 149.0.2, which shipped later in the same cycle.
 
-Each version heading must include a release channel prefix so it's clear which release train it belongs to:
+### Release note file structure
 
-| Prefix | Channel            | Example          |
-| ------ | ------------------ | ---------------- |
-| `fx-`  | Firefox            | `## fx-119.0.0`  |
-| `esr-` | Firefox ESR        | `## esr-128.0.0` |
-| `ent-` | Firefox Enterprise | `## ent-150.0.0` |
+For each release, follow this convention:
 
-An `## Unreleased` section at the top of the file can be used for upcoming changes.  
-When a version ships, the unreleased entries can be moved out of the `## Unreleased` section as level 2 headings to be published:
+```md
+## 154
 
-### Entries
+<!-- Release date -->
 
-Changelog entries are user-facing to Firefox admins, meaning any changes specific to the docs site itself are mostly irrelevant.
-Use the following sections per release and omit any that don't apply:
+_Released 18 August 2026._
 
-- `### Added`: new policies or functionality relating to the policy engine
-- `### Changed`: anything that modifies policy behavior or defaults
-- `### Fixed`: bug fixes, or corrections to documentation
-- `### Removed`: removed policies or deprecated functionality
+<!-- Which versions the release notes apply to and the current ESR -->
 
-### Example
+These changes apply to Firefox 154 and Firefox ESR 153.1.0 unless explicitly stated.
+Firefox ESR 153 is the current ESR.
 
-The following entry is for Firefox release version 119:
+### New in Firefox 154
 
-```md
-## fx-119.0.0
+- [`CNSA2KeyAgreementEnabled`](/reference/policies/cnsa2keyagreementenabled/): Enable the CNSA 2.0 ML-KEM-1024 … Does not apply to the ESR. ([bug 2000001](https://bugzilla.mozilla/show_bug.cgi?id=2000001))
+
+### Changes
+
+- `SomePolicy`: Now defaults to `false`. ([bug 2000000](https://bugzilla.mozilla/show_bug.cgi?id=2000000))
+
+### Fixes
+
+- [`SearchEngines`](/reference/policies/searchengines/): `PreventInstalls` did not prevent users from manually… ([bug 2052965](https://bugzilla.mozilla.org/show_bug.cgi?id=2052965))
+
+<!-- an optional notes section -->
 
-### Added
+### Notes
 
-- `DisableAccounts` policy: Disable account-based services, including sync. ([#68](https://github.com/mozilla/enterprise-admin-reference/pull/68))
+- Firefox ESR 115 support for Windows 7/8 and macOS 10.12, 10.13 and 10.14 extends to August 2026.
 ```
+
+The following details matter for the generated pages:
+
+- Headings are the version number only: a `process` hook prefixes the headings with `Firefox`, so `## 154` is published as `Firefox 154` at `/release-notes/version/firefox-154/`.
+- Link each policy to its reference page, at the lowercased policy name.
+  Builds fail on broken internal links, so a policy with no reference page yet can be left unlinked.
+- Anything that deviates from co-shipping needs a scope note, like `Firefox 154 only.`, `Does not apply to the ESR.` at the end of the sentence before the bug link.
+
+### Fact checking
+
+The following things should be checked:
+
+- **Which ESR version shipped with a Firefox release**.
+  Check <https://whattrainisitnow.com/api/firefox/releases/esr>.
+- **Ship dates** come from <https://product-details.mozilla.org/1.0/firefox_history_major_releases.json>, or the `future` endpoint for releases that haven't shipped.
+- **Whether something reached ESR**.
+  For a new policy or option, check whether it's in `browser/components/enterprisepolicies/schemas/policies-schema.json` at the ESR release tag, like `FIREFOX_140_11_0esr_RELEASE`.
+  For a fix, check the bug's `cf_status_firefox_esr140` or `cf_status_firefox_esr153` flag on Bugzilla.
+- **Sub-properties or options**.
+  The policy's block in `Policies.sys.mjs` at the release tag is a good primary source, because it shows the options the build reads.
+  For example, the `NewTabOnRestore` sub-property was added in Firefox 153, but the compat table currently describes a policy as a whole rather than its options.
+  You can fetch a file at a tag with `https://hg-edge.mozilla.org/releases/<branch>/raw-file/<tag>/browser/components/enterprisepolicies/Policies.sys.mjs`, using branches like `mozilla-release` or `mozilla-esr153` and tags like `FIREFOX_154_0_RELEASE` or `FIREFOX_153_1_0esr_RELEASE`.
+
+The daily `schema-sync` workflow opens a PR when upstream adds or changes a policy, which is the prompt to add a release note.

astro.config.mjs

@@ -28,6 +28,7 @@ export default defineConfig({
     "/reference/policies/searchengines--remove/": "/reference/policies/searchengines/",
     "/reference/policies/securitydevices--deprecated/": "/reference/policies/securitydevices/",
     "/reference/policies/disablepocket_deprecated_/": "/reference/policies/disablepocket/",
+    "/changelog/": "/release-notes/",
   },
   devToolbar: {
     enabled: false,
@@ -85,6 +86,8 @@ gtag('config', 'G-LMXJXH34WG');`,
         : [],
       lastUpdated: true,
       plugins: [starlightGitHubAlerts(), starlightChangelogs(), starlightLinksValidator()],
+      // Gives each generated release note page its own title.
+      routeMiddleware: "./src/starlightRouteData.ts",
       sidebar: [
         {
           label: "Reference",
@@ -99,13 +102,18 @@ gtag('config', 'G-LMXJXH34WG');`,
           items: [{ label: "Support", slug: "support" }],
         },
         {
-          label: "Changelog",
+          label: "Release notes",
           items: [
             ...makeChangelogsSidebarLinks([
+              {
+                type: "all",
+                base: "release-notes",
+                label: "All releases",
+              },
               {
                 type: "recent",
-                base: "changelog",
-                count: 10,
+                base: "release-notes",
+                count: 6,
               },
             ]),
           ],