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.
| * 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"?
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
| ## 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...
| |:----------|:-------|:--------| | ||
| | Microsoft Learn | `[Text](https://learn.microsoft.com/...)` | `[upgrade your node pools](https://learn.microsoft.com/azure/aks/upgrade-cluster)` | | ||
| | GitHub Issues | `[#XXXX](https://github.com/Azure/AKS/issues/XXXX)` or `[GitHub issue](URL)` | `[#4988](https://github.com/Azure/AKS/issues/4988)` | | ||
| | GitHub Releases | `[vX.Y.Z](https://github.com/org/repo/releases/tag/vX.Y.Z)` | `[v1.7.4](https://github.com/Azure/azure-container-networking/releases/tag/v1.7.4)` | |
There was a problem hiding this comment.
The GitHub Releases format and example in this table row are missing backticks around the version numbers, which is inconsistent with the actual examples shown throughout the document (e.g., line 270). The format should show: [vX.Y.Z](https://github.com/org/repo/releases/tag/vX.Y.Z) and the example should be: [v1.7.4](https://github.com/Azure/azure-container-networking/releases/tag/v1.7.4) with backticks around the version numbers.
| | GitHub Releases | `[vX.Y.Z](https://github.com/org/repo/releases/tag/vX.Y.Z)` | `[v1.7.4](https://github.com/Azure/azure-container-networking/releases/tag/v1.7.4)` | | |
| | GitHub Releases | [`vX.Y.Z`](https://github.com/org/repo/releases/tag/vX.Y.Z) | [`v1.7.4`](https://github.com/Azure/azure-container-networking/releases/tag/v1.7.4) | |
|
|
||
| #### Preview features | ||
|
|
||
| * [Preview Feature Name](https://learn.microsoft.com/azure/aks/preview-feature-doc) is now available in preview. Brief 1 line description of the value proposition of the feature here. |
There was a problem hiding this comment.
The template example has inconsistent formatting. There should be a blank line between "Preview features" section heading and "Behavioral changes" section heading to maintain consistency with the rest of the template structure.
| * [Preview Feature Name](https://learn.microsoft.com/azure/aks/preview-feature-doc) is now available in preview. Brief 1 line description of the value proposition of the feature here. | |
| * [Preview Feature Name](https://learn.microsoft.com/azure/aks/preview-feature-doc) is now available in preview. Brief 1 line description of the value proposition of the feature here. |
| @@ -0,0 +1,616 @@ | |||
| <!-- markdownlint-disable --> | |||
There was a problem hiding this comment.
The PR description states "Also updated existing CHANGELOG to reflect the instructions", but there are no changes to CHANGELOG.md shown in this pull request. Either the description is inaccurate, or the CHANGELOG.md changes were made in a separate commit that is not part of this PR. Please clarify whether CHANGELOG.md changes are part of this PR or update the description accordingly.
| - **No locale in URLs**: Use `https://learn.microsoft.com/azure/...` not `https://learn.microsoft.com/en-us/azure/...` | ||
| - **Descriptive link text**: Use meaningful text, never "click here" or bare URLs | ||
| - **Component versions**: Always require link to release notes: `` [v1.33.5](URL) `` | ||
| - **VHD image names**: Always require link to VHD notes: `` [AKSUbuntu-2204-202510.03.0](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202510.03.0.txt) `` |
There was a problem hiding this comment.
The VHD image name in this rule is missing backticks, which is inconsistent with the format shown in the table above (line 361) and the examples throughout the document. It should be: [`AKSUbuntu-2204-202510.03.0`](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202510.03.0.txt)
| - **VHD image names**: Always require link to VHD notes: `` [AKSUbuntu-2204-202510.03.0](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202510.03.0.txt) `` | |
| - **VHD image names**: Always require link to VHD notes: `` [`AKSUbuntu-2204-202510.03.0`](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202510.03.0.txt) `` |
|
|
||
| * Document version updates for AKS components. | ||
| * Only include components that are external user facing and don't include components that are internal to AKS service design. | ||
| * Only accept links to release notes of components that are publicly accesible and not from private repositories. |
There was a problem hiding this comment.
Spelling error: "accesible" should be "accessible".
| * Only accept links to release notes of components that are publicly accesible and not from private repositories. | |
| * Only accept links to release notes of components that are publicly accessible and not from private repositories. |
|
|
||
| ### Announcements of upcoming changes and retirements | ||
|
|
||
| * [Announcement item with link to documentation if it exists](https://learn.microsoft.com/...) description of the announcement or retirement. |
There was a problem hiding this comment.
The template example contains trailing whitespace at the end of this line. This violates the markdown linting rule MD009 mentioned in the "Markdown Linting" section of this file (line 606). Remove the trailing space after "retirement."
| * [Announcement item with link to documentation if it exists](https://learn.microsoft.com/...) description of the announcement or retirement. | |
| * [Announcement item with link to documentation if it exists](https://learn.microsoft.com/...) description of the announcement or retirement. |
| * [Feature Name](URL) is now generally available. [Description]. Brief 1 line description of the feature and its value proposition here. | ||
| * [Feature Name](URL) is now generally available in specific regions/contexts. [Description]. Brief 1 line description of the feature and its value proposition here. |
There was a problem hiding this comment.
The template contains redundant description placeholders. It shows "[Description]. Brief 1 line description of the feature and its value proposition here." but the examples that follow only include one description after "is now generally available." Consider simplifying the template to match the examples, removing the "[Description]." prefix to avoid confusion.
| * [Feature Name](URL) is now generally available. [Description]. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now generally available in specific regions/contexts. [Description]. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now generally available. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now generally available in specific regions/contexts. Brief 1 line description of the feature and its value proposition here. |
| * [Feature Name](URL) is now available as preview. [Description]. Brief 1 line description of the feature and its value proposition here. | ||
| * [Feature Name](URL) is now available as preview in specific regions/contexts. [Description]. Brief 1 line description of the feature and its value proposition here. |
There was a problem hiding this comment.
The template contains redundant description placeholders. It shows "[Description]. Brief 1 line description of the feature and its value proposition here." but the examples that follow only include one description after "is now available as preview." Consider simplifying the template to match the examples, removing the "[Description]." prefix to avoid confusion.
| * [Feature Name](URL) is now available as preview. [Description]. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now available as preview in specific regions/contexts. [Description]. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now available as preview. Brief 1 line description of the feature and its value proposition here. | |
| * [Feature Name](URL) is now available as preview in specific regions/contexts. Brief 1 line description of the feature and its value proposition here. |
| --- | ||
|
|
||
| **Questions?** See `.github/copilot-instructions.md` for the complete Microsoft Style Guide and repository standards. | ||
|
|
There was a problem hiding this comment.
The file ends with multiple consecutive blank lines (lines 616-617), which violates the MD012 markdown linting rule documented on line 607 of this file. The file should end with a single newline character per MD047 (also documented on line 608). Remove the extra blank line at the end of the file.
|
|
||
| - **No locale in URLs**: Use `https://learn.microsoft.com/azure/...` not `https://learn.microsoft.com/en-us/azure/...` | ||
| - **Descriptive link text**: Use meaningful text, never "click here" or bare URLs | ||
| - **Component versions**: Always require link to release notes: `` [v1.33.5](URL) `` |
There was a problem hiding this comment.
The component version format in this rule is missing backticks around the version number, which is inconsistent with the examples throughout the document (e.g., line 270). The format should be: [`v1.33.5`](URL) with backticks around the version number.
| - **Component versions**: Always require link to release notes: `` [v1.33.5](URL) `` | |
| - **Component versions**: Always require link to release notes: `` [`v1.33.5`](URL) `` |
6 participants
Also updated existing CHANGELOG to reflect the instructions