update-guidelines

# Update Guidelines ## When to Use - Syncing guideline changes from the [Azure/azure-sdk](https://github.com/Azure/azure-sdk) repo into the Copilot knowledge base - Ingesting a specific PR's guideline changes - Syncing guideline changes between two dates or two commit SHAs ## Overview The `avc db ingest-guidelines` command detects changes in the azure-sdk repo's guideline markdown files and syncs them to Cosmos DB. It compares a **base SHA** against a **target SHA** to find changed files, parses them, and upserts/deletes guidelines, examples, and memories accordingly. This skill supports three input scenarios for resolving the base and target SHAs: 1. **PR link** — Extract SHAs from a GitHub pull request 2. **Explicit SHAs** — Use the SHAs directly 3. **Date range** — Find the closest commits on `main` to the given dates **IMPORTANT:** Always run a **dry-run first** and confirm with the user before applying changes. ## Environment The user MUST specify which environment to update: **staging** or **production**. If not specified, **ask the user** — do NOT assume. This determines which Cosmos DB and App Configuration instance is modified. Always pass `--environment <env>` to the CLI commands. ## Language Filter The user may optionally specify one or more languages to narrow the ingestion scope. If languages are specified, only guideline files for those languages (plus cross-language "general" guidelines) are processed. Pass `--language <lang1> <lang2>` (or `-l <lang1> <lang2>`) to the CLI commands. Valid language names: `python`, `java`, `dotnet`, `typescript`, `golang`, `cpp`, `rust`, `ios`, `android`, `clang`. Case-insensitive aliases like `C#`, `Go`, `Swift` are also accepted. If the user does not mention specific languages, omit the flag to process all languages. --- ## Scenario 1: PR Link The user provides a GitHub PR link (e.g. `https://github.com/Azure/azure-sdk/pull/1234`). ### Step 1a: Extract the PR number Parse the PR number from the URL. ### Step 1b: Fetch PR details from GitHub API Run this command to get the base and merge commit SHAs: ```powershell Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/pulls/<PR_NUMBER>" -Headers @{ "User-Agent" = "apiview-copilot" } | Select-Object -Property @{N='base_sha';E={$_.base.sha}}, @{N='merge_commit_sha';E={$_.merge_commit_sha}}, @{N='title';E={$_.title}}, @{N='state';E={$_.state}}, @{N='merged';E={$_.merged}} | Format-List ``` - Use `base.sha` as the **base SHA** - Use `merge_commit_sha` as the **target SHA** - If `merged` is `false`, warn the user that the PR is not merged and the merge commit SHA may change ### Step 1c: Confirm with user Show the user: - PR title and state - Base SHA (first 8 chars) - Target SHA (first 8 chars) - Environment (staging or production) Ask for confirmation before proceeding. Then go to **Phase 2: Dry Run**. --- ## Scenario 2: Explicit SHAs The user provides two commit SHAs directly. Confirm with the user: - Base SHA (first 8 chars) - Target SHA (first 8 chars) - Environment (staging or production) Then go to **Phase 2: Dry Run**. --- ## Scenario 3: Date Range The user provides two dates (e.g. "April 1 to April 30", "March 15 and March 20"). ### Step 3a: Resolve dates to SHAs For each date, find the closest commit on `main` of the Azure/azure-sdk repo. Use the GitHub Commits API with the `until` parameter to find the most recent commit on or before the given date: **For the base date:** ```powershell (Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/commits?sha=main&until=<BASE_DATE>T23:59:59Z&per_page=1" -Headers @{ "User-Agent" = "apiview-copilot" })[0] | Select-Object -Property @{N='sha';E={$_.sha}}, @{N='date';E={$_.commit.committer.date}}, @{N='message';E={$_.commit.message.Split("`n")[0]}} | Format-List ``` **For the target date:** ```powershell (Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/commits?sha=main&until=<TARGET_DATE>T23:59:59Z&per_page=1" -Headers @{ "User-Agent" = "apiview-copilot" })[0] | Select-Object -Property @{N='sha';E={$_.sha}}, @{N='date';E={$_.commit.committer.date}}, @{N='message';E={$_.commit.message.Split("`n")[0]}} | Format-List ``` Replace `<BASE_DATE>` and `<TARGET_DATE>` with ISO dates (e.g. `2025-04-15`). ### Step 3b: Confirm with user The resolved commit dates may not exactly match the user's requested dates. **Always show the user what was resolved and ask for confirmation**, especially if the commit date differs from the requested date by more than a day. Show: - Requested base date → Resolved commit date and SHA (first 8 chars) and commit message - Requested target date → Resolved commit date and SHA (first 8 chars) and commit message - Environment (staging or production) Ask: "These are the closest commits to your requested dates. Proceed with dry run?" Then go to **Phase 2: Dry Run**. --- ## Phase 2: Dry Run **Always run a dry-run first.** Use a **300-second timeout** (the command can be slow due to LLM enrichment). ```powershell python cli.py db ingest-guidelines --environment <ENV> --base-sha <BASE_SHA> --target-sha <TARGET_SHA> --details [--language <LANG1> <LANG2>] ``` Include `--language` flags only if the user specified languages to filter. ### Interpreting results Read the terminal output. The command prints: - **Guidelines**: N to create, N to update, N to delete, N unchanged - **Examples**: N to create, N to update, N to delete, N unchanged - **Memories**: N to absorb, N to retain - **Errors**: any errors encountered With `--details`, the JSON output includes before/after content for each change. ### Present to user Summarize what the dry run found: - How many guidelines will be created/updated/deleted - How many examples will be created/updated/deleted - How many memories will be absorbed - Any errors - Remind them which environment this targets Ask: "Ready to apply these changes to **{environment}**?" --- ## Phase 3: Apply Only after the user confirms the dry-run results, run the actual ingestion: ```powershell python cli.py db ingest-guidelines --environment <ENV> --base-sha <BASE_SHA> --target-sha <TARGET_SHA> --apply [--language <LANG1> <LANG2>] ``` Use a **300-second timeout**. Include the same `--language` flags used in the dry run. After completion, report the final counts to the user. --- ## Gotchas - **Always dry-run first.** Never skip the dry run. The ingestion modifies Cosmos DB and App Configuration. - **Environment matters.** Staging and production have separate Cosmos DB instances. Double-check with the user. - **Large diffs are slow.** If many files changed, the LLM enrichment step can take several minutes. Use `--details` only on dry runs to inspect changes; omit it on the real run to save time. - **Language filter.** Use `--language` to scope to specific languages when debugging or testing. The filter also includes cross-language ("general") guidelines automatically. - **Merged PRs only.** If a PR is not yet merged, the merge commit SHA is provisional and may change. Warn the user.