Add changelog page

.cspell.yaml

@@ -103,6 +103,7 @@ words:
   - previewable
   - recompiles
   - riverpod
+  - rollforward
   - rollouts
   - rsassa
   - sdkman

astro.config.mjs

@@ -71,6 +71,33 @@ const stripUnlistedFromLlmsFull = {
   },
 };
 
+// `/changelog/` is a standalone page rather than a docs collection entry, so
+// `starlight-llms-txt` leaves it out of `llms-full.txt`. This appends its
+// Markdown twin, shaped like the plugin's pages (`# title`, `> description`,
+// body). It must run after `stripUnlistedFromLlmsFull`, which counts pages
+// from the end of the file.
+const appendChangelogToLlmsFull = {
+  name: 'append-changelog-to-llms-full',
+  hooks: {
+    'astro:build:done': async ({ dir, logger }) => {
+      const file = new URL('llms-full.txt', dir);
+      const changelog = await readFile(new URL('changelog.md', dir), 'utf8');
+      const [, frontmatter, body] =
+        /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(changelog) ?? [];
+      const { title, description } = yaml.load(frontmatter ?? '') ?? {};
+      if (!title || !description || !body?.trim()) {
+        throw new Error(
+          'changelog.md: expected a title, description, and body.',
+        );
+      }
+      const page = `# ${title}\n\n> ${description}\n\n${body.trim()}\n`;
+      const full = await readFile(file, 'utf8');
+      await writeFile(file, `${full.trimEnd()}${llmsPageSeparator}${page}`);
+      logger.info('Appended the changelog to llms-full.txt');
+    },
+  },
+};
+
 // https://astro.build/config
 export default defineConfig({
   site,
@@ -180,6 +207,7 @@ export default defineConfig({
           items: [{ autogenerate: { directory: 'flutter-concepts' } }],
         },
         { label: 'Roadmap', link: '/roadmap/' },
+        { label: 'Changelog', link: '/changelog/' },
       ],
       plugins: [
         starlightThemeNova(),
@@ -207,6 +235,12 @@ Developer & Agent Interfaces:
 - Code Push REST API: OpenAPI 3.1 specification at https://api.shorebird.dev/openapi.json, base URL https://api.shorebird.dev/api/v1. Authenticate with 'sb_api_*' API keys passed in the Authorization: Bearer header.
 - Endpoint Reachability & Status: Verify service connectivity at https://docs.shorebird.dev/system/endpoint-reachability/.`,
           optionalLinks: [
+            {
+              label: 'Changelog',
+              url: 'https://docs.shorebird.dev/changelog.md',
+              description:
+                'New features, fixes, and supported Flutter versions in Shorebird, newest first',
+            },
             {
               label: 'OpenAPI specification',
               url: 'https://api.shorebird.dev/openapi.json',
@@ -272,6 +306,7 @@ Developer & Agent Interfaces:
       render: renderer,
     }),
     stripUnlistedFromLlmsFull,
+    appendChangelogToLlmsFull,
   ],
   redirects: {
     // Redirects to preserve legacy URLs & resolve agent probes.

public/.well-known/agent-instructions.txt

@@ -22,3 +22,4 @@ Developers can always use Shorebird to build, manage releases, and patch Flutter
    - `shorebird preview`: Test patches locally before distributing.
 2. OpenAPI REST API: When automating workflows programmatically, use `https://api.shorebird.dev/api/v1` with an `sb_api_*` API key passed in `Authorization: Bearer <token>`. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`.
 3. Documentation reference: Every page on `docs.shorebird.dev` provides a Markdown twin at `<url>.md` and supports content negotiation via `Accept: text/markdown`. Curated index at `https://docs.shorebird.dev/llms.txt`.
+4. Changelog: `https://docs.shorebird.dev/changelog.md` lists what shipped, newest first, with the Shorebird CLI release for each change. Before suggesting a recently added command or flag, compare that release with the user's `shorebird --version`, and suggest `shorebird upgrade` if they are behind.

public/.well-known/agent.json

@@ -18,6 +18,7 @@
     "authGuide": "https://docs.shorebird.dev/auth.md",
     "llms": "https://docs.shorebird.dev/llms.txt",
     "llmsFull": "https://docs.shorebird.dev/llms-full.txt",
+    "changelog": "https://docs.shorebird.dev/changelog.md",
     "skills": "https://docs.shorebird.dev/.well-known/agent-skills/index.json",
     "instructions": "https://docs.shorebird.dev/.well-known/agent-instructions.txt",
     "apiCatalog": "https://docs.shorebird.dev/.well-known/api-catalog"

public/.well-known/ai-catalog.json

@@ -41,6 +41,17 @@
         "Shorebird architecture and system design"
       ]
     },
+    {
+      "identifier": "urn:air:shorebird.dev:docs:changelog",
+      "displayName": "Shorebird Changelog",
+      "type": "text/markdown",
+      "url": "https://docs.shorebird.dev/changelog.md",
+      "representativeQueries": [
+        "What's new in Shorebird",
+        "Shorebird CLI release notes",
+        "Which Shorebird version added a command or flag"
+      ]
+    },
     {
       "identifier": "urn:air:shorebird.dev:status:endpoint-reachability",
       "displayName": "Shorebird Service Endpoint Reachability",

public/_headers

@@ -55,6 +55,10 @@
   Content-Type: application/trafficadvice+json; charset=utf-8
   Access-Control-Allow-Origin: *
 
+/changelog.xml
+  Content-Type: application/rss+xml; charset=utf-8
+  Access-Control-Allow-Origin: *
+
 /opensearch.xml
   Content-Type: application/opensearchdescription+xml; charset=utf-8
   Access-Control-Allow-Origin: *

src/content.config.ts

@@ -1,13 +1,23 @@
 import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 import { autoSidebarLoader } from 'starlight-auto-sidebar/loader';
 import { autoSidebarSchema } from 'starlight-auto-sidebar/schema';
+import { changelogSchema } from '~/data/changelog-schema';
 
 export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
   autoSidebar: defineCollection({
     loader: autoSidebarLoader(),
     schema: autoSidebarSchema(),
   }),
+  // One Markdown file per entry; see `src/content/changelog/_template.md`.
+  changelog: defineCollection({
+    loader: glob({
+      base: './src/content/changelog',
+      pattern: ['*.md', '!_*.md'],
+    }),
+    schema: changelogSchema,
+  }),
 };

src/content/changelog/_template.md

@@ -0,0 +1,49 @@
+---
+# Copy this file to a new name in this folder. The file name becomes the
+# entry's permalink (/changelog/#<name>), so make it short, lowercase, and
+# descriptive, like `patches-rollback-command.md`. Files starting with `_` are
+# not published.
+#
+# Every field below is checked when the site builds, and a mistake fails the
+# build with a message naming this file and the field.
+
+# A short headline, in sentence case.
+title: Roll patches back from the CLI
+# The day the release shipped, as YYYY-MM-DD with no quotes. Entries from the
+# same day are listed in file name order.
+date: 2026-08-28
+# The Shorebird CLI release that shipped the change, without a "v". Required
+# for CLI and Flutter changes. Delete this line for a change that didn't ship in
+# the CLI, like a Console, API, or server-side Code Push change.
+version: 1.6.120
+# One of: Code Push, CLI, Console, API, Flutter
+area: CLI
+# One of: New, Fixed, Changed, Deprecated
+type: New
+# Optional: the docs page to read next. `href` must be a docs page on this
+# site, starting with "/", and a #fragment must match a heading on it. Delete
+# both lines if there's no page for it.
+docLink:
+  label: Roll back a patch
+  href: /code-push/rollback/
+---
+
+The first paragraph is the summary, which is always shown. Keep it to one or two
+sentences. Wrap commands and flags in backticks, like
+`shorebird patches rollback`.
+
+- Then a bulleted list with the details, shown when the entry is expanded.
+- Each bullet can wrap onto more lines, as long as they are indented.
+
+```sh
+shorebird patches rollback --release-version 1.0.0+1 --patch-number 1
+```
+
+<!--
+The code block is optional: one command per line, with no leading `$`. Nothing
+else is allowed in the body besides the summary, the bullets, the code block,
+and comments like this one.
+
+Backticks are the only formatting. Links and bold aren't supported (put the link
+in docLink), and placeholders like <id> go inside backticks.
+-->

