From e03450f09b4426d136af39256d1fb9d46dc579a5 Mon Sep 17 00:00:00 2001 From: Alex Frankel Date: Tue, 12 May 2026 18:54:43 -0700 Subject: [PATCH] =?UTF-8?q?Fix=20doc-drift=20in=20contribution=20guide:=20?= =?UTF-8?q?/verify=20=E2=86=92=20/validate,=20drop=20nonexistent=20summari?= =?UTF-8?q?ze-pr.yml,=20correct=20Bicep=20azuredeploy.json=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Maintainer command is /validate, not /verify (7 occurrences updated). - Remove §3 "Summarize PR (summarize-pr.yml)" — that workflow doesn't exist. The AI summary is a job inside ValidateSampleDeployments.yml and fires automatically alongside /validate; folded a one-line mention into §2. - Update "Two workflows" instead of "Three workflows" in section opener. - Drop step 7 from Contributor Workflow Summary (no /summarize command). - Bicep section: azuredeploy.json should be included in the PR (compiled output of main.bicep). The "Deploy to Azure"/"Visualize" buttons link directly to it. Earlier wording said it would be auto-generated on merge, which is the design intent but doesn't reflect what works today. --- 1-CONTRIBUTION-GUIDE/README.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/1-CONTRIBUTION-GUIDE/README.md b/1-CONTRIBUTION-GUIDE/README.md index 325397e9ae6c..9f59325ce1f5 100644 --- a/1-CONTRIBUTION-GUIDE/README.md +++ b/1-CONTRIBUTION-GUIDE/README.md @@ -114,7 +114,7 @@ The target scope itself should not be created by the sample unless the creation We encourage new samples to be written directly in [Bicep](https://docs.microsoft.com/azure/azure-resource-manager/bicep/overview) and encourage existing samples to be converted to support Bicep. 1. The bicep file must be named **main.bicep** -1. The **azuredeploy.json** must **not** be included in the PR as it will be built automatically when the sample is merged. +1. The **azuredeploy.json** (compiled output of `main.bicep`) should be included in the PR alongside `main.bicep`. The "Deploy to Azure" / "Visualize" buttons in each sample's README link directly to `azuredeploy.json`, so it must exist in the sample folder. Compile locally with `az bicep build --file main.bicep --outfile azuredeploy.json` before submitting. 1. The [**README.md**](sample-README.md) file must include a link to the bicep badge 1. The parameter file must still be named **azuredeploy.parameters.json** @@ -309,7 +309,7 @@ If only one is provided it will be used for testing in all clouds. ## GitHub Actions CI -We have automated template validation through GitHub Actions. Three workflows run as part of the PR process: +We have automated template validation through GitHub Actions. Two workflows run as part of the PR process: ### 1. Validate Sample Contributions (`validate-samples.yml`) @@ -323,17 +323,15 @@ This workflow runs automatically on every PR to `master`. It validates: ### 2. Validate ARM Deployments (`ValidateSampleDeployments.yml`) -This workflow is triggered by a repo maintainer posting a `/verify` comment on your PR. It validates the deployment results you provided in `testResult`: +This workflow is triggered by a repo maintainer posting a `/validate` comment on your PR. It validates the deployment results you provided in `testResult`: + Verifies that the `correlationId` and `deploymentName` exist in the Azure deployment logs + Confirms the deployment `executionStatus` is `Succeeded` + Computes a `templateHash` from the template file in the PR and verifies it matches the hash recorded in the deployment logs — this ensures the template you deployed is the same one in the PR -The `/verify` command can only be run after `validate-samples.yml` passes. +The workflow also posts an AI-generated summary comment on the PR alongside the deployment validation, to help reviewers understand what the sample does. -### 3. Summarize PR (`summarize-pr.yml`) - -Triggered by a `/summarize` comment on a PR, this workflow generates an AI-powered summary of the sample changes to help reviewers. +The `/validate` command can only be run after `validate-samples.yml` passes. ### Contributor Workflow Summary @@ -342,8 +340,7 @@ Triggered by a `/summarize` comment on a PR, this workflow generates an AI-power 3. **Capture** the deployment results: `correlationId`, `deploymentName`, and `templateFileName` 4. **Update** `metadata.json` with the `testResult` section containing the deployment results 5. **Submit** your PR — `validate-samples.yml` runs automatically -6. A **maintainer** runs `/verify` to validate your deployment results against Azure logs -7. Optionally, a reviewer runs `/summarize` for an AI-generated PR summary +6. A **maintainer** runs `/validate` to validate your deployment results against Azure logs ### Parameters File Placeholders @@ -489,9 +486,9 @@ Common failure reasons: + **metadata.json missing `testResult`:** You must deploy your template and add the deployment results to metadata.json before submitting the PR. See [testResult](#testresult) for the required format. + **Template changed but metadata.json not updated:** If you modify any `.bicep` or `.json` file, you must re-deploy and update the `testResult` section with fresh deployment results. -+ **`/verify` fails with "No ADX record found":** The `correlationId` or `deploymentName` in your metadata.json does not match any Azure deployment log. Double-check the values are correct. -+ **`/verify` fails with templateHash mismatch:** The template you deployed is different from the template in your PR. Re-deploy the exact template from your PR branch and update the deployment results. -+ **`/verify` fails with executionStatus not Succeeded:** Your deployment did not succeed. Fix the template, re-deploy, and update the deployment results. ++ **`/validate` fails with "No ADX record found":** The `correlationId` or `deploymentName` in your metadata.json does not match any Azure deployment log. Double-check the values are correct. ++ **`/validate` fails with templateHash mismatch:** The template you deployed is different from the template in your PR. Re-deploy the exact template from your PR branch and update the deployment results. ++ **`/validate` fails with executionStatus not Succeeded:** Your deployment did not succeed. Fix the template, re-deploy, and update the deployment results. Keep in mind that depending on the resources allocated, it can take a few minutes for the CI system to cleanup provisioned resources.