Ring:generating Release Guides

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

STRICTNOTOUCH (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.

TEMPCLONEFORFRESHREFS: 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 — — — Portuguese title: # Guia de Atualização (Ops) — — — (Without version: use BASE_REF → TARGET_REF instead of ``)

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, language(s).

Hard Rules

| Rule | Requirement | |------|-------------| | No invented changes | MUST: All changes traceable to diff — nothing invented | | Uncertain info | MUST: Mark uncertain claims as ASSUMPTION + HOW TO VALIDATE | | Preview required | MUST: Show preview before saving — never skip | | User confirmation | MUST: Wait for explicit user confirmation before writing files | | Special change types | MUST: Explicitly document DB migrations, breaking API, feature flags, security/auth, log level changes |

Blocker Conditions

| Condition | Action | |-----------|--------| | Ref cannot be resolved in STRICT mode | STOP — suggest TEMP_CLONE mode | | Not in git repository | STOP — skill requires git context | | diff returns empty | STOP — verify refs have commits between them | | User declines preview | STOP — ask for corrections or abort confirmation |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LerianStudio
• Source: LerianStudio/ring
• License: Apache-2.0
• Homepage: https://lerian.studio

Install and usage instructions live in the source repository linked above.