From ef8fd7eae60caca62b22e27240e5ed2d512a9808 Mon Sep 17 00:00:00 2001
From: Tony <anthony@correa.co>
Date: Mon, 19 Jan 2026 13:41:55 -0600
Subject: [PATCH] add releasing, change ci build check directory

---
 .github/workflows/ci-docs.yml |   2 +-
 RELEASING.md                  | 153 ++++++++++++++++++++++++++++++++++
 2 files changed, 154 insertions(+), 1 deletion(-)
 create mode 100644 RELEASING.md

diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
index e191ec8..7bfeded 100644
--- a/.github/workflows/ci-docs.yml
+++ b/.github/workflows/ci-docs.yml
@@ -40,4 +40,4 @@ jobs:
             STRICT_FLAG="--strict"
           fi
 
-          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml
\ No newline at end of file
+          OFFLINE=true mkdocs build ${STRICT_FLAG} -f mkdocs/mkdocs.yml -d $RUNNER.TEMP/
\ No newline at end of file
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 0000000..113b814
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,153 @@
+# 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/<tag>/` |
+| 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` |
+
+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.
\ No newline at end of file