changelog-generation

WORKFLOW SKILL — Generates release changelog entries for azd core or extensions.

INVOKES: GitHub MCP tools, git CLI, gh CLI, cspell CLI, ask_user.

Workflow

Step 1 — Determine Scope

Auto-detect scope from the current working directory:

1. Check if the cwd is inside a cli/azd/extensions/<name>/ directory.
   • If yes → infer extension scope, with <name> as the target extension.
   • If no → infer core scope.

2. Present the detected scope to the user for confirmation via ask_user:

   I detected you're in <cwd>, so I'll generate changelog for [core azd CLI | extension <name>]. Is that correct?

   Choices:

   • Yes, that's correct (Recommended)
   • No, switch to [core | an extension]
3. If extension and not auto-detected: list folders under cli/azd/extensions/ and ask the user to select the target.
4. After extension scope is confirmed (whether auto-detected or manually selected), verify the target extension contains CHANGELOG.md, version.txt, and extension.yaml. If any are missing, stop and list which files are absent.

Step 2 — Find Cutoff & List Commits

Per references/scope-rules.md § Commit Discovery.

1. Inspect changelog git history to find the cutoff commit SHA.
2. List commits from cutoff to origin/main (extensions: scoped to extension path).
3. If >30 commits in the range, display the count and ask the user if they want to see the full list or proceed directly to PR processing.
4. Present the commit list to the user. This is a manual pre-filter opportunity — ask if any commits should be explicitly included or excluded before automated processing.

Step 3 — Process Each PR

For each commit remaining after the user's pre-filter in Step 2, extract its PR number using the rules in references/pr-processing.md (each commit maps to exactly one canonical PR). Apply the automated exclusion rules and complete the full sub-workflow before moving to the next. Do not batch or abbreviate — and do not skip a PR unless an explicit error-handling rule applies and the user confirms skipping.

Track processed PR numbers. If a PR number was already processed in a previous commit, skip it. If the commit subject starts with Revert, skip both the revert commit and note the original PR number to avoid including the reverted change.

Per references/pr-processing.md:

1. Extract PR number from commit subject ((#1234)) or locate by SHA.
2. Fetch PR details via GitHub MCP (owner: Azure, repo: azure-dev).
3. Detect external contributors per references/pr-processing.md § External Contributor Detection.
4. Fetch linked issues from the PR body when relevant to understanding user impact.
5. Apply exclusion rules per references/pr-processing.md § Exclusion Rules.
6. Cross-release deduplication: before writing an entry, search all existing sections in CHANGELOG.md for the PR number and any linked issue numbers from the PR body. If a match is found in a prior release, skip the entry and log a note. Entries must always use PR numbers (pull/NNNN), not issue numbers (issues/NNNN), to maintain consistency with the [[#PR]] format convention.
7. Categorize and draft the entry per references/pr-processing.md § Category Classification and § Entry Format.

Step 4 — Determine Version & Update Files

Files to update (core): cli/azd/CHANGELOG.md, cli/version.txt, cli/azd/pkg/azdext/version.go Files to update (extension): <extension>/CHANGELOG.md, <extension>/version.txt, <extension>/extension.yaml

For version derivation rules, see references/scope-rules.md § Version Files.

• Core: use the version specified in the triggering issue or user request when explicit. Otherwise, assess the included changes and select an appropriate patch or minor version. Replace the top unreleased header with the selected version and today's date, without adding a new unreleased placeholder above it. Update cli/version.txt and cli/azd/pkg/azdext/version.go (Version constant) to the released version.
• Extension: use the version specified in the triggering issue or user request when explicit. Otherwise, select the next version by following the extension's own versioning convention from its changelog history and assessing the included changes. Update both version.txt and extension.yaml — they must match exactly.

After selecting the version, create or update the release header and write the drafted entries under it.

Step 5 — Assemble & Review

1. Remove empty category sections — scan the new release entry and delete any ### <Category> heading that has no bullet entries beneath it (i.e., the next line is blank followed by another ### heading or ## heading or end of section). This is mandatory — never leave empty ### Breaking Changes, ### Features Added, ### Bugs Fixed, or ### Other Changes sections in the final output.
2. For extensions using flat bullet lists (no category headings), match the existing style.
3. Validate PR links: verify that every - bullet under a category heading contains a [[#NNNN]] link. If any entry is missing a link, flag it and require either adding the PR reference or explicitly justifying the omission. When a single large PR warrants multiple changelog bullets, each must reference the same PR number.
4. Cross-reference commit range (forward): verify every [[#NNNN]] PR number against the commit list from Step 2. Flag any PR that does not appear in the commit range — it may be a duplicate from a prior release or an incorrectly attributed entry.
5. Reverse cross-reference (coverage check): for every commit in the Step 2 range, verify it is either (a) included in the changelog entry, or (b) excluded with a documented reason (test-only, docs-only, CI, extension-only, dependency bump, duplicate PR, alpha-gated, or cross-release dedup). Present a summary table to the user listing each commit's PR number, title, and disposition (included / excluded with reason). Flag any commit that is neither included nor has a clear exclusion reason — these are potential misses that require explicit user confirmation before proceeding.

6. Present the complete changelog entry to the user for review via ask_user.

   Choices:

   • Approve — accept and proceed to spell check
   • Edit — provide feedback for revisions (loop back). If the revisions change the included entries, reassess the version and update the release header and version files in place before presenting again.
   • Abort — cancel the entire workflow

Step 6 — Spell Check

cspell lint "<changelog-path>" --relative --config "$(git rev-parse --show-toplevel)/cli/azd/.vscode/cspell.yaml" --no-progress

If new names or handles trigger errors, add them to .vscode/cspell-github-user-aliases.txt.

Core Release Tracking Handoff

Changelog preparation is not release publication. Once the core changelog PR exists, offer the azd release canvas as the next step when canvas support is available. For canvas-initiated preparation, tracking already exists: return the PR link so the driver can link it inside that release. Otherwise, the driver can select New release, create tracking with the version only, and link the existing PR there. Publishing follows after the PR merges. Ask before opening the canvas; do not create tracking issues or queue a pipeline implicitly as part of changelog generation. If canvas support is not available, link the guide instead. Extension releases do not use this core canvas.

Error Handling

• GitHub MCP unavailable → fall back to gh CLI: gh pr view {number} --json title,author,body,labels,files
• No new commits since cutoff → inform user, no changelog entry needed
• PR deleted or inaccessible → log warning, skip with user confirmation
• cspell not installed → warn, skip spell check, note in summary
• Extension missing required files → stop, list which files are missing
• Version mismatch between version.txt and extension.yaml → warn, ask which is correct
• Cannot determine cutoff → ask user for the cutoff commit SHA or previous release version