From 88fccc6c496f74b840d5e830337f8cfde268cfbc Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 6 Apr 2026 20:01:13 +0000
Subject: [PATCH] docs: update CONTRIBUTING.md for Go 1.26.1, playback tests,
 and Go version management

- Update Go prerequisite from 1.26 to 1.26.1 (Azure/azure-dev#7488)
- Document new `mage playbackTests` target added as preflight step 8 (Azure/azure-dev#7506)
- Add Go Version Management section documenting Update-GoVersion.ps1 script
  and validate-go-version CI workflow (Azure/azure-dev#7488)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 cli/azd/CONTRIBUTING.md | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/cli/azd/CONTRIBUTING.md b/cli/azd/CONTRIBUTING.md
index da3feeb05d6..88096714089 100644
--- a/cli/azd/CONTRIBUTING.md
+++ b/cli/azd/CONTRIBUTING.md
@@ -20,7 +20,7 @@ In general, to make contributions a smooth and easy experience, we encourage the
 
 Prerequisites:
 
-- [Go](https://go.dev/dl/) 1.26
+- [Go](https://go.dev/dl/) 1.26.1
 
 Build:
 
@@ -49,13 +49,20 @@ automatically adds that directory to your PATH if it isn't already there.
 
 ### Preflight (all quality checks)
 
-Run all pre-commit checks (formatting, copyright headers, linting, spell check, build, unit tests) in one command:
+Run all pre-commit checks (formatting, copyright headers, linting, spell check, build, unit tests, and playback tests) in one command:
 
 ```bash
 cd cli/azd
 mage preflight
 ```
 
+To run only the playback tests (functional tests replayed from recorded cassettes, no Azure credentials needed):
+
+```bash
+cd cli/azd
+mage playbackTests
+```
+
 Run tests:
 
 ```bash
@@ -91,6 +98,16 @@ CI enforces this check — PRs with pending `go fix` suggestions will fail the l
 
 > Note: On Windows you may need to add `C:\Program Files\Git\usr\bin` to `%PATH%`
 
+### Go Version Management
+
+When bumping the Go version across the repository, use the `Update-GoVersion.ps1` script instead of manually editing each file. It updates all `go.mod` files, Dockerfiles with `golang:` base images, and the ADO pipeline template in one command:
+
+```powershell
+pwsh eng/scripts/Update-GoVersion.ps1 -NewVersion 1.27.0
+```
+
+CI enforces version consistency via the `validate-go-version` workflow, which runs on PRs that touch `go.mod`, `Dockerfile`, or the ADO setup template. The source of truth is `cli/azd/go.mod`.
+
 ### Debugging (with VSCode)
 
 If you don't have a preferred editor for Go code, we recommend [Visual Studio Code](https://code.visualstudio.com/Download).