From 4263cb04c8c2c2d0dacc291e3c2937d4e048dcf2 Mon Sep 17 00:00:00 2001
From: Mark Shust <mark@shust.com>
Date: Wed, 3 Jun 2026 10:55:18 -0400
Subject: [PATCH] docs: document GitHub Actions version convention
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a short "GitHub Actions" section to CONTRIBUTING.md covering
how to pick action versions for new and edited workflows: pin to
the latest stable major (currently v6), match what's already used
across sibling workflows, no floating refs.

Prompted by PR #112 — a new workflow shipped with checkout@v4
(Node 20, deprecated) while every other workflow in the repo was
already on @v6. Documenting the convention so it stops recurring.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CONTRIBUTING.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f073cc72..88dd5880 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,6 +70,20 @@ From a clean `develop` branch:
 
 The script handles everything: merges develop into main, runs tests, tags, pushes, creates a GitHub Release with auto-generated notes, and returns develop to sync with main. Version format is `X.Y.Z` — no `v` prefix.
 
+## GitHub Actions
+
+When adding or editing workflows under `.github/workflows/`:
+
+- **Pin third-party actions to the latest stable major.** Currently that means `actions/checkout@v6`, etc. Older majors (`@v4`, `@v5`) emit Node deprecation warnings as GitHub rolls runners forward.
+- **Stay consistent with the rest of the repo.** Before introducing a new action version, grep the existing workflows — if `actions/checkout@v6` is already in use, match it rather than picking a different major.
+- **Don't pin to floating refs** (`@main`, `@master`). Majors are stable enough; floating refs are not.
+
+A quick check:
+
+```bash
+grep -rh 'uses: actions/' .github/workflows/ | sort -u
+```
+
 ## Code Standards
 
 See [`.claude/code-standards.md`](.claude/code-standards.md) for PHP-specific conventions (strict types, constructor promotion, type declarations, etc.).