Skip to content

ADR 004: Adopt semantic-release

  • Status: Accepted
  • Date: 2026-02-05
  • Author: Victoria Cheng

Context and Problem Statement

In ADR 001, a lightweight, shell-based approach was implemented to automate releases using Conventional Commits. This served as a successful proof-of-concept for "Zero-Touch Releases."

However, as the platform matures into "Chapter 4: Autonomous Workflows," the custom implementation has limitations:

  1. Lack of Changelogs: Tagging is handled, but human-readable changelogs are not generated.
  2. Maintenance Overhead: Custom shell logic must be manually updated to handle edge cases or new release requirements.
  3. Limited Extensibility: Features like GitHub Release notes or automated package publishing require significant manual scripting.

A standardized, industry-standard tool is required to handle the full release lifecycle.

Decision Outcome

release-please will be adopted (encapsulated within a local semantic-release action) to automate the entire release process. This provides a "Human in the Loop" safety gate where the machine prepares the release (versioning and changelog) in a Pull Request, and a human triggers the release by merging it.

Implementation Details

  • Tooling: Use googleapis/release-please-action wrapped in a local ./semantic-release composite action.
  • Configuration: Use release-please-config.json and .release-please-manifest.json at the repository root.
  • Trigger: Runs on push to the main branch, triggered by merged Pull Requests that follow the Conventional Commits specification (enforced by ADR 003).
  • Zero Node.js Dependency: Implementation requires no package.json, npx, or Node.js runtime environment in the repository.

Alternatives Considered but Rejected

  • semantic-release (Node.js): Rejected due to the requirement for a package.json and a Node.js runtime environment.
  • go-semantic-release: Rejected because it lacks the "Human in the Loop" Pull Request gate and carries a higher maintenance risk compared to the Google-maintained release-please.
  • Enhance Custom Shell Script: Rejected because re-inventing features like changelog parsing and GitHub API integration is a "non-core" activity that adds technical debt.

Consequences

Positive

  • Human in the Loop: A mandatory human checkpoint (merging the Release PR) ensures high-quality releases.
  • Automated Changelogs: Contributors and users get clear, automated visibility into changes.
  • No Node.js Overhead: Maintains a clean environment without JS-specific metadata files.
  • Industry Standard: Uses a robust, Google-maintained tool for long-term stability.

Negative

  • Two-Step Merge: Requires a human to merge both the feature/fix PR and the subsequent Release PR.
  • Configuration Complexity: Requires managing release-please specific manifest files.

Verification

  • [x] Action Encapsulation: Create the semantic-release/ action directory.
  • [x] Dry Run: Verify the action in a CI dry-run mode via .github/workflows/test-actions.yml.
  • [x] CI Integration: Integrate the action into the primary release workflow.
  • [x] Changelog: Confirm CHANGELOG.md is correctly generated and includes categorized entries.