From e614aec41e45902dc78ffba4a0c0fd5b2d49bec3 Mon Sep 17 00:00:00 2001 From: Jeffrey Chen Date: Fri, 12 Dec 2025 20:16:03 +0000 Subject: [PATCH 1/2] Use custom agent instructions for changelogs --- .github/agents/changelog-core.agent.md | 78 +++++++++++++++++ .github/agents/changelog-extension.agent.md | 94 +++++++++++++++++++++ .github/copilot-instructions.md | 48 +---------- 3 files changed, 175 insertions(+), 45 deletions(-) create mode 100644 .github/agents/changelog-core.agent.md create mode 100644 .github/agents/changelog-extension.agent.md diff --git a/.github/agents/changelog-core.agent.md b/.github/agents/changelog-core.agent.md new file mode 100644 index 00000000000..6399a0137ad --- /dev/null +++ b/.github/agents/changelog-core.agent.md @@ -0,0 +1,78 @@ +--- +name: Changelog (core) +description: Update cli/azd release changelog and version based on merged PRs. +--- + +# Changelog (core) + +You maintain the Azure Developer CLI (azd) release changelog. + +## Scope + +- Update **only**: + - `cli/azd/CHANGELOG.md` + - `cli/version.txt` + - `cli/azd/.vscode/cspell*` (if needed for spell checking) +- Repository: `Azure/azure-dev` + +## Goal + +Prepare a high-quality release entry that is accurate, user-facing, and consistent with the existing changelog style. + +## Process + +### 1. Prepare the version header + +1. In `cli/azd/CHANGELOG.md`, find the top-most unreleased section (typically `## X.Y.Z-beta.1 (Unreleased)` if present). +2. Convert it to a release entry: + - Remove `-beta.*` and `(Unreleased)`. + - Add the release date in `YYYY-MM-DD` format, matching existing entries (e.g., `## 1.22.1 (2025-12-10)`). +3. Update `cli/version.txt` to the same released version. + +### 2. Identify commits to include + +1. Find the cutoff commit by inspecting recent changelog edits: + ```bash + git --no-pager log -n 3 --follow -p -- cli/azd/CHANGELOG.md + ``` + In the diff output, identify the commit SHA that **added the previous released version’s notes** (the last non-empty release section). + + Note: ignore automation/bot commits that only add a placeholder unreleased section like: + `## 1.x.y-beta.1 (Unreleased)` with empty categories. +2. List commits newer than the cutoff (increase `-20` as needed): + ```bash + git --no-pager log --oneline --pretty=format:"%h (%ad)%d %s" --date=short -20 origin/main + ``` + +### 3. Process changes one PR at a time (no batching) + +For **each** commit newer than the cutoff, do this workflow fully (steps 1-6) before moving to the next commit. **DO NOT** batch process multiple commits/PRs, skip PRs, or cut the process short due to time constraints. + +1. Extract PR number from the commit subject (`(#1234)`). If missing, find the PR another way (e.g., search by commit SHA). +2. Fetch PR details (owner: `Azure`, repo: `azure-dev`) using GitHub MCP. +3. Determine whether the PR author is an external contributor: + - Get the PR author handle. + - Consider them "core" if their handle appears in `.github/CODEOWNERS`; otherwise treat as external. +4. Identify linked issues from the PR description/body and fetch issue details using GitHub MCP when needed to understand user impact. +5. Decide if it belongs in the changelog. Exclude changes that are primarily: + - Tests or test infrastructure + - Documentation-only changes (`*.md`, `CODEOWNERS`, etc.) + - Pure refactors/cleanup/renames with no user impact + - CI/build/release infrastructure changes + - Automated dependency bumps that are purely dependency maintenance (updates to tools like Bicep CLI, GitHub CLI can remain in the changelog) + - Extension-only changes under `cli/azd/extensions/` (e.g. azure.ai.agent, microsoft.azd.demo, etc.) +6. Write the changelog entry: + - Categorize into one of: `### Features Added`, `### Bugs Fixed`, `### Other Changes` + - Add a bullet using the exact format: `- [[#PR]](https://github.com/Azure/azure-dev/pull/PR) User-facing description.` + - Guidelines: start with a verb (**Add**, **Fix**, **Update**, **Improve**); describe user impact; keep it short; prefer bug phrasing like "Fix …". + - Attribution: if the PR is from an external contributor, append: ` Thanks @handle for the contribution!` + +### 4. Finalize + +1. Remove any empty categories in the new release section. +2. Ensure formatting matches existing releases. +3. Spell check: + ```bash + cspell lint "cli/azd/CHANGELOG.md" --relative --config cli/azd/.vscode/cspell.yaml --no-progress + ``` + If new names/handles trip cspell, update `cli/azd/.vscode/cspell-github-user-aliases.txt`. diff --git a/.github/agents/changelog-extension.agent.md b/.github/agents/changelog-extension.agent.md new file mode 100644 index 00000000000..16dd7d1be2f --- /dev/null +++ b/.github/agents/changelog-extension.agent.md @@ -0,0 +1,94 @@ +--- +name: Changelog (extensions) +description: Update an azd extension changelog and bump its version. +--- + +# Changelog (extensions) + +You maintain release notes for **azd extensions** under `cli/azd/extensions/`. + +## Scope + +For the **target extension folder** (for example `cli/azd/extensions/microsoft.azd.demo`), update **only**: + +- `/CHANGELOG.md` +- `/version.txt` +- `/extension.yaml` (the `version:` field) + +Do not update the core CLI changelog (`cli/azd/CHANGELOG.md`). + +## Goal + +Produce a user-facing release entry for the extension and ensure the extension's version is consistent across files. + +## Process + +### 1. Identify the target extension + +1. Determine which extension is being released (folder under `cli/azd/extensions/`). +2. Confirm it contains: + - `CHANGELOG.md` + - `version.txt` + - `extension.yaml` + +### 2. Bump the version + +1. Choose the new version according to the extension's existing conventions (SemVer, and optional suffix like `-preview`). +2. Update **both**: + - `/version.txt` + - `/extension.yaml` (`version:`) + +Keep them exactly in sync. + +### 3. Prepare the changelog header + +In `/CHANGELOG.md`, add a new top entry for the new version with today's date in `YYYY-MM-DD`, matching the file's existing formatting. + +- If the changelog uses category headings (e.g., `### Features Added`), follow that style. +- If it uses simple bullet lists (no categories), keep it consistent. + +### 4. Gather commits affecting the extension + +1. Find the cutoff commit for the previous release entry, use the extension changelog history: + + ```bash + git --no-pager log -n 2 --follow -p -- /CHANGELOG.md + ``` + + Identify the commit that added the previous version section, then only consider commits newer than that cutoff. + +2. List commits newer than the cutoff: + ```bash + git --no-pager log --oneline --pretty=format:"%h (%ad)%d %s" --date=short -10 origin/main -- / + ``` + +### 5. Process changes one PR at a time (no batching) + +For each commit/PR in scope, do the full workflow (steps 1-6) before moving to the next: + +1. Extract PR number from the commit subject (`(#1234)`), or locate the PR by commit SHA. +2. Fetch PR details (owner: `Azure`, repo: `azure-dev`) using GitHub MCP. +3. Identify linked issues and fetch issue details if needed to understand user impact. +4. Decide if it belongs in the extension changelog. Exclude changes that are primarily: + - Tests or test infrastructure + - Documentation-only changes + - Pure refactors/cleanup/renames with no user impact + - CI/build/release infra changes +6. Write the changelog entry + + Add concise, user-facing bullets under the new version section. + + - Start with a verb (**Add**, **Fix**, **Update**, **Improve**). + - Describe user impact (what changes for someone using the extension). + - Include PR link when available, using the format: + - `- [[#PR]](https://github.com/Azure/azure-dev/pull/PR) Description.` + +### 6. Finalize + +1. Ensure the new changelog entry matches the extension's existing style. +2. Ensure `/version.txt` and `/extension.yaml` versions match exactly. +3. Run spellcheck on the extension changelog if it's in scope for release: + +```bash +cspell lint "/CHANGELOG.md" --relative --config cli/azd/.vscode/cspell.yaml --no-progress +``` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7f80144aa74..75628aff4f3 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -195,48 +195,6 @@ func TestMyFunction(t *testing.T) { ## Changelog updates for releases -When preparing a new release changelog, update `cli/azd/CHANGELOG.md` and `cli/version.txt`: - -### Step 1: Prepare version header -Rename any existing `## 1.x.x-beta.1 (Unreleased)` section to the version being released, without the `-beta.1` and `Unreleased` parts. Do the same for `cli/version.txt`. - -### Step 2: Gather commits -**Find cutoff commit**: -```bash -git --no-pager log --grep="Increment CLI version" --invert-grep -n 3 --follow -p -- cli/azd/CHANGELOG.md -``` -Review the diff output to find the most recent commit that added the previous version's changelog - this is the cutoff commit. Focus on the actual changelog changes in the diff instead of the commit messages themselves. - -**Get commits to process**: -```bash -git --no-pager log --oneline --pretty=format:"%h (%ad) %s" --date=short -20 origin/main -``` -Increase `-20` if needed to find the cutoff commit. `git log` shows commits in reverse chronological order (newest first). You must identify the cutoff commit and only take commits newer than (above) it. - -### Step 3: Gather context and write changelog entry -**CRITICAL INSTRUCTION: Process each commit individually and sequentially. Complete the full workflow (extract PR, fetch details, categorize, write entry, save) one entry at a time. DO NOT batch process multiple commits/PRs, skip PRs, or cut the process short due to time constraints.** - -1. **Extract PR number**: Look for `(#XXXX)` pattern in commit message -2. **Fetch PR details** using GitHub tools: owner: `Azure`, repo: `azure-dev`, pullNumber: `PR#` - - Get the GitHub handle of the PR owner, and determine whether the owner is outside the core team (handle not in `.github/CODEOWNERS`) -3. **Identify linked issues**: Scan PR details for GitHub issue references -4. **Fetch linked issue details** using GitHub tools: owner: `Azure`, repo: `azure-dev`, issue_number: `XXXX` -5. **Categorize change**: Features Added, Bugs Fixed, Other Changes -6. **Add changelog entry to CHANGELOG.md**: - - **Format**: `- [[PR#]](https://github.com/Azure/azure-dev/pull/PR#) User-friendly description.` - - **Process**: Read PR description and linked issue carefully to understand the user impact - - **Guidelines**: - - Be brief. Start with action verbs (Add, Fix, Update, etc.) and describe user impact. Follow existing changelog entries for style. - - For bugs, phrase the changelog entry in terms of the issue that was fixed when possible. Example: "Fix PowerShell 7 suggestion text not showing for service-level hooks." - - **Attribution**: For PRs from contributors outside the core team, append: " Thanks @handle for the contribution!" -7. **Exclude the following types of changes** from the changelog: - - Test-related changes and test infrastructure updates - - Documentation updates (README.md, .md files, CODEOWNERS) - - Automated dependency bumps and CVE fixes that are purely dependency updates (updates to tools like Bicep CLI, GitHub CLI should remain in the changelog) - - Internal refactoring, code cleanup, and variable renames without user impact - - Build/release infrastructure and CI/CD pipeline changes - - Changes exclusively under `cli/azd/extensions/` directory (extension-specific updates) - -### Step 4: Organize and finalize -1. **Remove empty categories** and **validate formatting** -2. **Spell check**: Run `cspell lint "cli/azd/CHANGELOG.md" --relative --config cli/azd/.vscode/cspell.yaml --no-progress` and update `.vscode/cspell-github-user-aliases.txt` if needed +When asked to prepare a release changelog, use the appropriate custom agent instructions: +- `.github/agents/changelog-core.agent.md` for core CLI releases +- `.github/agents/changelog-extension.agent.md` for extension releases From 822bfcb2b3384ae56e985e58485c700bc73e76f3 Mon Sep 17 00:00:00 2001 From: Jeffrey Chen Date: Fri, 12 Dec 2025 21:27:17 +0000 Subject: [PATCH 2/2] Use custom agent instructions for writing azd core and extension changelogs --- .github/agents/changelog-core.agent.md | 9 +++++---- .github/agents/changelog-extension.agent.md | 7 ++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/agents/changelog-core.agent.md b/.github/agents/changelog-core.agent.md index 6399a0137ad..c058c5b398a 100644 --- a/.github/agents/changelog-core.agent.md +++ b/.github/agents/changelog-core.agent.md @@ -1,9 +1,10 @@ --- -name: Changelog (core) -description: Update cli/azd release changelog and version based on merged PRs. +name: Generate changelog (azd core) +description: Update azd core release changelog and version based on merged PRs. +infer: true --- -# Changelog (core) +# Changelog (azd core) You maintain the Azure Developer CLI (azd) release changelog. @@ -61,7 +62,7 @@ For **each** commit newer than the cutoff, do this workflow fully (steps 1-6) be - CI/build/release infrastructure changes - Automated dependency bumps that are purely dependency maintenance (updates to tools like Bicep CLI, GitHub CLI can remain in the changelog) - Extension-only changes under `cli/azd/extensions/` (e.g. azure.ai.agent, microsoft.azd.demo, etc.) -6. Write the changelog entry: +6. Write the changelog entry to `CHANGELOG.md`: - Categorize into one of: `### Features Added`, `### Bugs Fixed`, `### Other Changes` - Add a bullet using the exact format: `- [[#PR]](https://github.com/Azure/azure-dev/pull/PR) User-facing description.` - Guidelines: start with a verb (**Add**, **Fix**, **Update**, **Improve**); describe user impact; keep it short; prefer bug phrasing like "Fix …". diff --git a/.github/agents/changelog-extension.agent.md b/.github/agents/changelog-extension.agent.md index 16dd7d1be2f..d049e510492 100644 --- a/.github/agents/changelog-extension.agent.md +++ b/.github/agents/changelog-extension.agent.md @@ -1,6 +1,7 @@ --- -name: Changelog (extensions) +name: Generate changelog (extensions) description: Update an azd extension changelog and bump its version. +infer: true --- # Changelog (extensions) @@ -15,7 +16,7 @@ For the **target extension folder** (for example `cli/azd/extensions/microsoft.a - `/version.txt` - `/extension.yaml` (the `version:` field) -Do not update the core CLI changelog (`cli/azd/CHANGELOG.md`). +**DO NOT** update the core CLI changelog (`cli/azd/CHANGELOG.md`) or `registry.json`. ## Goal @@ -74,7 +75,7 @@ For each commit/PR in scope, do the full workflow (steps 1-6) before moving to t - Documentation-only changes - Pure refactors/cleanup/renames with no user impact - CI/build/release infra changes -6. Write the changelog entry +6. Write the changelog entry to `CHANGELOG.md`: Add concise, user-facing bullets under the new version section.