docs: correct the release docs to match what the workflows now do - #9
Merged
Conversation
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>
There was a problem hiding this comment.
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 (notfeat!:). - Documents the
Releaseworkflow’splanstep 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
buildjob still runs and only its steps are skipped whenplansays 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 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Five separate inaccuracies, all of which would mislead a maintainer:
feat!:produces a major. It does not. semantic-release's Angular preset ignores the!shorthand, sofeat!: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.planjob and describedbuildas unconditional. Builds now happen only when a release is actually coming.ci-gateand onlyci-gate.Neither commit type releases, so this changes nothing about versioning.