From 653586eb2af3c7b1476fb6551c65a94d36381157 Mon Sep 17 00:00:00 2001 From: btardif Date: Fri, 28 Aug 2026 08:48:36 -0700 Subject: [PATCH 1/2] Add Azure CLI App Service blog skill Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../azure-cli-app-service-blog/SKILL.md | 91 ++++++++++++ .../references/article-contract.md | 95 ++++++++++++ .../references/release-research.md | 140 ++++++++++++++++++ 3 files changed, 326 insertions(+) create mode 100644 .github/skills/azure-cli-app-service-blog/SKILL.md create mode 100644 .github/skills/azure-cli-app-service-blog/references/article-contract.md create mode 100644 .github/skills/azure-cli-app-service-blog/references/release-research.md diff --git a/.github/skills/azure-cli-app-service-blog/SKILL.md b/.github/skills/azure-cli-app-service-blog/SKILL.md new file mode 100644 index 0000000000..08aaef07f7 --- /dev/null +++ b/.github/skills/azure-cli-app-service-blog/SKILL.md @@ -0,0 +1,91 @@ +--- +name: azure-cli-app-service-blog +description: Generate and stage Azure App Service Team Blog posts from Azure CLI monthly releases. Use when asked to audit an Azure CLI version or month, identify App Service changes, enrich release content from the product-planning board, or draft an App Service Azure CLI release post. +--- + +# Azure CLI App Service Blog + +Generate a factual, customer-focused App Service Team Blog post for one or more Azure CLI releases. Research the exact release boundary, classify PRs using the Azure CLI title convention, enrich customer framing from product planning, verify every shipped claim, write the post, and stage it for review. + +Read these references before starting: + +- [Release research](references/release-research.md) +- [Article contract](references/article-contract.md) + +## Required inputs and defaults + +- Accept a release version such as `2.90`, `2.90.0`, or a month such as `2026/08`. +- Normalize monthly versions to `X.Y.0`. +- If given a month, resolve its monthly release from the official Azure CLI release notes. Do not substitute a later servicing patch unless the user requests it. +- Use `Byron Tardif` as `author_name` unless the user specifies another author. +- Work only in the current App Service Blog repository and preserve unrelated staged or unstaged changes. + +## Non-negotiable publication rules + +1. **Keep the article App Service-only.** + - Include customer behavior under `az webapp` and `az appservice`. + - Exclude `az functionapp`, Function Apps, Flex Consumption, `az logicapp`, and Logic Apps from both the article and examples. + - A PR touching the App Service command module is not sufficient if its customer surface belongs to another service. + +2. **Require the PR title marker.** + - `[App Service]` or `[AppService]` means customer-facing and eligible for verification. + - `{App Service}` or `{AppService}` means non-customer-facing. Keep it in the internal ledger and exclude it from the article. + - Exclude unmarked PRs and PRs marked for another service. Flag them in the ledger instead of silently promoting them. + - The marker is necessary, not sufficient. Verification can still block a customer-facing PR. + +3. **Prove release inclusion.** + - The PR's merged commit must be present in the target release tag. + - Confirm the item against the target tag's `src/azure-cli/HISTORY.rst`. + - Never use milestone assignment, merge date, PR state, or release-note wording alone as proof. + +4. **Treat pinned public implementation as the shipping authority.** + - Verify help, parameters, implementation, and tests at the target tag. + - Treat PR descriptions and planning-board statements as intent, not proof. + - Withhold a claim when tagged source, tests, SDK models, platform documentation, or public availability disagree. + - State preview status, operating-system scope, regional rollout, platform dependencies, and breaking changes explicitly. + +5. **Use private planning context safely.** + - Search `coreai-microsoft/azure-app-service` by command, parameter, property, and customer outcome. + - Use problem statements and “why it matters” material to strengthen customer framing. + - Treat “We need to” statements and timeline comments as desired or tentative behavior until public evidence confirms shipment. + - Never put private issue links, internal system links, private quotations, or unshipped roadmap details in the public post. + - Keep PM, workstream, SME, and reviewer discoveries in the private evidence ledger. + +6. **Use canonical terminology.** + - Always write `SCM (Kudu)`. + - Never write `KuduLite`, `Kudu+`, or standalone `Kudu` in prose. + - Do not alter literal command names, API paths, settings, or quoted output that legitimately contain another form. + +## Workflow + +1. Resolve the target and previous monthly release tags, immutable commit SHAs, and official release date. +2. Build a bounded candidate inventory from the tag comparison, tagged history, and PR metadata. +3. Apply title-marker and App Service command-scope filters. +4. Search the planning board only for surviving customer-facing candidates. +5. Verify every candidate against tag-pinned source, tests, and contemporaneous public documentation. +6. Record include, exclude, and blocked decisions in a private evidence ledger. +7. If no verified App Service changes survive, do not create a post. Report that the release produced no article. +8. Group related changes by customer outcome and draft the article using the article contract. +9. Open the repository Markdown for review when an editor surface is available. +10. Re-read the file from disk after review because user edits may have changed it. +11. Validate and stage only the generated post. Do not commit, push, or create a pull request unless explicitly requested. + +## Research stopping rule + +Do not perform open-ended PR archaeology. Stop when all of these are true: + +- Every App Service history entry maps to a title-marked PR. +- Every mapped PR has an include, exclude, or blocked decision. +- Every included claim has tag-pinned implementation or test evidence. +- Relevant planning matches have been classified as exact, partial, weak, or none. +- Known documentation or rollout conflicts are recorded. + +## Expected handoff + +Provide: + +1. The staged post path, or a clear no-post decision. +2. A compact ledger of included, excluded, and blocked PRs. +3. Material rollout, preview, breaking-change, or evidence caveats. + +Keep the public article free of research notes and private planning references. diff --git a/.github/skills/azure-cli-app-service-blog/references/article-contract.md b/.github/skills/azure-cli-app-service-blog/references/article-contract.md new file mode 100644 index 0000000000..609f65ab60 --- /dev/null +++ b/.github/skills/azure-cli-app-service-blog/references/article-contract.md @@ -0,0 +1,95 @@ +# Article contract + +## Filename and front matter + +Use the official Azure CLI release-notes date: + +```text +_posts/YYYY-MM-DD-azure-cli-X-YY-app-service-updates.md +``` + +For a monthly `X.Y.0` release, omit the patch component from the slug but keep the full version in the title. + +Start with: + +```yaml +--- +title: "What's new for Azure App Service in Azure CLI X.Y.Z" +author_name: "Byron Tardif" +toc: true +toc_sticky: true +--- +``` + +Do not repeat the title as an H1 in the body. + +## Opening + +- Link the first body mention of `Azure CLI X.Y.Z` to that version's section in the Microsoft Learn Azure CLI release notes. +- Use one or two information-dense paragraphs that identify the major customer outcomes, breaking changes, and important scope. +- Do not add a closing `## Summary`; strengthen the introduction instead. +- Do not link to articles or documentation that did not exist on the post's release date. + +Example: + +```markdown +[Azure CLI X.Y.Z](https://learn.microsoft.com/cli/azure/release-notes-azure-cli#month-dd-yyyy) adds ... +``` + +## Body + +- Organize H2 sections by customer outcome, not by PR number or implementation file. +- Use benefit-first, sentence-style headings. +- Group closely related fixes into one section. +- Explain what changed, why it matters, how to use it, and material limitations. +- Use short, verified `bash` examples with placeholders such as `` and ``. +- State breaking changes before migration guidance. +- Mark preview commands and parameters explicitly. +- Preserve Linux-only, Windows-only, slot, region, SKU, and rollout boundaries. +- Distinguish “request accepted” from operation completion when commands are asynchronous. +- Use `SCM (Kudu)` for every prose reference. +- Exclude Function Apps, Flex Consumption, and Logic Apps. +- Do not expose private planning links or internal terminology. + +Add first-party Microsoft Learn links when they materially help the reader and were public by the article date. Do not create feature-specific mandatory links from one-off editorial feedback. + +## Release section + +End the article with: + +````markdown +## Get the release + +Run `az upgrade` to install the latest available Azure CLI release, then verify the installed version: + +```bash +az upgrade +az version +``` +```` + +Do not add a summary after this section. + +## Review and staging + +Before staging: + +1. Re-read the file from disk after editor or canvas review. +2. Confirm the filename date matches the official release-notes heading. +3. Confirm the title and release-notes link use the same version. +4. Confirm every published PR uses a customer-facing App Service marker. +5. Confirm no Function App, Flex Consumption, or Logic Apps content remains. +6. Confirm prose contains only `SCM (Kudu)`, not standalone variants. +7. Confirm there is no `## Summary`. +8. Confirm code examples use tag-verified options and values. +9. Run `git diff --check`. +10. Run the repository's existing Jekyll validation only when its dependencies are already available. Do not install Ruby dependencies from an unapproved source. + +Stage only the generated post: + +```text +git add -- _posts/YYYY-MM-DD-azure-cli-X-YY-app-service-updates.md +git diff --cached --check +``` + +Do not overwrite or unstage unrelated user changes. Do not commit, push, or create a pull request unless requested. diff --git a/.github/skills/azure-cli-app-service-blog/references/release-research.md b/.github/skills/azure-cli-app-service-blog/references/release-research.md new file mode 100644 index 0000000000..ec5b77aef0 --- /dev/null +++ b/.github/skills/azure-cli-app-service-blog/references/release-research.md @@ -0,0 +1,140 @@ +# Release research + +Use authenticated GitHub tools or `gh`. Prefer structured API responses and exact tag boundaries over broad web search. + +## 1. Resolve the release + +Use these sources: + +- Azure CLI releases: `Azure/azure-cli` +- Azure CLI release notes source: + `MicrosoftDocs/azure-docs-cli/docs-ref-conceptual/Latest-version/release-notes-azure-cli.md` + +For the target and previous monthly release: + +1. Record the official version and the date heading from the release notes. +2. Resolve both tag refs to immutable commit SHAs. +3. Record the exact base-exclusive, target-inclusive boundary. +4. Treat servicing releases such as `X.Y.1` separately from the monthly `X.Y.0` release. + +Useful commands: + +```text +gh release view azure-cli-X.Y.Z --repo Azure/azure-cli --json name,tagName,publishedAt,url +gh api repos/Azure/azure-cli/git/ref/tags/azure-cli-X.Y.Z +gh api repos/Azure/azure-cli/compare/azure-cli-PREV...azure-cli-TARGET +``` + +Release tags can diverge because of servicing commits. When they do: + +- Use the target tag's App Service `HISTORY.rst` section as the candidate index. +- Verify each candidate's merged commit is contained in the target tag. +- Ensure the commit was not already contained in the previous monthly tag. +- Do not infer inclusion from a three-dot comparison alone. + +## 2. Discover candidates + +Search the target tag's App Service history and the bounded comparison for: + +- `App Service` +- `AppService` +- `webapp` +- `appservice` +- `Microsoft.Web` + +Search Function and Logic App terms only to identify and explicitly exclude them. + +For each PR, collect: + +| Field | Purpose | +|---|---| +| PR number and exact title | Title-marker classification | +| Merge commit | Tag containment | +| Contributor | Reviewer or acknowledgment context | +| Changed paths | Command-module relevance | +| HISTORY entries | Public release-note mapping | +| Command and parameters | Customer-facing surface | +| Help examples | Safe article examples | +| Tests | Shipped behavior and edge cases | + +Retrieve focused metadata: + +```text +gh pr view PR --repo Azure/azure-cli --json number,title,body,url,author,mergedAt,mergeCommit,files +``` + +Do not trust milestones as release boundaries. A PR can be assigned to one month and ship in another, or remain unmerged. + +## 3. Apply classification + +Use this order: + +1. Is the merged commit in the target tag and absent from the previous monthly tag? +2. Does the title contain an explicit App Service marker? +3. Is the marker square-bracket customer-facing or brace-marked non-customer-facing? +4. Is the customer command actually `az webapp` or `az appservice`? +5. Does tag-pinned source show the claimed behavior? + +Possible decisions: + +- **Include**: customer-facing, in scope, tag-contained, and verified. +- **Exclude — marker**: brace-marked, unmarked, or another service. +- **Exclude — scope**: Function Apps, Flex Consumption, Logic Apps, or unrelated command surface. +- **Exclude — boundary**: not in the target tag or already in the previous tag. +- **Blocked**: eligible marker and boundary, but evidence conflicts or functionality is unsafe to claim. + +## 4. Enrich from product planning + +Search `coreai-microsoft/azure-app-service` using the exact command, parameter, property, and customer outcome. Avoid downloading the entire board. + +Capture privately: + +- Workstream and PM +- Problem statement +- Why the change matters +- Customer gaps +- “We need to” goals +- Dependencies +- Timeline comments +- Potential SMEs or reviewers + +Classify each match: + +- **Exact**: same command/property and shipped outcome +- **Partial**: same problem, but the release implements only part of the requested outcome +- **Weak**: adjacent context only +- **None** + +Only exact or carefully bounded partial matches should shape the article. Never turn a planning goal into a release claim. + +## 5. Verify claims + +At the target tag, inspect: + +1. `_help.py` for examples and documented limitations. +2. `_params.py` for exact option names, aliases, enums, preview metadata, and defaults. +3. `commands.py` for registration, preview, and deprecation metadata. +4. Implementation files for actual behavior and error handling. +5. Tests and recordings for supported boundaries and rollout behavior. +6. Dependency pins and SDK models when a parameter relies on newly generated properties. + +Then compare with contemporaneous public Microsoft documentation. A later `azure-cli-latest` page is not immutable evidence for an older release. + +Block or narrow claims when: + +- Public product documentation disagrees with CLI release notes. +- A platform endpoint or feature is still rolling out. +- The pinned SDK cannot serialize the new property. +- Tests prove only discovery or acceptance, not completion or availability. +- A release note overstates what implementation returns. + +Examples in the article must come from tag-pinned help, tests, or implementation. Never invent a plausible CLI option. + +## 6. Build the private ledger + +Use a compact table: + +| PR | Marker | Scope | Decision | Public evidence | Planning match | Caveat | +|---|---|---|---|---|---|---| + +Do not write the ledger into `_posts`. Keep it in the response or session artifacts. From da7f01af9322dfeffba9c96a7a9adf930fd6e446 Mon Sep 17 00:00:00 2001 From: Byron Tardif <4119816+btardif@users.noreply.github.com> Date: Fri, 28 Aug 2026 10:28:32 -0700 Subject: [PATCH 2/2] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/release-research.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/skills/azure-cli-app-service-blog/references/release-research.md b/.github/skills/azure-cli-app-service-blog/references/release-research.md index ec5b77aef0..a30d986dc9 100644 --- a/.github/skills/azure-cli-app-service-blog/references/release-research.md +++ b/.github/skills/azure-cli-app-service-blog/references/release-research.md @@ -19,11 +19,13 @@ For the target and previous monthly release: Useful commands: -```text +~~~text gh release view azure-cli-X.Y.Z --repo Azure/azure-cli --json name,tagName,publishedAt,url +# Tag refs may be annotated; if the ref object's type is "tag", dereference it via /git/tags/{sha} to get the commit SHA. gh api repos/Azure/azure-cli/git/ref/tags/azure-cli-X.Y.Z +gh api repos/Azure/azure-cli/git/tags/ gh api repos/Azure/azure-cli/compare/azure-cli-PREV...azure-cli-TARGET -``` +~~~ Release tags can diverge because of servicing commits. When they do: