Adding instructions to automate CHANGELOG reviews with Copilot by sabbour · Pull Request #5474 · Azure/AKS

sabbour · 2025-11-30T19:48:51Z

Also updated existing CHANGELOG to reflect the instructions

Copilot

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

.github/instructions/changelog.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

pauldotyu

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?

.github/instructions/changelog.instructions.md

Co-authored-by: Paul Yu <paul.d.yu@gmail.com>

.github/instructions/changelog.instructions.md

palma21 · 2025-12-09T23:23:34Z

.github/instructions/changelog.instructions.md

+* 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.


We now have a new versions category that we seem to have added, so isn't it better to have all version things there?

That is a future announcement though. So isn't it better here, assuming we rename that section to be "Announcements of upcoming changes"?

.github/instructions/changelog.instructions.md

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 5 comments.

.github/instructions/changelog.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

kaarthis

PTAL

.github/instructions/changelog.instructions.md

kaarthis · 2025-12-10T22:52:18Z

.github/instructions/changelog.instructions.md

+## Validation Checklist
+
+Before committing changes to CHANGELOG.md:
+


Make sure that anything that can be in Feature , Preview, Kubernetes versions need not come in the announcements.

kaarthis · 2025-12-10T22:54:26Z

.github/instructions/changelog.instructions.md

+- [ ] 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


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.

kaarthis · 2025-12-10T22:55:14Z

.github/instructions/changelog.instructions.md

+
+---
+
+## Validation Checklist


Bug fixes all have a corresponding GH link

kaarthis · 2025-12-10T22:57:42Z

.github/instructions/changelog.instructions.md

+
+Before committing changes to CHANGELOG.md:
+
+- [ ] Release date uses `YYYY-MM-DD` format


Kubernetes versions - patches, minor versions, deprecations , LTS should all come exclusively in Kubernetes versions section.

kaarthis · 2025-12-10T22:59:23Z

.github/instructions/changelog.instructions.md

+- [ ] 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")


Component updates especially for upstream OSS projects should link to the corresponding upstream URL eg: Cilium https://github.com/cilium/cilium/releases

jakjang · 2025-12-11T00:04:11Z

.github/instructions/changelog.instructions.md

+
+#### 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.


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...

…notes

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 10 comments.

.github/instructions/changelog.instructions.md

Copilot · 2026-01-23T22:18:09Z

.github/instructions/changelog.instructions.md

@@ -0,0 +1,616 @@
+<!-- markdownlint-disable -->


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.

.github/instructions/changelog.instructions.md

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

Copilot · 2026-01-27T20:42:25Z

.github/instructions/changelog.instructions.md

