Adding instructions to automate CHANGELOG reviews with Copilot #5474
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces comprehensive CHANGELOG validation guidelines to automate reviews with Copilot. The new instructions provide detailed standards for release notes formatting, content structure, and Microsoft Style Guide compliance.
Key changes:
- Added comprehensive CHANGELOG.md validation guidelines with templates, examples, and formatting rules
- Added markdownlint-disable comment to blog instructions file for consistency
- Established clear standards for component updates, VHD image references, and documentation links
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
.github/instructions/website.blog.instructions.md |
Added markdownlint-disable comment at the top of the file for consistency with other instruction files |
.github/instructions/changelog.instructions.md |
New comprehensive 620-line guideline document covering release structure templates, section formatting rules, link requirements, Microsoft Style Guide compliance, validation checklists, and common mistakes with examples |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
pauldotyu
left a comment
pauldotyu
left a comment
There was a problem hiding this comment.
LGTM and seems that it cleaned up a lot of the old CHANGELOG.md content to meet the new guidelines.
Should we also include automation to take the latest release note entry in the CHANGELOG.md and create a new release in the GitHub Releases page?
Co-authored-by: Paul Yu <paul.d.yu@gmail.com>
Co-authored-by: Paul Yu <paul.d.yu@gmail.com>
| * Component Name has been updated to [`vX.Y.Z`](https://github.com/org/repo/releases/tag/vX.Y.Z). | ||
| * AKS Ubuntu 22.04 node image has been updated to [`YYYYMM.DD.V`](vhd-notes/aks-ubuntu/AKSUbuntu-2204/YYYYMM.DD.V.txt). | ||
|
|
||
| --- |
There was a problem hiding this comment.
| --- | |
| --- | |
| ## Release Notes YYYY-MM-DD | |
| ... |
There was a problem hiding this comment.
I think this could help, it took me a few seconds to understand the Horizontal rule.
There was a problem hiding this comment.
Why would I include the header of the previous release notes here?
There was a problem hiding this comment.
Was thinking it'd be a good showcase of "Horizontal rule: Use --- between releases", you'd see that --- leads directly to the previous release.
|
|
||
| ```markdown | ||
| * Starting on [DATE], [what will happen]. [Action required]. For more information, see [Link Text](URL). | ||
| * [Product/Feature] is now [status]. [Brief description]. Refer to [documentation](URL) for more information. |
There was a problem hiding this comment.
This shouldn't really be in announcements?
There was a problem hiding this comment.
You're correct. I think Copilot found a mix of cases where some feature announcements ended up here. I'll remove that since this should be under the Features section.
| * Starting on [DATE], [what will happen]. [Action required]. For more information, see [Link Text](URL). | ||
| * [Product/Feature] is now [status]. [Brief description]. Refer to [documentation](URL) for more information. | ||
| * [Feature/Product] (preview) will be retired on [DATE]. [Migration instructions]. For more information, see [Link](URL). | ||
| * AKS Kubernetes version X.XX [standard support will be deprecated/is going out of support] by [DATE]. [Action required]. Refer to [version support policy](URL) and [upgrading a cluster](URL) for more information. |
There was a problem hiding this comment.
We now have a new versions category that we seem to have added, so isn't it better to have all version things there?
There was a problem hiding this comment.
That is a future announcement though. So isn't it better here, assuming we rename that section to be "Announcements of upcoming changes"?
| * AKS LTS (Long Term Support) patch versions are now available: | ||
| * Kubernetes X.XX.XXX-akslts - [Changelog](URL) | ||
| * Kubernetes X.XX and X.XX are now designated as [Long-Term Support (LTS)](URL) versions. | ||
| ``` |
There was a problem hiding this comment.
Suggest adding here removals and version announcements
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
|
||
| ### Release notes | ||
|
|
||
| #### Kubernetes versions |
There was a problem hiding this comment.
Deprecation of versions including LTS and launch of minor versions (GA) should be here. FYI Going forward we should also call out any 'System enforced 'Upgrade dates' ' or forced upgrade from Community to LTS . LTS EOL to community version probably either here or in announcements as the PRD Dan is driving comes to fruition.
| ## Validation Checklist | ||
|
|
||
| Before committing changes to CHANGELOG.md: | ||
|
|
There was a problem hiding this comment.
Make sure that anything that can be in Feature , Preview, Kubernetes versions need not come in the announcements.
| - [ ] Microsoft Learn links don't include `/en-us/` | ||
| - [ ] Component versions are in backticks with release note links | ||
| - [ ] VHD image names are in backticks and use the full Markdown link format (e.g., ``[`AKSUbuntu-2204-202306.26.0`](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202306.26.0.txt)``) | ||
| - [ ] VHD note files exist at the referenced paths |
There was a problem hiding this comment.
Think we should also link to the 'Release tracker - Node images' section which is a more real time view depending on when the Rel notes was seen this is useful.
|
|
||
| --- | ||
|
|
||
| ## Validation Checklist |
There was a problem hiding this comment.
Bug fixes all have a corresponding GH link
|
|
||
| Before committing changes to CHANGELOG.md: | ||
|
|
||
| - [ ] Release date uses `YYYY-MM-DD` format |
There was a problem hiding this comment.
Kubernetes versions - patches, minor versions, deprecations , LTS should all come exclusively in Kubernetes versions section.
| - [ ] Only sections with content are included | ||
| - [ ] Section hierarchy follows template (`###` for main, `####` under Release notes) | ||
| - [ ] Bullet points use `*` consistently | ||
| - [ ] All links use descriptive text (no bare URLs or "click here") |
There was a problem hiding this comment.
Component updates especially for upstream OSS projects should link to the corresponding upstream URL eg: Cilium https://github.com/cilium/cilium/releases
|
|
||
| #### VHD/Node image updates | ||
|
|
||
| Use relative paths to VHD note files. **Validate that referenced files exist in the repository.** VHD image names should be wrapped in backticks, consistent with component version formatting. |
There was a problem hiding this comment.
In similar vein to Jorge's comment above, should we include version deprecations here?
e.g.
* AKS Azure Linux v2 is approaching end of life on...
5 participants
Also updated existing CHANGELOG to reflect the instructions