Skip to main content

ADR 0063: Enforce Conventional Commits In The STAGE Repository

Status: Accepted

Date: 2026-08-01

The commit-policy decision remains current. Its release-proposal deferral is resolved by ADR 0064.

Context​

ADR 0057 made Conventional Commits optional project guidance and kept release automation proposal-only. STAGE's own repository continued to use consistent imperative subjects without a machine-readable change type.

The owner now wants commit metadata that can support dependable changelog and release proposals. That creates a named consumer for the convention, but it does not resolve which files a release proposal may update or transfer release approval to automation.

GitHub currently reports that protected branches and repository rulesets are unavailable for this private repository under its account plan. Hosted checks can therefore detect a nonconforming direct push but cannot prevent that push from landing until the repository gains branch-rule support.

Decision​

Require Conventional Commit syntax for new commits in this STAGE repository from this decision onward. This is a repository-maintainer policy, not a new universal requirement for projects adopting STAGE.

Enforce the policy at the available boundaries:

  • root maintainer dependencies pin @commitlint/cli and @commitlint/config-conventional;
  • a Husky commit-msg hook rejects invalid local commit messages after npm ci installs the repository tooling;
  • the hosted quality workflow checks every new commit in a push;
  • pull requests check both their commits and title so a squash merge produces a conforming mainline subject; and
  • repository merge settings allow squash merges only and delete merged branches automatically.

Use the conventional type to classify the change, not its release authority. A feat does not independently approve a minor release, a fix does not prove compatibility, and ! or a BREAKING CHANGE footer does not authorize a breaking release.

Do not rewrite existing history. The adoption commit and later commits form the machine-readable boundary.

Keep Release Please or equivalent release-proposal automation disabled until a separate decision names:

  • the authoritative version source and SemVer mapping;
  • every synchronized package, site, specification, compatibility, and release record path;
  • the human review required before creating a tag or GitHub release; and
  • the explicit boundary preventing automatic plugin or source publication.

ADR 0064 now supplies that separate decision without changing this commit policy.

Consequences​

  • New history has structured change types suitable for future release proposals and changelog grouping.
  • Local setup includes a small root Node maintainer-tool surface in addition to the independent Docusaurus package.
  • Pull-request titles become part of the integration contract because the repository uses squash merges.
  • Hooks remain bypassable and hosted checks remain post-push on unprotected main; full remote prevention requires a GitHub plan or visibility change that supports branch rules.
  • Release versions, release notes, tags, plugin refresh, and public source or package publication remain human-approved operations.
Last updated on