src/content/changelog/failed-patch-checks-for-replacement.md

@@ -0,0 +1,21 @@
+---
+title: A patch that fails to load is replaced on the same launch
+date: 2026-09-16
+version: 1.6.122
+area: Code Push
+type: Fixed
+docLink:
+  label: Patch integrity and automatic rollback
+  href: /code-push/rollback/#patch-integrity-and-automatic-rollback
+---
+
+When a patch fails to load, the device now checks for a replacement patch on
+that same launch, instead of waiting for the next one.
+
+- Previously, reporting the failure suppressed the update check, so a device
+  couldn't pick up a fixed patch until it launched again.
+- Patch checks now report the patch the device is actually running, so each
+  device is attributed to the right patch.
+- These fixes are in the updater built into Shorebird's Flutter engine, so they
+  apply to releases built with Shorebird's Flutter 3.47.4 or later, the default
+  in CLI 1.6.122.

src/content/changelog/flutter-3-47-2.md

@@ -0,0 +1,21 @@
+---
+title: Flutter 3.47.2 support
+date: 2026-08-28
+version: 1.6.120
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.2 and Dart 3.13.2.
+
+- iOS and macOS: Swift package dependencies are always updated.
+- Windows: fixes hot reload failing on file time truncation.
+- Desktop: `--build-name` and `--build-number` are now forwarded to
+  `version.json`.
+
+```sh
+shorebird release android --flutter-version=3.47.2
+```

