/generating-release-guides

name: ring:generating-release-guides
description: "Generating an internal Operations-facing update/migration guide from the git diff between two refs, documenting per-change client impact, deploy ordering, monitoring, and rollback notes in English, pt-br, or both. Use when preparing a version release or recording what changed for the Ops team. Runs read-only by default and previews before writing. Skip with no git repo or a trivial single-file change."

Release Guide — Ops Update Guide Generator

When to use

• Preparing to release a new version
• Need to document what changed between refs
• Creating operational update guide
• Communicating version updates to Ops team

Skip when

• No git repository available
• Single file change (too small for formal guide)
• Customer-facing release notes only (use simpler template)

Inputs

• `BASE_REF` (string, required): e.g. `main`, `v1.0.0`
• `TARGET_REF` (string, required): e.g. `HEAD`, `v1.1.0`
• `VERSION` (string, optional): auto-detected from tags if not provided
• `LANGUAGE` (enum, optional, default `en`): `en`, `pt-br`, `both`
• `MODE` (enum, optional, default `STRICT_NO_TOUCH`): `STRICT_NO_TOUCH`, `TEMP_CLONE_FOR_FRESH_REFS`

Produce an **internal** Operations-facing update/migration guide from git diff analysis.

Safety Modes

**STRICT_NO_TOUCH (default):** Read-only git commands only. Forbidden: `fetch`, `pull`, `push`, `checkout`, `switch`, `reset`, `commit`, `merge`, `rebase`. If ref doesn't exist locally → STOP and suggest TEMP_CLONE mode.

**TEMP_CLONE_FOR_FRESH_REFS:** Clone to temp dir, fetch refs there, run all analysis in clone, cleanup after. Never touches current repo.

Process

Step 0: Execution Location

Determine mode. In TEMP_CLONE mode, create isolated clone before proceeding.

Step 1: Resolve Refs

git rev-parse --verify BASE_REF^{commit}   # verify both refs exist
git rev-parse --verify TARGET_REF^{commit}
BASE_SHA=$(git rev-parse --short BASE_REF)
TARGET_SHA=$(git rev-parse --short TARGET_REF)

Step 1.5: Version Detection

# If TARGET_REF is a tag, extract version
# Note: avoid /i flag (GNU-specific); use explicit case alternation for portability (macOS + Linux)
if git tag -l "$TARGET_REF" | grep -q .; then
    AUTO_VERSION=$(echo "$TARGET_REF" | sed -E 's/^[Vv]//;s/^[Rr]elease[-_]?//;s/^[Vv]ersion[-_]?//')
fi
# Priority: explicit VERSION > auto-detected > none (omit from title)

Step 1.6: Commit Log Analysis

git log --oneline --no-merges BASE_REF...TARGET_REF
git log --pretty=format:"%h %s%n%b" --no-merges BASE_REF...TARGET_REF

Parse commit prefixes: `feat:` → Feature, `fix:` → Bug Fix, `refactor:` → Improvement, `breaking:` / `BREAKING CHANGE:` → Breaking.

Step 2: Produce Diff

git diff --find-renames --find-copies --stat BASE_REF...TARGET_REF
git diff --find-renames --find-copies BASE_REF...TARGET_REF

Step 3: Build Change Inventory

From diff, identify: endpoints (new/changed/removed), DB schema/migrations, messaging (topics/payloads), config/env vars, auth changes, performance (timeouts/pools), dependency bumps with runtime impact, observability changes.

Step 4: Write Guide

Use language-appropriate template based on LANGUAGE parameter.

**English title:** `# Ops Update Guide — <repo> — <VERSION> — <TARGET_SHA>` **Portuguese title:** `# Guia de Atualização (Ops) — <repo> — <VERSION> — <TARGET_SHA>` (Without version: use `BASE_REF → TARGET_REF` instead of `<VERSION>`)

**Header block:** Mode, Comparison, Base SHA, Target SHA, Date, Source.

**Per section format:** `## N. Descriptive Title [Category Emoji]`

| Category | English | Portuguese | Emoji | |----------|---------|------------|-------| | Feature | Feature | Funcionalidade | ✨ | | Bug Fix | Bug Fix | Correção | 🐛 | | Improvement | Improvement | Melhoria | 🆙 | | Breaking | Breaking | Breaking | ⚠️ | | Infrastructure | Infrastructure | Infra | 🔧 | | Observability | Observability | Observabilidade | 📊 | | Data | Data | Dados | 💾 |

**Each section contains (in order):**

1. **Contextual narrative** (1-3 paragraphs) — business/operational context, why this changed 2. **What Changed / O que mudou** — bullet list with file:line references 3. **Why It Changed / Por que mudou** — infer from code; if uncertain mark as **ASSUMPTION** + **HOW TO VALIDATE** 4. **Client Impact / Impacto para clientes** — who's affected, risk level (Low/Medium/High) 5. **Required Client Action / Ação necessária do cliente** — "None" or exact steps 6. **Deploy/Upgrade Notes / Notas de deploy/upgrade** — ordering, rolling deploy safety 7. **Post-Deploy Monitoring / O que monitorar pós-deploy** — logs in table format (Level | Message | Meaning), tracing spans in table format 8. **Rollback** — Safety: Safe/Conditional/Not recommended (or pt-br equivalents) + steps

**Special sections when applicable:**

• `### ⚠️ Attention Point` — confusing but expected behaviors
• Backward compatibility table for data/schema changes

Step 5: Summary Section

**English:** Summary table (Features/Bug Fixes/Improvements/Data counts) + Rollback Compatibility matrix (`| Item | Rollback | Justification |`).

**Portuguese:** `## Resumo` + `## Análise de Compatibilidade de Rollback` with same structure.

Step 6: Preview Before Saving (MANDATORY)

Show before writing to disk:

• Repository, comparison range, version detected, language(s), mode
• Change summary table (categories + counts)
• Top 5 key changes
• Output file path(s)

**Wait for user confirmation.**

Step 7: Save File

Output directory: `notes/releases/`

| Has Version? | LANGUAGE | Filename | |--------------|----------|----------| | Yes | `en` | `{DATE}_{REPO}-{VERSION}.md` | | Yes | `pt-br` | `{DATE}_{REPO}-{VERSION}_pt-br.md` | | No | `en` | `{DATE}_{REPO}-{BASE}-to-{TARGET}.md` | | No | `pt-br` | `{DATE}_{REPO}-{BASE}-to-{TARGET}_pt-br.md` | | Any | `both` | Both files above |

Confirm after saving: file path(s), refs/SHAs used, version, lang