From 04ccc77a13da34265aaf1787826c8ccc8327a6d0 Mon Sep 17 00:00:00 2001
From: "Hel.Isa" <learnhub@helr.dev>
Date: Sat, 2 May 2026 18:09:34 -0400
Subject: [PATCH] Prepare v2.0.1 release

---
 README.md                  |  2 ++
 docs/release-management.md | 65 +++++++++++++++++++++++++++++++++-----
 2 files changed, 59 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index e297e79..d254ce4 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,8 @@ Advanced teams can call individual reusable workflows directly when they need cu
 
 Approved consumers should pin to immutable release tags such as `v2.0.1`. Keep the workflow reference and `gate_ref` aligned so the reusable workflow and dashboard assets come from the same release.
 
+Users who want the latest compatible v2 release can use the `v2` branch with `@v2` and `gate_ref: v2`, but exact tags are safer for production and external-company onboarding.
+
 ## Local Usage (where applicable)
 - Aggregation script:
   ```bash
diff --git a/docs/release-management.md b/docs/release-management.md
index ed1157b..d46edfe 100644
--- a/docs/release-management.md
+++ b/docs/release-management.md
@@ -4,18 +4,19 @@ Security Gate consumers should pin to stable release tags. This keeps approved r
 
 ## Tag Strategy
 
-Use semantic version tags for immutable releases:
+Use semantic version tags for immutable releases, plus the `v2` branch for users who want the latest compatible version:
 
 - `v2.0.1`: exact release, recommended for approved consumers
 - `v2.0.2`: patch release for compatible fixes
 - `v2.1.0`: minor release for compatible features or new optional inputs
+- `v2`: moving branch for the latest compatible v2 release
 - `v3.0.0`: breaking release
 
-The `v2` branch may continue to track active v2 development. Do not ask approved consumers to depend on `@v2` unless they explicitly accept moving updates.
+Do not create a `v2` tag while a `v2` branch exists. Keep `v2` as the latest compatible branch.
 
 ## Consumer Pinning
 
-Approved repositories should pin the reusable workflow and dashboard assets to the same release:
+Approved repositories should pin the reusable workflow and dashboard assets to the same exact release when they need predictable builds:
 
 ```yaml
 jobs:
@@ -34,6 +35,46 @@ Keep these aligned:
 - workflow reference: `@v2.0.1`
 - dashboard/script reference: `gate_ref: v2.0.1`
 
+## Latest Compatible Version
+
+Users who want automatic compatible updates can use the moving `v2` branch:
+
+```yaml
+jobs:
+  security-gate:
+    name: Security Gate
+    uses: hel-isa/security-gate/.github/workflows/reusable-security-gate.yml@v2
+    with:
+      mode: audit
+      semgrep_config: auto
+      repo_name: ${{ github.repository }}
+      gate_ref: v2
+```
+
+Use this only when the consumer accepts receiving patch and minor v2 updates automatically. For production or external-company onboarding, exact tags such as `v2.0.1` are safer.
+
+## Pull Request Release Flow
+
+Use a pull request for every release. The release PR should include:
+
+- `VERSION` updated to the next version
+- `CHANGELOG.md` updated with the release notes
+- examples and docs updated to the new recommended exact tag
+- workflow validation results
+
+Suggested branch and PR flow:
+
+```bash
+git checkout v2
+git pull origin v2
+git checkout -b release/v2.0.1
+git add .
+git commit -m "Prepare v2.0.1 release"
+git push origin release/v2.0.1
+```
+
+Then open a PR from `release/v2.0.1` into `v2`.
+
 ## Release Checklist
 
 1. Update `VERSION`.
@@ -45,21 +86,29 @@ Keep these aligned:
    PYTHONPYCACHEPREFIX=/private/tmp/security-gate-pycache python3 -m py_compile scripts/aggregate_results.py scripts/generate_dashboard.py
    ```
 
-4. Commit the release changes.
-5. Create an annotated tag:
+4. Open and merge the release PR into `v2`.
+5. Pull the merged `v2` branch:
+
+   ```bash
+   git checkout v2
+   git pull origin v2
+   ```
+
+6. Create an annotated exact release tag:
 
    ```bash
    git tag -a v2.0.1 -m "Release v2.0.1"
    ```
 
-6. Push the branch and tag:
+7. Push the exact tag:
 
    ```bash
-   git push origin v2
    git push origin v2.0.1
    ```
 
-7. Ask one approved repository to run the audit template before announcing the release more broadly.
+8. Ask one approved repository to run the audit template before announcing the release more broadly.
+
+If you do not want a moving latest branch, ask all consumers to use exact tags only.
 
 ## Compatibility Promise