Skip to content

docs: correct the release docs to match what the workflows now do - #9

Merged
StoneyJackson merged 1 commit into
mainfrom
docs/accurate-release-docs
Jul 27, 2026
Merged

docs: correct the release docs to match what the workflows now do#9
StoneyJackson merged 1 commit into
mainfrom
docs/accurate-release-docs

Conversation

@StoneyJackson

Copy link
Copy Markdown
Member

Five separate inaccuracies, all of which would mislead a maintainer:

  • Both README and the maintainer guide claimed feat!: produces a major. It does not. semantic-release's Angular preset ignores the ! shorthand, so feat!: alone yields no release while CI stays green. The BREAKING CHANGE footer is what does the work, which also makes merge commits safer than squash for a major.
  • The release flow omitted the plan job and described build as unconditional. Builds now happen only when a release is actually coming.
  • The weekly bump was described as touching only the two image configs and explicitly "not" the feature. It updates five files, bumps the feature's own version, derives the release type from plcc-ng's major, and retags image references on a major.
  • Bootstrap said to require "the CI status check". Requiring job names is what hung PRs in both repos today; require ci-gate and only ci-gate.
  • Housekeeping implied candidates accumulate on every merge; infra-only merges no longer build at all.

Neither commit type releases, so this changes nothing about versioning.

Five separate inaccuracies, all of which would mislead a maintainer:

- Both README and the maintainer guide claimed `feat!:` produces a major.
  It does not. semantic-release's Angular preset ignores the `!`
  shorthand, so `feat!:` alone yields no release while CI stays green.
  The BREAKING CHANGE footer is what does the work, which also makes
  merge commits safer than squash for a major.
- The release flow omitted the `plan` job and described `build` as
  unconditional. Builds now happen only when a release is actually coming.
- The weekly bump was described as touching only the two image configs
  and explicitly "not" the feature. It updates five files, bumps the
  feature's own version, derives the release type from plcc-ng's major,
  and retags image references on a major.
- Bootstrap said to require "the CI status check". Requiring job names is
  what hung PRs in both repos today; require `ci-gate` and only `ci-gate`.
- Housekeeping implied candidates accumulate on every merge; infra-only
  merges no longer build at all.

Neither commit type releases, so this changes nothing about versioning.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 27, 2026 19:09
@StoneyJackson
StoneyJackson merged commit 45bff4b into main Jul 27, 2026
7 checks passed
@StoneyJackson
StoneyJackson deleted the docs/accurate-release-docs branch July 27, 2026 19:10

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the repository’s release documentation to reflect the current GitHub Actions workflows and semantic-release behavior, reducing the risk of maintainers following outdated or misleading instructions.

Changes:

  • Corrects Conventional Commit guidance for major releases to rely on BREAKING CHANGE: footers (not feat!:).
  • Documents the Release workflow’s plan step and that image builds/publishing are conditional on an actual release.
  • Expands the “weekly plcc-ng bump” and bootstrap/ruleset guidance to match current automation (including ci-gate).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File Description
README.md Updates contributor-facing Conventional Commit / major-release guidance to match semantic-release behavior.
docs/maintainer-guide.md Aligns maintainer release flow, weekly bump process, and branch protection guidance with current workflows (plan/build gating, ci-gate, housekeeping).
Comments suppressed due to low confidence (1)

docs/maintainer-guide.md:152

  • This section says infra-only merges “skip the build entirely”, but earlier the guide correctly explains that the build job still runs and only its steps are skipped when plan says no release is coming. Consider rewording here to avoid contradicting the earlier explanation.
  the package settings UI if clutter bothers you. Candidates are only
  produced for commits that actually release — infra-only merges skip the
  build entirely (see `plan`, above), so they no longer leave orphans.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/maintainer-guide.md
Comment on lines +28 to +29
For the same reason, prefer a merge commit over squash on a major: squash
can drop the footer and silently downgrade the release to a minor.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants