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