cmba-bylaws/RELEASING.md

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.