# 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.