docs: add release policy and notes

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    name: Check, build, and verify generated documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - name: Install Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type and content checks
+        run: npm run check
+
+      - name: Build site
+        run: npm run build
+
+      - name: Verify generated AI outputs and release pages
+        run: |
+          test -f public/llms.txt
+          test -f public/llms-full.txt
+          test -d public/raw
+          test -f dist/index.html
+          test -f dist/releases/index.html
+          test -f dist/releases/release-notes/index.html
+          grep -q "https://docs.database.pizza/raw/releases/index.md" public/llms.txt
+          grep -q "https://docs.database.pizza/raw/releases/release-notes.md" public/llms.txt
+          grep -q "Canonical URL: https://docs.database.pizza/releases/" public/llms-full.txt
+          grep -q "Canonical URL: https://docs.database.pizza/releases/release-notes/" public/llms-full.txt

astro.config.mjs

@@ -123,6 +123,13 @@ export default defineConfig({
             { label: 'Limits & quotas', link: '/guides/limits/' },
           ],
         },
+        {
+          label: 'Releases',
+          items: [
+            { label: 'Release policy', link: '/releases/' },
+            { label: 'Release notes', link: '/releases/release-notes/' },
+          ],
+        },
         {
           label: 'For AI Tools',
           items: [

scripts/generate-ai.mjs

@@ -50,7 +50,7 @@ for (const file of files) {
 
   await mkdir(path.dirname(rawPath), { recursive: true });
   await writeFile(rawPath, source);
-  pages.push({ body, description, route, source, title });
+  pages.push({ body, description, rawRelative: relative, route, source, title });
 }
 
 const index = [
@@ -62,7 +62,7 @@ const index = [
   '',
   '## Documentation',
   '',
-  ...pages.map(({ description, route, title }) => `- [${title || route}](https://docs.database.pizza/raw${route === '/' ? '/index.md' : `${route.slice(0, -1)}.md`})${description ? `: ${description}` : ''}`),
+  ...pages.map(({ description, rawRelative, title }) => `- [${title || rawRelative}](https://docs.database.pizza/raw/${rawRelative})${description ? `: ${description}` : ''}`),
   '',
   '## Important context',
   '',

src/content/docs/releases/index.md

@@ -0,0 +1,120 @@
+---
+title: Release policy
+description: How database.pizza versions PizzaKV, PizzaSQL, and the managed app, and how paired engine compatibility is defined.
+---
+
+database.pizza ships three independently versioned components that are released
+together as one or more validated **pairs**:
+
+| Component | Repository | Versioned artifact |
+| --- | --- | --- |
+| PizzaKV | `pizzakv` | `pizzakv` engine binary |
+| PizzaSQL | `pizzasql` | `pizzasql` engine binary |
+| database.pizza app | `app.database.pizza` | `dbpizza` orchestrator and API |
+
+Every component follows [Semantic Versioning 2.0.0](https://semver.org/). A
+release tag in a component repository is `vMAJOR.MINOR.PATCH` (for example
+`v0.1.0`). Pre-release builds append a hyphenated identifier
+(`v0.2.0-rc.1`); build metadata is never used for ordering.
+
+## What each number means
+
+- **MAJOR** changes when the component removes or changes behavior that callers
+  or stored data depend on. For PizzaKV this includes the on-disk `PKVDB`
+  storage format; for PizzaSQL it includes SQL semantics and the
+  PostgreSQL-compatible wire behavior.
+- **MINOR** adds backward-compatible functionality. A minor PizzaSQL release may
+  require a newer PizzaKV within the same supported pair window.
+- **PATCH** is a backward-compatible fix with no change to storage or wire
+  formats.
+
+The storage format is tracked separately from the version string as an integer.
+A storage format never decreases, and a format increase is a migration, not a
+refactor. Release notes state the format explicitly.
+
+## Paired engine compatibility
+
+PizzaSQL and PizzaKV are **not** independently selectable. A managed database
+always runs a complete, validated `PizzaKV + PizzaSQL` pair. The control plane
+(`app.database.pizza`) stores each pair as an immutable release with:
+
+- both component versions and source commits,
+- the artifact filename and `sha256` checksum for each component,
+- `storage_format` and `protocol_version`,
+- `min_upgradable_from`, the oldest storage format that may upgrade directly.
+
+An upgrade moves a tenant from one complete pair to another. It never mixes
+components across pairs. When a new pair raises `storage_format`, only tenants at
+or above `min_upgradable_from` are eligible; older tenants must first move
+through an intermediate pair.
+
+### Supported pair window
+
+A pair is supported when its PizzaSQL and PizzaKV versions are the ones recorded
+in the same manifest entry. The supported upgrade path is:
+
+1. the current stable pair,
+2. the previous stable pair, and
+3. one active `beta` or `canary` pair for pre-release validation.
+
+Pairs outside that window are not supported upgrade sources, even if their
+component versions look compatible.
+
+## Release channels
+
+Each pair is published on exactly one channel:
+
+- `canary` — pre-merge or early validation builds. Not for production tenants.
+- `beta` — feature-complete candidates with a migration plan.
+- `stable` — promoted, reviewed pairs that tenants may adopt or upgrade to.
+
+A pair also has a promotion state (`draft`, `candidate`, `stable`, `deprecated`,
+`revoked`). Draft, deprecated, and revoked pairs are never valid upgrade targets.
+
+## The paired manifest
+
+Every pair is described by one machine-readable manifest that mirrors the
+control plane's `EngineRelease` contract. The JSON Schema lives at
+`app.database.pizza/backend/internal/releases/release-manifest.schema.json`, and
+the template below is validated against the same rules by
+`make test` in that repository.
+
+```json
+{
+  "id": "stable-0.1.0",
+  "version": "0.1.0",
+  "channel": "stable",
+  "promotion_state": "candidate",
+  "pizzakv_version": "0.1.0",
+  "pizzasql_version": "0.1.0",
+  "pizzakv_commit": "0000000000000000000000000000000000000000",
+  "pizzasql_commit": "0000000000000000000000000000000000000000",
+  "pizzakv_artifact": "pizzakv-0.1.0-freebsd-arm64",
+  "pizzasql_artifact": "pizzasql-0.1.0-freebsd-arm64",
+  "pizzakv_checksum": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "pizzasql_checksum": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+  "storage_format": 1,
+  "protocol_version": 1,
+  "min_upgradable_from": 0,
+  "release_notes": "Initial paired PizzaKV + PizzaSQL release."
+}
+```
+
+- `version` is the pair's SemVer identity; both components may use their own
+  component versions in `pizzakv_version` and `pizzasql_version`.
+- `checksum` values are `sha256:` followed by 64 lowercase hex characters and
+  cover the exact uploaded artifact.
+- `min_upgradable_from` is `0` when any older storage format may upgrade
+  directly.
+
+## Artifacts
+
+Release artifacts are named for their target platform, for example
+`pizzakv-0.1.0-freebsd-arm64` and `pizzasql-0.1.0-freebsd-arm64`. Every build
+publishes a `SHA256SUMS` file next to the binaries. FreeBSD ARM64 is the primary
+production target; Linux and FreeBSD AMD64 builds are used for verification and
+local development.
+
+The CI workflows in each repository build and test their artifacts and validate
+the manifest contract, but they do not deploy or publish. Promotion to a
+channel is a separate, reviewed operator action.

src/content/docs/releases/release-notes.md

@@ -0,0 +1,127 @@
+---
+title: Release notes
+description: The canonical structure for database.pizza release notes, with a copy-ready template.
+---
+
+Release notes are the human-readable companion to a release manifest. Every
+promoted pair and every app release has one note. This page defines the
+structure so notes stay comparable across releases and channels.
+
+## Where notes live
+
+- The short operator summary is stored on the release pair itself in the
+  manifest's `release_notes` field. It must fit in one or two sentences.
+- The full note is a Markdown page under `docs.database.pizza` and is the
+  canonical, linkable record. Long-form detail, migration guidance, and known
+  issues belong here, not in the manifest.
+
+A note names the exact components and commits it describes. If the note covers a
+paired engine release, link the pair version from the release policy page.
+
+## Required sections
+
+Use these sections in this order. Omit a section only when it has nothing to
+say, except **Summary**, **Components**, and **Compatibility**, which are always
+present.
+
+| Section | Contents |
+| --- | --- |
+| Summary | One paragraph: what changed and who should care. |
+| Components | Table of each component, its version, and its source commit. |
+| Compatibility | `storage_format`, `protocol_version`, and `min_upgradable_from`, plus required intermediate pairs. |
+| Added | New behavior and features. |
+| Changed | Behavior changes that are backward compatible. |
+| Fixed | Bug fixes. |
+| Security | Security-relevant fixes and their impact. |
+| Deprecated | Features or formats scheduled for removal and the replacement. |
+| Upgrade notes | Ordered operator steps, snapshots, and rollback expectations. |
+| Verification | Artifact names and `sha256` checksums, or a link to `SHA256SUMS`. |
+| Known issues | Open problems and workarounds. |
+
+Change entries use the conventional-commit vocabulary where it helps: `feat`,
+`fix`, `perf`, `refactor`, and so on. Write for an operator deciding whether to
+upgrade, not for a commit log.
+
+## Template
+
+Copy this block for a new note and replace the placeholders.
+
+```markdown
+# <pair version / app version> — <YYYY-MM-DD>
+
+## Summary
+
+<What changed, and who should act on it.>
+
+## Components
+
+| Component | Version | Commit |
+| --- | --- | --- |
+| PizzaKV | <version> | `<commit>` |
+| PizzaSQL | <version> | `<commit>` |
+| database.pizza app | <version or n/a> | `<commit or n/a>` |
+
+## Compatibility
+
+- Storage format: `<n>` (previous: `<n>`)
+- Protocol version: `<n>`
+- Minimum upgradable from: `<storage format>` (or any)
+- Required intermediate pairs: <none, or list them>
+
+## Added
+
+- <entry>
+
+## Changed
+
+- <entry>
+
+## Fixed
+
+- <entry>
+
+## Security
+
+- <entry>
+
+## Deprecated
+
+- <entry>
+
+## Upgrade notes
+
+1. <operator step, including snapshot requirements>
+
+## Verification
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `pizzakv-<version>-freebsd-arm64` | `<sha256>` |
+| `pizzasql-<version>-freebsd-arm64` | `<sha256>` |
+
+## Known issues
+
+- <entry>
+```
+
+## Initial release
+
+### 0.1.0 — initial paired release
+
+**Summary.** First tracked SemVer identity for PizzaKV, PizzaSQL, and the
+managed app. No production tenants are upgraded by this note; it establishes the
+versioning and manifest convention.
+
+**Components.**
+
+| Component | Version | Commit |
+| --- | --- | --- |
+| PizzaKV | 0.1.0 | tracked in the release manifest |
+| PizzaSQL | 0.1.0 | tracked in the release manifest |
+| database.pizza app | 0.1.0 | reported by `app-api -version` |
+
+**Compatibility.** Storage format `1`, protocol version `1`,
+`min_upgradable_from` `0`. No intermediate pairs are required.
+
+**Verification.** Artifacts and checksums are recorded in the release manifest
+described in the [release policy](/releases/).