Anthony Correa
08c50299f0
All checks were successful
CI - Docs build check / build-check (push) Successful in 6s
154 lines
4.3 KiB
Markdown
154 lines
4.3 KiB
Markdown
# 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. |