Update RELEASING.md

.github/workflows/ci-docs.yml

@@ -0,0 +1,49 @@
+name: CI - Docs build check
+
+on:
+  pull_request:
+    branches: [release-candidate]
+  push:
+    branches: [release-candidate]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }} 
+
+jobs:
+  build-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        # if: false
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          # cache: "pip"
+          # cache-dependency-path: mkdocs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install -r mkdocs/requirements.txt
+
+      - name: MkDocs build
+        run: |
+          set -euo pipefail
+          echo "MKDOCS_STRICT: $MKDOCS_STRICT"
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d $RUNNER_TEMP/
+          
+ 

.github/workflows/deploy-main-pages.yml

@@ -0,0 +1,78 @@
+name: Deploy main to GitHub Pages (stable)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+
+jobs:
+  deploy-main-pages:
+    if: ${{ env.ENABLE_DEPLOY == 'true' && env.ACT != 'true' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (main)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: mkdocs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install -r mkdocs/requirements.txt
+
+      - name: Build (MKDOCS_STRICT)
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d site_build
+
+      - name: Checkout gh-pages branch
+        run: |
+          set -euo pipefail
+          git fetch origin gh-pages:gh-pages || true
+          if git show-ref --verify --quiet refs/heads/gh-pages; then
+            git switch gh-pages
+          else
+            git switch --orphan gh-pages
+            rm -rf ./*
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git commit --allow-empty -m "Initialize gh-pages"
+          fi
+
+      - name: Publish stable site to root (preserve rc/)
+        run: |
+          set -euo pipefail
+
+          mkdir -p _keep
+          if [ -d rc ]; then cp -a rc _keep/; fi
+
+          rm -rf ./*
+          if [ -d _keep/rc ]; then mv _keep/rc ./rc; fi
+          rm -rf _keep
+
+          cp -a ../site_build/. .
+
+          git add -A
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Deploy stable site from main" || echo "No changes to commit"
+          git push origin gh-pages

.github/workflows/deploy-rc-pages.yml

@@ -0,0 +1,91 @@
+name: Deploy RC preview to GitHub Pages
+
+on:
+  push:
+    tags:
+      - "v*-rc.*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+
+jobs:
+  deploy-rc-pages:
+    if: ${{ env.ENABLE_DEPLOY == 'true' && env.CI_PROVIDER == 'github' && env.ACT != 'true' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (tag)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure tag commit is on release-candidate
+        run: |
+          set -euo pipefail
+          git fetch origin release-candidate:refs/remotes/origin/release-candidate
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/release-candidate"; then
+            echo "ERROR: Tagged commit ${GITHUB_SHA} is not on release-candidate. Refusing RC deploy."
+            exit 1
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: mkdocs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install -r mkdocs/requirements.txt
+
+      - name: Build (MKDOCS_STRICT)
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d site_build
+
+      - name: Checkout gh-pages branch
+        run: |
+          set -euo pipefail
+          git fetch origin gh-pages:gh-pages || true
+          if git show-ref --verify --quiet refs/heads/gh-pages; then
+            git switch gh-pages
+          else
+            git switch --orphan gh-pages
+            rm -rf ./*
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git commit --allow-empty -m "Initialize gh-pages"
+          fi
+
+      - name: Publish RC preview under /rc/<tag>/
+        run: |
+          set -euo pipefail
+          REF="${{ github.ref_name }}"
+          mkdir -p "rc/${REF}"
+          rm -rf "rc/${REF:?}/"* || true
+          cp -a ../site_build/. "rc/${REF}/"
+
+          mkdir -p rc
+          if [ ! -f rc/index.html ]; then
+            cat > rc/index.html << 'EOF'
+<!doctype html><meta charset="utf-8"><title>RC Previews</title>
+<h1>RC Previews</h1><p>Browse rc/&lt;tag&gt;/</p>
+EOF
+          fi
+
+          git add -A
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Deploy RC preview ${REF}" || echo "No changes to commit"
+          git push origin gh-pages

.github/workflows/prerelease-docs.yml

@@ -0,0 +1,88 @@
+name: Pre-release - Build and publish docs
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  
+env:
+  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }}
+
+jobs:
+  prerelease:
+    if: >
+      startsWith(github.ref_name, 'v')
+      && contains(github.ref_name, '-rc')}}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout (tag)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure tag commit is on release-candidate
+        run: |
+          set -euo pipefail
+          git fetch origin release-candidate:refs/remotes/origin/release-candidate
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/release-candidate"; then
+            echo "ERROR: Tagged commit ${GITHUB_SHA} is not on release-candidate. Refusing prerelease."
+            exit 1
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: mkdocs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install -r mkdocs/requirements.txt
+
+      - name: CI gate (MKDOCS_STRICT)
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d $RUNNER_TEMP
+
+      - name: Build artifact (non-strict)
+        env:
+          MKDOCS_STRICT: "false"
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          mkdir -p "${RUNNER_TEMP}/dist"
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d "${RUNNER_TEMP}/dist/${{ github.ref_name }}"
+
+      - name: Zip artifact
+        run: |
+          set -euo pipefail
+          cd "${RUNNER_TEMP}/dist"
+          zip -r "${{ github.ref_name }}.zip" "./${{ github.ref_name }}"
+
+      - name: Publish prerelease (skip on act)
+        if: ${{ env.ENABLE_RELEASE == 'true' && env.ACT != 'true' }}
+        uses: softprops/action-gh-release@v2
+        with:
+          prerelease: true
+          files: |
+            ${{ runner.temp }}/dist/${{ github.ref_name }}.zip

.github/workflows/release-docs.yml

@@ -1,29 +1,86 @@
-name: Build and publish CMBA rulebooks (Gitea)
+name: Release - Build and publish docs
 
 on:
   push:
     tags:
       - "v*"
 
+permissions:
+  contents: write
+  
+env:
+  MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }}
+
 jobs:
-  build-release:
+  release:
+    if: >
+      startsWith(github.ref_name, 'v')
+      && !contains(github.ref_name, '-rc')}}
     runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - name: Checkout (tag)
+        uses: actions/checkout@v4
         with:
-          python-version: '3.13' 
-      - name: Install Dependencies
-        run: pip install -r mkdocs/requirements.txt
-      - name: Build Docs
+          fetch-depth: 0
+
+      - name: Ensure tag commit is on main
         run: |
-          mkdir $RUNNER_TEMP/dist
-          mkdocs build -f mkdocs/mkdocs.yml -d $RUNNER_TEMP/${{ github.ref_name }}
-          zip -r $RUNNER_TEMP/dist/${{ github.ref_name }}.zip $RUNNER_TEMP/${{ github.ref_name }}
-      - name: Release
-        if: ${{ !env.ACT }}
+          set -euo pipefail
+          git fetch origin main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/main"; then
+            echo "ERROR: Tagged commit ${GITHUB_SHA} is not on main. Refusing release."
+            exit 1
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: mkdocs/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          set -euo pipefail
+          pip install -r mkdocs/requirements.txt
+
+      - name: CI gate (MKDOCS_STRICT)
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d $RUNNER_TEMP
+
+      - name: Build artifact (non-strict)
+        env:
+          MKDOCS_STRICT: "false"
+        run: |
+          set -euo pipefail
+
+          MKDOCS_STRICT="${MKDOCS_STRICT:-true}"
+          STRICT_FLAG=""
+          if [ "${MKDOCS_STRICT}" = "true" ]; then
+            STRICT_FLAG="--strict"
+          fi
+
+          mkdir -p "${RUNNER_TEMP}/dist"
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d "${RUNNER_TEMP}/dist/${{ github.ref_name }}"
+
+      - name: Zip artifact
+        run: |
+          set -euo pipefail
+          cd "${RUNNER_TEMP}/dist"
+          zip -r "${{ github.ref_name }}.zip" "./${{ github.ref_name }}"
+
+      - name: Publish release (skip on act; allowed on gitea)
+        if: ${{ env.ENABLE_RELEASE == 'true' && env.ACT != 'true' }}
         uses: softprops/action-gh-release@v2
         with:
           files: |
-            $RUNNER_TEMP/dist/*.zip
+            ${{ runner.temp }}/dist/${{ github.ref_name }}.zip

RELEASING.md

@@ -0,0 +1,154 @@
+# Technical Release & Automation Notes
+
+> ⚠️ This document describes **technical automation and versioning**
+> used by the repository (CI/CD, tags, and deployments).
+>
+> It does **not** define:
+> - the organizational process for approving bylaws or constitutional changes
+> - who is authorized to make those changes
+> - when changes are considered “official” by the organization
+>
+> Those governance decisions within the organization’s constitution.
+
+This document exists solely to explain how **Git version tags, automated checks,
+and publishing workflows** are wired together so that future maintainers
+(dozens of months from now) do not accidentally trigger or break them.
+
+# Release & CI Process
+
+This repository uses a deliberately strict and explicit release process.
+It exists to prevent accidental releases, deployments, or CI runs.
+
+If you are changing tags, workflows, or branches, read this first.
+
+—
+
+## Branches
+
+- `development`
+  - Day-to-day work
+  - No releases or deployments happen from this branch
+
+- `release-candidate`
+  - Stabilization branch
+  - CI runs here with strict checks
+  - Release candidates are tagged from here
+
+- `main`
+  - Stable, releasable state
+  - Final releases are tagged from here
+  - Stable GitHub Pages content is deployed from here
+
+—
+
+## Tag Naming Policy
+
+### Final Releases
+- Tags **must** start with `v`
+- Tags **must not** contain `-rc`
+
+Examples:
+- `v2026.1.0`
+- `v1.0.0`
+
+### Release Candidates
+- Tags **must** start with `v`
+- Tags **must** contain `-rc`
+
+Examples:
+- `v2026.1.0-rc.1`
+- `v1.0.0-rc.2`
+
+This naming policy is intentional and is enforced by CI.
+
+—
+
+## CI and Workflows Overview
+
+| Workflow          | Trigger                          | Purpose                                |
+|-------------------|----------------------------------|----------------------------------------|
+| CI Docs           | Push / PR to `release-candidate` | Strict MkDocs build validation         |
+| Prerelease        | Tag `v*` containing `-rc`        | Build and publish prerelease artifacts |
+| Release           | Tag `v*` not containing `-rc`    | Build and publish final release        |
+| RC Pages Deploy   | RC tag                           | Publish preview docs under `/rc//`     |
+| Main Pages Deploy | Push to `main`                   | Publish stable docs to root            |
+
+—
+
+## Why both release workflows trigger on `v*`
+
+GitHub Actions does **not** support negative tag filters.
+Because of this:
+
+- Both release and prerelease workflows trigger on `v*`
+- Each workflow uses a job-level `if:` to decide whether it should run
+
+This ensures:
+- Symmetry between workflows
+- Clear, explicit logic
+- No reliance on fragile glob patterns
+
+—
+
+## Safety Checks (Intentional Redundancy)
+
+Releases and deployments are guarded by **multiple independent checks**:
+
+1. **Tag name checks**
+   - Release vs prerelease is decided by presence of `-rc`
+
+2. **Branch ancestry checks**
+   - Final releases must be reachable from `main`
+   - RC releases must be reachable from `release-candidate`
+
+3. **Strict MkDocs CI**
+   - Controlled by `MKDOCS_STRICT` (defaults to true)
+
+4. **Environment guards**
+   - Releases are skipped when running under `act`
+   - Deployments only run on GitHub, never on Gitea or act
+
+This redundancy is intentional.
+
+—
+
+## Environment Variables
+
+These variables control CI and release behavior:
+
+| Variable          | Purpose                             |
+|-------------------|-------------------------------------|
+| `MKDOCS_STRICT`   | Enable/disable strict MkDocs builds |
+| `ENABLE_RELEASE`  | Master switch for releases          |
+| `ENABLE_DEPLOY`   | Master switch for deployments       |
+| `CI_PROVIDER`     | `github`, `gitea`, or `act`         |
+| Main Pages Deploy | Push to `main`                      |
+
+Defaults are defined in repository settings.
+
+—
+
+## Common Mistakes (and What Happens)
+
+- Tagging `v2026.1.0` on a non-`main` commit  
+  → Release workflow runs but fails early with a clear error
+
+- Tagging `v2026.1.0-rc.1` on `main`  
+  → Prerelease workflow runs but branch check fails
+
+- Running workflows locally with `act`  
+  → Builds run, but no release or deploy occurs
+
+—
+
+## Changing This Process
+
+If you change:
+- Tag patterns
+- Branch names
+- Workflow triggers
+- CI guard logic
+
+Update this document **and** the workflows together.
+
+This process is designed to be boring, explicit, and safe.