Skip to content

RELEASE_PROCESS.md

Latest commit

 

History

History
134 lines (106 loc) · 5.81 KB

RELEASE_PROCESS.md

File metadata and controls

134 lines (106 loc) · 5.81 KB
title Release Process
description Authoritative release process for lightspeedwp/.github: develop → main flow, gating, changelog validation, release PRs, tags, and GitHub Releases.
file_type documentation
version v2.2.1
last_updated 2026-06-01
author LightSpeed Team
maintainer LightSpeed Team
owners
lightspeedwp
tags
release
process
automation

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 and reusable workflow_call.
    • Typed inputs: version, notes_from, scope, provider, dry_run.
    • 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.
    • Provider mode:
      • shell (default): gh/git-backed publication.
      • mcp: GitHub API-backed publication for tag ref, PR, and release.
    • Dry-run mode publishes review artefacts (release-agent.log, release-notes-preview.md) without creating commits/tags/releases.
    • Trigger telemetry records unauthorised trigger attempts (expected 0).
  • 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
node scripts/agents/release.agent.js --scope=minor --provider=mcp --dry-run

MCP provider runtime settings

  • GITHUB_REPOSITORY or RELEASE_REPO_OWNER + RELEASE_REPO_NAME must identify the target repository.
  • GITHUB_TOKEN is required for MCP provider mutation operations.
  • Retry/backoff tuning for MCP API calls:
    • RELEASE_MCP_RETRIES (default 3)
    • RELEASE_MCP_BACKOFF_MS (default 250)
    • RELEASE_MCP_BACKOFF_FACTOR (default 2)

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

Rollback notes

If a release is started but must be rolled back:

  1. Delete the release branch (release/vX.Y.Z) if it should not proceed.
  2. Delete the tag locally and remotely:
    • git tag -d vX.Y.Z
    • git push origin :refs/tags/vX.Y.Z
  3. If a GitHub Release was created, remove it:
    • gh release delete vX.Y.Z --yes
  4. Restore VERSION and CHANGELOG.md to the last known good commit on develop.
  5. Re-run the workflow in dry_run mode first to validate fixes before re-attempting a live release.

Rollback utility supports provider-aware cleanup:

node scripts/workflows/release/rollback.cjs --version=X.Y.Z --provider=shell
node scripts/workflows/release/rollback.cjs --version=X.Y.Z --provider=mcp --dry-run