Skip to content

Fix doc-drift in contribution guide post Apr–May 2026 CI rewrite #14755

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alex-frankel wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix doc-drift in contribution guide post Apr–May 2026 CI rewrite #14755

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 9 additions & 12 deletions 1-CONTRIBUTION-GUIDE/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down Expand Up @@ -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`)

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down
Loading