Release Governance: YYYY.MM.DD Workflow

This Gem defines the canonical Sugartown release workflow. Releases are documentation-first, Python-canonical, and reproducible; WordPress reflects releases but does not define them.

Release ID Convention

• Release ID: YYYY.MM.DD (human-readable, chronological, sortable)

Release Plan (Authoritative Checklist)

• Release ID Assigned: YYYY.MM.DD anchors docs + commits.
• Scope Summary: One sentence describing what changed and why it exists.
• Canonical Data Updated: content_store.py reflects the intended final state.
• CMS Documentation Updated: sugartown-cms/README.md updated for behavioral/architectural changes.
• PRDs Updated: Relevant sugartown-cms/docs/*_PRD_*.md files updated to match reality.
• Theme Documentation Updated: sugartown-pink/README.md updated if rendering/tokens/layout changed.
• Changelog Entry Added: Append a dated entry in content_store.py describing the change (breaking or non-breaking).
• Verification Pass: Smoke test publish, render, archive view, filters, and rollback sanity check.
• Git Commit Created: Single-scoped commit using the release ID.

Per-Release Documentation Workflow

For every release, document changes in the following locations:

• sugartown-cms/README.md
• sugartown-cms/docs/*_PRD_*.md
• sugartown-pink/README.md
• content_store.py (changelog section)
• git commit -m "release: YYYY.MM.DD – concise descriptor"

Commit Message Pattern

Operating Principles

• Documentation-first: If it shipped, it’s documented.
• Python-canonical: The system of record lives in code and docs, not WP edits.
• Reproducible: A release should be reconstructable from repo state + artifacts.
• Low ceremony, high traceability: Minimal steps, maximal clarity.

Versioning & Changelog Rules (Locked)

• Calendar versioning: Use vYYYY.MM.DD (one version per release day).
• No SemVer: Do not use major/minor/patch semantics for Sugartown releases.
• Single source of truth: CHANGELOG.md is authoritative for release history.
• Auto-import: content_store.py imports changelog entries on publish; do not maintain manual changelog content in code.
• Normalization rule: If an older changelog entry is touched, normalize it to the canonical format.

Canonical CHANGELOG Entry Format

Changelog Lint Checklist (Required)

Fail the release review if any check below does not pass.

File & Format

• Changelog update exists in CHANGELOG.md
• Entry is written in Markdown (no HTML)
• No changelog content is written directly to content_store.py

Versioning

• Version follows calendar format: vYYYY.MM.DD
• Version date matches the release date
• No semantic versioning (major/minor/patch)
• Only one version entry per release date

Structure

• Entry begins with: ## vYYYY.MM.DD: <short, factual descriptor>
• Includes Date and Status lines
• Uses emoji-labeled sections (e.g., 🎨, ⚙️, 🧩)
• Bullets are concise and factual
• Entry ends with a horizontal rule: ---

Content Integrity

• Bullets reflect only shipped work
• No speculative or future-tense language
• No duplicated bullets across sections
• No marketing language or narrative prose

Release Checklist Updates (Replace Changelog Items)

• Replace: “Changelog Entry Added: Append a dated entry in content_store.py …”
• With: “Changelog Entry Added: Append a canonical entry to CHANGELOG.md (Markdown); imported automatically on publish.”
• Replace: “content_store.py (changelog section)” in the per-release workflow list
• With: “CHANGELOG.md (canonical entry; auto-imported on publish)”