Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
132 lines (103 loc) · 5.68 KB

RELEASE_PROCESS.md

File metadata and controls

132 lines (103 loc) · 5.68 KB
Raw
Error in user YAML: (<unknown>): did not find expected key while parsing a block mapping at line 1 column 1
---
version: "v2.1.0"
last_updated: "2026-09-22""
owners: ["lightspeedwp"]
file_type: "process-guide"
category: "release-management"
description: "Authoritative release process for lightspeedwp/.github: develop → main flow, gating, changelog validation, release PRs, tags, and GitHub Releases."
references:
  - path: "../agents/release.agent.md"
    description: "Release agent specification"
  - path: "../scripts/agents/release.agent.js"
    description: "Release automation implementation"
  - path: "../.github/workflows/release.yml"
    description: "Release workflow (develop → main)"
  - path: "../.github/workflows/changelog.yml"
    description: "Changelog validation on every PR"
  - path: "../.schemas/changelog.schema.json"
    description: "Keep a Changelog schema"
  - path: "../scripts/validation/validate-changelog.cjs"
    description: "Schema validation script"
  - path: "../CHANGELOG.md"
    description: "Keep a Changelog source of truth"
---

Release Process (develop → main)

Goal: ship reliable releases from develop to main with validated changelog entries, a release PR, tags, and GitHub Releases generated by release.agent.js.

Branch flow

  1. Work on develop.
  2. When ready, run the release agent (default scope patch).
  3. Agent creates release/vX.Y.Z, bumps VERSION, updates CHANGELOG.md, tags vX.Y.Z, pushes branch + tag, and opens a PR to main.
  4. Merge PR to main after gates are green.
  5. GitHub Release is published with compiled notes (sections, highlights, contributors).

Automation & gates

  • Changelog validation (.github/workflows/changelog.yml)
    • Runs on every PR (all branches) and on develop pushes to ensure:
      • CHANGELOG.md conforms to changelog.schema.json.
      • Unreleased section exists and is populated.
  • Release workflow (.github/workflows/release.yml)
    • Manual workflow_dispatch (scope input, default patch).
    • Hard gate on lint (linting.yml reuse).
    • Runs schema + unreleased validation before invoking release.agent.js.
    • Uses release.agent.js (ESM) to create release branch, PR → main, tag, and GitHub Release with compiled notes.
  • Required checks before merging release PR
    • Lint/test green.
    • Changelog validation green.
    • Version bump and dated changelog entry present.

Semantic versioning & scope

  • Single source of truth: VERSION file.
  • Scope values: patch (default), minor, major.
  • Agent command examples:
node scripts/agents/release.agent.js --scope=patch
node scripts/agents/release.agent.js --scope=minor --dry-run

Pre-release checklist (run on develop)

  • CHANGELOG.md has unreleased entries and passes schema validation (changelog.yml).
  • VERSION matches intended bump source.
  • Lint/tests green.
  • Agent/workflow alignment: release.agent.js, release.agent.md, release.yml, changelog.yml.
  • Documentation current (links valid, branch flow accurate).
  • No uncommitted changes in working tree.

Release execution (agent-driven)

  1. Validate readiness: VERSION + changelog schema + unreleased content; warn if dirty working tree.
  2. Create branch: release/vX.Y.Z from develop.
  3. Bump & document: update VERSION; roll CHANGELOG.md [Unreleased] to [X.Y.Z] - YYYY-MM-DD.
  4. Commit & push: commit release bump; push branch and tags.
  5. PR to main: agent opens PR release/vX.Y.Z → main.
  6. Tag & release: annotated tag vX.Y.Z; GitHub Release with notes compiled from changelog + merged PRs (highlights, breaking changes, contributors).
  7. Post-merge: verify no drift between develop and main; prep next cycle if needed.

Changelog governance

  • Format: Keep a Changelog.
  • Schema: ../.schemas/changelog.schema.json enforced by:
    • scripts/validation/validate-changelog.cjs
    • scripts/agents/includes/changelogUtils.cjs --validate/--unreleased
  • Requirements:
    • [Unreleased] section must exist and contain entries before release.
    • Sections allowed: Added, Changed, Deprecated, Removed, Fixed, Security, Documentation, Performance.

Release notes generation

release.agent.js compiles notes using:

  • Changelog sections (ordered).
  • Highlights (prioritising Added/Changed/Security).
  • Breaking changes callout.
  • Contributors from merged PRs between previous tag and new tag.
  • Full changelog compare link.

Troubleshooting

  • Changelog validation fails: run node scripts/validation/validate-changelog.cjs CHANGELOG.md and fix schema violations/empty sections.
  • No unreleased changes: add entries under [Unreleased] before running release agent.
  • PR not created: ensure gh CLI and GITHUB_TOKEN available; otherwise create PR from release/vX.Y.Z → main manually.
  • Tag conflicts: delete or move existing tag before rerunning; ensure working tree clean.

This document is authoritative for the release flow, gating, and automation alignment in lightspeedwp/.github.

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP Contact

Have questions? Ping us on GitHub! 🐙 Made with 💚 by LightSpeedWP