+```markdown
+* AKS Azure Linux v2 image has been updated to [`AzureLinux-202510.03.0`](vhd-notes/AzureLinux/202510.03.0.txt).
+* AKS Azure Linux v3 image has been updated to [`AzureLinux-202510.03.0`](vhd-notes/AzureLinuxv3/202510.03.0.txt).
+* AKS Ubuntu 22.04 node image has been updated to [`AKSUbuntu-2204-202510.03.0`](vhd-notes/aks-ubuntu/AKSUbuntu-2204/202510.03.0.txt).


The instructions specify that VHD image names should include the full image name format (e.g., AKSUbuntu-2204-202510.03.0), but the actual CHANGELOG.md file uses only the version number (e.g., 202510.03.0).

The PR description states "Also updated existing CHANGELOG to reflect the instructions," but CHANGELOG.md is not included in this PR's changes. Either:

The instructions should be updated to match the current CHANGELOG.md format (using just version numbers), or

CHANGELOG.md should be updated in this PR to match the instructions, or

The PR description should be updated to clarify that CHANGELOG.md updates will come separately

This inconsistency could confuse future contributors about which format to use.

.github/instructions/changelog.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

Copilot · 2026-01-27T20:53:01Z

.github/instructions/changelog.instructions.md

+#### Versions introduced or graduating to GA
+* Kubernetes Version [X.XX Preview](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-X.XX.md) is being rolled out.
+* Kubernetes Version [X.XX](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-X.XX.md) is now generally available.
+* Kubernetes patch versions [X.XX.X](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-X.XX.X.md), [X.XX.X](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-X.XX.X.md), [X.XX.X](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-X.XX.X.md) are now available.


Missing space after the first comma in the Kubernetes patch versions list. This is inconsistent with the example on line 127 which shows proper spacing after commas.

.github/instructions/changelog.instructions.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 2 comments.

Copilot · 2026-01-27T20:58:15Z

.github/instructions/changelog.instructions.md

+```markdown
+* Starting on 30 November 2025, AKS will no longer support Azure Linux 2.0. Migrate to a supported version by [upgrading your node pools](https://learn.microsoft.com/azure/aks/upgrade-cluster?tabs=azure-cli). For more information, see [\[Retirement\] Azure Linux 2.0 node pools on AKS](https://github.com/Azure/AKS/issues/4988).
+* AKS Kubernetes version 1.31 standard support will be deprecated by November 1, 2025. Kindly upgrade your clusters to 1.32 community version or enable [Long Term Support](https://learn.microsoft.com/azure/aks/long-term-support) with 1.31 in order to continue in the same version. Refer to [version support policy](https://learn.microsoft.com/azure/aks/supported-kubernetes-versions?tabs=azure-cli#kubernetes-version-support-policy) and [upgrading a cluster](https://learn.microsoft.com/azure/aks/upgrade-cluster?tabs=azure-cli) for more information.
+* [Teleport (preview)](https://github.com/Azure/acr/blob/main/docs/teleport/aks-getting-started.md) on AKS will be retired on 15 July 2025, please [migrate to Artifact Streaming (preview) on AKS](https://learn.microsoft.com/azure/aks/artifact-streaming) or update your node pools to set --aks-custom-headers EnableACRTeleport=false. For more information, see [aka.ms/aks/teleport-retirement](https://aka.ms/aks/teleport-retirement).


The command line flag --aks-custom-headers should be formatted with backticks according to the Microsoft Style Guide which states "Use backticks for code, component names, and versions" (see Formatting section on line 401). Command line flags and parameters are code elements and should be styled accordingly.

Suggested change

* [Teleport (preview)](https://github.com/Azure/acr/blob/main/docs/teleport/aks-getting-started.md) on AKS will be retired on 15 July 2025, please [migrate to Artifact Streaming (preview) on AKS](https://learn.microsoft.com/azure/aks/artifact-streaming) or update your node pools to set --aks-custom-headers EnableACRTeleport=false. For more information, see [aka.ms/aks/teleport-retirement](https://aka.ms/aks/teleport-retirement).

* [Teleport (preview)](https://github.com/Azure/acr/blob/main/docs/teleport/aks-getting-started.md) on AKS will be retired on 15 July 2025, please [migrate to Artifact Streaming (preview) on AKS](https://learn.microsoft.com/azure/aks/artifact-streaming) or update your node pools to set `--aks-custom-headers` EnableACRTeleport=false. For more information, see [aka.ms/aks/teleport-retirement](https://aka.ms/aks/teleport-retirement).

Copilot · 2026-01-27T20:58:17Z

.github/instructions/changelog.instructions.md

+* App Routing updated to version 0.2.10 with ingress-nginx bumped to [`v1.13.1`](https://github.com/Azure/aks-app-routing-operator/pull/497) addressing [CVE-2025-22874](https://nvd.nist.gov/vuln/detail/CVE-2025-22874), [CVE-2025-47906](https://nvd.nist.gov/vuln/detail/CVE-2025-47906), and [CVE-2025-47907](https://nvd.nist.gov/vuln/detail/CVE-2025-47907).
+* VPA (Vertical Pod Autoscaler) has been updated to [`1.4.2`](https://github.com/kubernetes/autoscaler/releases/tag/vertical-pod-autoscaler-1.4.2) on AKS 1.34.
+* Retina Basic Image has been updated to [`v1.0.0-rc3`](https://github.com/microsoft/retina/releases/tag/v1.0.0-rc3) on both Linux and Windows to resolve [GHSA-2464-8j7c-4cjm](https://github.com/advisories/GHSA-2464-8j7c-4cjm). See [#1824](https://github.com/microsoft/retina/pull/1824) and [#1881](https://github.com/microsoft/retina/pull/1881) for details.
+* [Azure Monitor managed service for Prometheus](https://learn.microsoft.com/azure/azure-monitor/metrics/prometheus-metrics-overview#azure-monitor-managed-service-for-prometheus) addon is updated to the latest release [06-19-2025](https://github.com/Azure/prometheus-collector/blob/main/RELEASENOTES.md#release-06-19-2025).


Inconsistent terminology: "addon" should be "add-on" to match the hyphenation used elsewhere in this file (lines 95, 255, 278) and to align with the Microsoft Style Guide which specifies "add-in" should be hyphenated (see .github/copilot-instructions.md:532). This ensures consistent terminology throughout the CHANGELOG instructions.

Suggested change

* [Azure Monitor managed service for Prometheus](https://learn.microsoft.com/azure/azure-monitor/metrics/prometheus-metrics-overview#azure-monitor-managed-service-for-prometheus) addon is updated to the latest release [06-19-2025](https://github.com/Azure/prometheus-collector/blob/main/RELEASENOTES.md#release-06-19-2025).

* [Azure Monitor managed service for Prometheus](https://learn.microsoft.com/azure/azure-monitor/metrics/prometheus-metrics-overview#azure-monitor-managed-service-for-prometheus) add-on is updated to the latest release [06-19-2025](https://github.com/Azure/prometheus-collector/blob/main/RELEASENOTES.md#release-06-19-2025).

sabbour added 4 commits November 26, 2025 17:59

Adding changelog instructions

b982b3c

Ran the instructions against existing CHANGELOG.md

b00502a

Updated instructions and existing changelog formatting

7b29160

Merge branch 'Azure:master' into changelog-copilot-instructions

1d0b1ba

sabbour requested a review from Copilot November 30, 2025 19:48

sabbour requested review from a team and palma21 as code owners November 30, 2025 19:48

sabbour requested a review from thomas1206 November 30, 2025 19:48

Copilot started reviewing on behalf of sabbour November 30, 2025 19:49 View session

Copilot finished reviewing on behalf of sabbour November 30, 2025 19:52

Copilot AI reviewed Nov 30, 2025

View reviewed changes

.github/instructions/changelog.instructions.md Outdated Show resolved Hide resolved

.github/instructions/changelog.instructions.md Outdated Show resolved Hide resolved

.github/instructions/changelog.instructions.md Outdated Show resolved Hide resolved

sabbour and others added 3 commits November 30, 2025 11:53

Update .github/instructions/changelog.instructions.md

2067d01

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update .github/instructions/changelog.instructions.md

d5b89b8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fixed incorrect URL format

3d3dc29

pauldotyu reviewed Dec 1, 2025

View reviewed changes

.github/instructions/changelog.instructions.md Outdated Show resolved Hide resolved

.github/instructions/changelog.instructions.md Outdated Show resolved Hide resolved

sabbour and others added 2 commits December 2, 2025 19:47

Update .github/instructions/changelog.instructions.md

011ccb6

Co-authored-by: Paul Yu <paul.d.yu@gmail.com>

Apply suggestions from code review

926e088

Co-authored-by: Paul Yu <paul.d.yu@gmail.com>

jakjang reviewed Dec 9, 2025

View reviewed changes

.github/instructions/changelog.instructions.md Show resolved Hide resolved

palma21 reviewed Dec 9, 2025

View reviewed changes

Addressing some comments

f27fc87

sabbour requested a review from Copilot December 10, 2025 22:05

Copilot started reviewing on behalf of sabbour December 10, 2025 22:06 View session

Copilot AI reviewed Dec 10, 2025

View reviewed changes

sabbour and others added 2 commits December 10, 2025 14:10

Update .github/instructions/changelog.instructions.md

ca0678b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update .github/instructions/changelog.instructions.md

e9ac8db

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

kaarthis reviewed Dec 10, 2025

View reviewed changes

jakjang reviewed Dec 11, 2025

View reviewed changes

Update changelog instructions for clarity and consistency in release …

e081c91

…notes

Copilot AI review requested due to automatic review settings January 23, 2026 22:12

Copilot started reviewing on behalf of shashankbarsin January 23, 2026 22:12 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

Updated based on Copilot suggestions

bb24268

sabbour requested a review from Copilot January 27, 2026 20:37

Copilot started reviewing on behalf of sabbour January 27, 2026 20:38 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

Update .github/instructions/changelog.instructions.md

9c15bf8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 27, 2026 20:48

Copilot started reviewing on behalf of sabbour January 27, 2026 20:48 View session

Update .github/instructions/changelog.instructions.md

b50dde4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI reviewed Jan 27, 2026

View reviewed changes

Update .github/instructions/changelog.instructions.md

fad248f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 27, 2026 20:53

Copilot started reviewing on behalf of sabbour January 27, 2026 20:54 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

Updated based on Copilot

163ccc3

		## Validation Checklist

		Before committing changes to CHANGELOG.md:


		Before committing changes to CHANGELOG.md:

		- [ ] Release date uses `YYYY-MM-DD` format


		#### 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.

	* [Azure Monitor managed service for Prometheus](https://learn.microsoft.com/azure/azure-monitor/metrics/prometheus-metrics-overview#azure-monitor-managed-service-for-prometheus) addon is updated to the latest release [06-19-2025](https://github.com/Azure/prometheus-collector/blob/main/RELEASENOTES.md#release-06-19-2025).
	* [Azure Monitor managed service for Prometheus](https://learn.microsoft.com/azure/azure-monitor/metrics/prometheus-metrics-overview#azure-monitor-managed-service-for-prometheus) add-on is updated to the latest release [06-19-2025](https://github.com/Azure/prometheus-collector/blob/main/RELEASENOTES.md#release-06-19-2025).

Conversation

sabbour commented Nov 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pauldotyu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kaarthis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!