docs(changelog): cut internal rationale from the Unreleased entries - #764
Merged
Conversation
The developer documentation style guide gained a "Release notes and changelogs"
section (CP dev/DEVELOPER_DOCUMENTATION_STYLE_GUIDE, 2026-07-28): a changelog
answers what changed for the reader and what they must do, and nothing else.
It names five things to keep out. The Unreleased block violated four of them.
The SSO/MFA entry is the guide's published counter-example, so this is a
correction rather than an interpretation. It carried the packaging rationale
("authentication-strength ceiling on the free tier"), the paid-tier entitlement
count, the admission that neither flag ever gated a route, and the internal
mechanics of how the features array is assembled. Rewritten to the guide's
recommended form: what changed, no access change, update clients asserting on
the array.
The tier-rename entry keeps its break and its action and loses the
pre-1.0-minor-release meta-commentary and the internal note about what
entitlement turns on.
The remediation_execution / remediation_auto entry is dropped entirely. The
guide is explicit that a dormant registered flag is not a changelog entry:
nothing consumes remediation_auto and single-rule remediation was free before
and after, so it changed nothing for a reader. The scoping decision belongs in
the roadmap and the licensing plan, where it already is.
No behaviour change; CHANGELOG.md only.
remyluslosius
force-pushed
the
docs/changelog-style-compliance
branch
from
July 28, 2026 12:13
328aecd to
e6ed452
Compare
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
1 participant
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.
The style guide gained a Release notes and changelogs section (CP
dev/DEVELOPER_DOCUMENTATION_STYLE_GUIDE, updated 2026-07-28). A changelog answers what changed for me and what must I do, and nothing else. It names five things to keep out; the Unreleased block violated four.The SSO/MFA entry is the guide's published counter-example, so this is a correction, not an interpretation. It carried the packaging rationale, the paid-tier entitlement count, the admission that neither flag ever gated a route, and the internal mechanics of how the
featuresarray is assembled. Rewritten to the guide's recommended form.The tier-rename entry keeps its break and action, and loses the pre-1.0 meta-commentary.
The
remediation_autoentry is dropped: the guide is explicit that a dormant registered flag is not a changelog entry. Nothing consumes it, single-rule remediation was free before and after. The scoping decision already lives in the roadmap and the licensing plan.No behaviour change.
CHANGELOG.mdonly.