From 17e20c63048ebee05ded794844f376ba8db42868 Mon Sep 17 00:00:00 2001
From: Brian Smith <brian@smith.berlin>
Date: Fri, 13 Mar 2026 10:44:49 +0100
Subject: [PATCH] feat: Add a basic changelog mechanism

---
 CHANGELOG.md          | 34 +++++++++++++++++++++++++++++++---
 CONTRIBUTING.md       | 41 +++++++++++++++++++++++++++++++++++++++++
 astro.config.mjs      | 13 ++++++++++++-
 src/content.config.ts |  9 ++++++++-
 4 files changed, 92 insertions(+), 5 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc21084..f9b1919 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,7 +1,35 @@
 # enterprise-firefox-admin-docs
 
-## 0.0.1
+<!-- markdownlint-disable MD024 -->
 
-### Additions
+## Unreleased
 
-- Initial commit
+### fx-150.0.0
+
+#### Added
+
+- `SitePolicies`: Defines policies scoped to specific sites. ([#82](https://github.com/mozilla/enterprise-admin-reference/pull/82))
+
+### esr-153.0.0
+
+#### Added
+
+- `SitePolicies`: Defines policies scoped to specific sites. ([#82](https://github.com/mozilla/enterprise-admin-reference/pull/82))
+
+### ent-150.0.0
+
+#### Added
+
+- Sync policy [#70](https://github.com/mozilla/enterprise-admin-reference/pull/70)
+
+## 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-119.0.0
+
+### Added
+
+- `DisableAccounts`: Disable account-based services, including sync. ([#68](https://github.com/mozilla/enterprise-admin-reference/pull/68))
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7089004
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing
+
+## Changelog
+
+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.
+
+### Version prefixes
+
+Each version heading must include a release channel prefix so it's clear which release train it belongs to:
+
+| Prefix | Channel            | Example          |
+| ------ | ------------------ | ---------------- |
+| `fx-`  | Firefox            | `## fx-119.0.0`  |
+| `esr-` | Firefox ESR        | `## esr-128.0.0` |
+| `ent-` | Firefox Enterprise | `## ent-150.0.0` |
+
+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:
+
+### Entries
+
+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:
+
+- `### 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
+
+### Example
+
+The following entry is for Firefox release version 119:
+
+```md
+## fx-119.0.0
+
+### Added
+
+- `DisableAccounts` policy: Disable account-based services, including sync. ([#68](https://github.com/mozilla/enterprise-admin-reference/pull/68))
+```
diff --git a/astro.config.mjs b/astro.config.mjs
index e46932f..719b04a 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -7,7 +7,6 @@ import starlightLinksValidator from "starlight-links-validator";
 
 export const locales = {
   root: { label: "English", lang: "en" },
-  // de: { label: "Deutsch", lang: "de" },
   // fr: { label: "Français", lang: "fr" },
 };
 
@@ -61,6 +60,18 @@ export default defineConfig({
           label: "Resources",
           items: [{ label: "Support", slug: "support" }],
         },
+        {
+          label: "Changelog",
+          items: [
+            ...makeChangelogsSidebarLinks([
+              {
+                type: "recent",
+                base: "changelog",
+                count: 10,
+              },
+            ]),
+          ],
+        },
       ],
       social: [
         {
diff --git a/src/content.config.ts b/src/content.config.ts
index 74e71bd..95fcc5c 100644
--- a/src/content.config.ts
+++ b/src/content.config.ts
@@ -15,9 +15,16 @@ export const collections = {
   changelogs: defineCollection({
     loader: changelogsLoader([
       {
-        provider: "changeset",
+        provider: "keep-a-changelog",
         base: "changelog",
         changelog: "CHANGELOG.md",
+        // see https://starlight-changelogs.netlify.app/providers/keep-a-changelog/#process
+        process: ({ title }) => {
+          if (title.startsWith("ent-")) return `Firefox Enterprise ${title.slice(4)}`;
+          if (title.startsWith("esr-")) return `Firefox ESR ${title.slice(4)}`;
+          if (title.startsWith("fx-")) return `Firefox ${title.slice(3)}`;
+          return title;
+        },
       },
     ]),
   }),