docs: Keep a Changelog header + README link for CHANGELOG.md - #724
docs: Keep a Changelog header + README link for CHANGELOG.md#724Patrick Phipps (drkemp187) wants to merge 2 commits into
Conversation
Preserve the existing release-please CHANGELOG history. Add Keep a Changelog / SemVer header, an Unreleased section, and a README link so OSSF reviewers and contributors can find the changelog easily. Fixes microsoft#143
ec46dac to
979e0ae
Compare
Patrick Phipps (drkemp187)
changed the title
|
@microsoft-github-policy-service agree |
| Categories align with [`.github/release.yml`](.github/release.yml). | ||
| GitHub Releases remain the canonical auto-generated notes. | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
The next release-please run will insert the generated version above this heading. Its changelog updater inserts before the first heading matching \n###? v?[0-9[], and ## [Unreleased] is now that first match. I reproduced this against the PR content, where the generated release was placed between the preamble and Unreleased. Could we remove this heading so release-please continues to place each generated version directly below the preamble? The insertion logic is available in the official release-please source.
If the heading needs to remain, could we first verify a supported release-please configuration that preserves it at the top after every release?
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| Categories align with [`.github/release.yml`](.github/release.yml). |
There was a problem hiding this comment.
Could we revise this sentence to distinguish the two category sources? The changelog headings come from changelog-sections in release-please-config.json, while .github/release.yml configures GitHub's label-based automatically generated release notes. GitHub documents the latter behavior in Automatically generated release notes.
The current configurations might not satisfy issue #143's alignment criterion. For example, the changelog includes Miscellaneous Chores, Build System, and Code Refactoring, which are not categories in .github/release.yml, and dependency changes are included by release-please but excluded from the GitHub release-note configuration. Could you either align the configurations or clarify that they intentionally serve different outputs?
| Categories align with [`.github/release.yml`](.github/release.yml). | ||
| GitHub Releases remain the canonical auto-generated notes. | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
If this heading is intended to be a link like the generated version headings, it might be missing an [Unreleased] reference definition. The CommonMark specification requires a matching link reference definition for a shortcut reference link. Keep a Changelog also demonstrates linking Unreleased to the comparison with HEAD.
Could we either add and maintain that comparison link or use unambiguous plain text? This comment is unnecessary if the heading is removed to address the release-please insertion behavior.
2 participants
Summary
CHANGELOG.mdhistory intact## [Unreleased]sectionCloses #143
Why
Root CHANGELOG already existed (release-please). This PR makes the format explicit for OSSF reviewers and links it from the README without rewriting history.
Test plan