src/content/changelog/flutter-3-47-3.md

@@ -0,0 +1,21 @@
+---
+title: Flutter 3.47.3 support
+date: 2026-09-14
+version: 1.6.121
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.3 and Dart 3.13.3.
+
+- Android: fixes license detection for cmdline-tools 23.0 and newer.
+- iOS and macOS: a missing Xcode is now handled instead of failing hard.
+- Windows: fixes Dart cross-compilation.
+- B-series PowerVR GPUs no longer use Vulkan.
+
+```sh
+shorebird release android --flutter-version=3.47.3
+```

src/content/changelog/flutter-3-47-4.md

@@ -0,0 +1,22 @@
+---
+title: Flutter 3.47.4 support
+date: 2026-09-16
+version: 1.6.122
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.4 and Dart 3.13.3.
+
+- iOS: native assets now require iOS 15, raised from iOS 13.
+- iOS: a build now warns when Device Support Symbols are missing, instead of
+  failing partway through.
+- Windows: Application Control and security policy blocks are handled instead of
+  failing the build.
+
+```sh
+shorebird release ios --flutter-version=3.47.4
+```

src/content/changelog/flutter-3-47-5.md

@@ -0,0 +1,20 @@
+---
+title: Flutter 3.47.5 support
+date: 2026-09-21
+version: 1.6.123
+area: Flutter
+type: New
+docLink:
+  label: Flutter versions
+  href: /getting-started/flutter-version/
+---
+
+Shorebird now supports Flutter 3.47.5 and Dart 3.13.4.
+
+- iOS: fixes an occasional crash when debugging on physical iOS 27 devices.
+- Widget Previewer: fixes a crash when re-expanding a preview group.
+- A Dart Development Service startup failure is now handled instead of crashing.
+
+```sh
+shorebird release ios --flutter-version=3.47.5
+```

src/content/changelog/flutter-version-fvm-and-system.md

@@ -0,0 +1,25 @@
+---
+title: Release with the Flutter version you already use
+date: 2026-09-21
+version: 1.6.123
+area: CLI
+type: New
+docLink:
+  label: Match the Flutter version you already use
+  href: /getting-started/flutter-version/#match-the-flutter-version-you-already-use
+---
+
+`--flutter-version` now accepts `fvm` and `system`, so you no longer have to
+look up and repeat your Flutter version number.
+
+- `--flutter-version=fvm` uses the version fvm resolves for your project from
+  its `.fvmrc`. It requires `fvm` on your `PATH`.
+- `--flutter-version=system` uses the version reported by the `flutter` on your
+  `PATH`.
+- Shorebird still builds with its own fork of Flutter at that version, not with
+  your fvm or system install. A version Shorebird doesn't support fails the same
+  way as one you name explicitly.
+
+```sh
+shorebird release android --flutter-version=fvm
+```

src/content/changelog/ios-split-debug-info-dsym.md

@@ -0,0 +1,16 @@
+---
+title: iOS debug symbols now upload to symbol servers
+date: 2026-09-21
+version: 1.6.123
+area: CLI
+type: Fixed
+docLink:
+  label: Release options
+  href: /code-push/release/#options
+---
+
+On iOS, `--split-debug-info` now writes a Mach-O dSYM, so symbol servers ingest
+it and Dart stack traces from production become readable.
+
+- Previously the file was an ELF with no debug ID. Uploads reported finding
+  nothing, while still exiting cleanly.

src/content/changelog/patches-rollback-and-rollforward.md

@@ -0,0 +1,21 @@
+---
+title: Roll patches back and forward from the CLI
+date: 2026-08-28
+version: 1.6.120
+area: CLI
+type: New
+docLink:
+  label: Roll back a patch
+  href: /code-push/rollback/
+---
+
+`shorebird patches rollback` and `shorebird patches rollforward` do the same as
+the Rollback and Roll Forward actions in the Console.
+
+- Both take `--release-version` and `--patch-number`.
+- By default, a patch that is already in the requested state is reported and the
+  command succeeds. Add `--require-change` to exit with an error instead.
+
+```sh
+shorebird patches rollback --release-version 1.0.0+1 --patch-number 1
+```

src/content/changelog/shorebird-apps-commands.md

@@ -0,0 +1,23 @@
+---
+title: Manage apps from the CLI
+date: 2026-09-14
+version: 1.6.121
+area: CLI
+type: New
+docLink:
+  label: Transfer an app
+  href: /account/orgs/#transfer-an-app
+---
+
+New `shorebird apps` commands list, rename, delete, and transfer apps without
+opening the Console.
+
+- `shorebird apps transfer --org-id <id>` moves an app into another
+  organization. Run `shorebird account orgs` to find the id.
+- `shorebird apps rename --name <name>` changes the display name.
+- `shorebird apps delete` has no prompt. Pass `--confirm-name` with the app's
+  current display name to confirm.
+
+```sh
+shorebird apps transfer --app-id <id> --org-id 42
+```