Skill de Release do GitHub

Esta skill automatiza o fluxo de trabalho completo de release para um repositório GitHub de pacote único, da análise à autoria do changelog e criação de PR. Ela depende exclusivamente do gh (GitHub CLI) e git, sem necessidade de outras ferramentas.

Os Passos 1 a 4 são somente leitura de reconhecimento, nada é escrito no repositório até o Passo 5, após a confirmação do número da versão.

Quando Usar Esta Skill

Use esta skill sempre que o usuário quiser fazer um novo release, publicar uma nova versão, incrementar uma versão, criar um branch de release, gerar um changelog ou abrir um PR de release em um repositório GitHub. Dispare mesmo que o usuário diga algo casual como "vamos lançar uma nova versão" ou "hora de fazer o release".

Pré-requisitos

Os exemplos abaixo incluem variantes Bash e PowerShell; usuários do Windows devem preferir os blocos PowerShell.

Antes de começar, verifique o ambiente:

gh auth status                        # must be authenticated
gh repo view --json nameWithOwner     # must be inside a GitHub repo
git status                            # working tree should be clean

Se alguma verificação falhar, pare e diga ao usuário o que corrigir antes de continuar.

Em seguida, pergunte ao usuário uma pergunta:

"Qual diretório contém o código-fonte público da sua biblioteca? (ex: src/, lib/, pkg/ - usado para focar o diff no que os consumidores realmente veem. Pressione Enter para escanear o repositório inteiro.)"

Armazene a resposta como PUBLIC_PATH. Se estiver vazio, PUBLIC_PATH é . (raiz do repositório). Exclua esses caminhos de todos os diffs, independentemente: tests/, test/, spec/, __tests__/, docs/, *.lock, *-lock.json, *.sum, arquivos gerados (arquivos com um comentário de cabeçalho "não editar") e artefatos de build.

O Fluxo de Trabalho de Release em 9 Passos

Trabalhe em cada passo em ordem. Mostre ao usuário qual comando você está prestes a executar e sua saída. Pause e peça confirmação apenas quando explicitamente indicado.

Passo 1 - Garantir que o main está atualizado

git checkout main
git pull origin main

Permaneça no main por enquanto. O branch de release é criado no Passo 5, após a versão ser confirmada.

Passo 2 - Obter a última tag de versão

Por que não gh release list? Releases do GitHub são uma camada opcional sobre tags Git. Muitos repositórios marcam releases com git tag sem nunca criar um Release do GitHub, então gh release list pode retornar vazio mesmo quando tags de versão existem. Ler tags diretamente do git é a fonte confiável da verdade.

# Fetch all tags from remote to ensure local view is current
git fetch --tags

# Find the latest version tag, sorted semantically
# --sort=-version:refname handles 1.10.0 > 1.9.0 correctly (unlike alphabetical)
PREV_TAG=$(git tag --sort=-version:refname | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+' | head -1)
echo "Latest tag: $PREV_TAG"

# Fetch all tags from remote to ensure local view is current
git fetch --tags

# Find the latest version tag, sorted semantically
# --sort=-version:refname handles 1.10.0 > 1.9.0 correctly (unlike alphabetical)
$prevTag = git tag --sort='-version:refname' | `
  Select-String '^[vV]?\d+\.\d+\.\d+' | `
  Select-Object -First 1 -ExpandProperty Line

if ($prevTag) {
  $prevSha = git rev-list -n 1 $prevTag
} else {
  $prevSha = git rev-list --max-parents=0 HEAD
}

Write-Output "Latest tag: $prevTag"

Em seguida, verifique se a tag existe no remoto (não apenas localmente):

git ls-remote --tags origin | grep "refs/tags/$PREV_TAG$"

Se a verificação remota não retornar nada, avise o usuário que a tag parece ser apenas local e não foi enviada (push) - ele pode querer enviá-la antes de continuar.

• PREV_TAG é o nome da tag exatamente como encontrado (ex: v1.4.2). Remova qualquer v inicial ao fazer aritmética; preserve-o ao nomear coisas.
• Se nenhuma tag existir, trate PREV_TAG como (none), defina PREV_SHA para o primeiro commit e defina a nova versão como 1.0.0 (pule a lógica de versionamento do Passo 4; vá direto para o Passo 5).
• Se a tag não apontar para um commit real (tag órfã), volte para git rev-list --max-parents=0 HEAD e avise o usuário.

PREV_SHA=$(git rev-list -n 1 "$PREV_TAG" 2>/dev/null || git rev-list --max-parents=0 HEAD)

Passo 3 - Analisar o que mudou desde o último release

Este passo usa dois sinais complementares. O diff de código é a fonte primária da verdade; mensagens de commit fornecem contexto de apoio sobre a intenção.

3a - Diff de código (sinal primário)

# Diff focado no caminho da fonte pública, excluindo ruído

…