gugabfigueiredo/semver-howto

O que semver-howto faz?

Toda a lógica reside em scripts/resolve-version.sh. Este arquivo informa ao agente quando chamá-lo e quais são as regras. Ele não rederiva o procedimento — leia o --help do script para flags e seus comentários inline para o algoritmo.

Quando invocar

• Após uma mudança de código, quando uma tag de versão precisar ser proposta.
• Quando o usuário disser "tag this" / "bump version" / "what version?".
• A partir de uma etapa de CI que delega a seleção de tag a um agente.

Não invoque para criação de mensagens de commit ou geração de changelog.

Regras que o script impõe

1. Zona de Impacto: caminhos modificados → git log -1 -- <caminhos> → git describe --match "*v*" <commit>. Nunca amplia para todas as tags em um monorepo.
2. Bump: commits feat: dentro da zona de impacto → minor; caso contrário, patch. Major nunca é autônomo.
3. Colisão: git tag -l com escopo de padrão localmente, em seguida git ls-remote --tags origin "refs/tags/<candidato>" para pré-verificação superficial. Avança pelos endereços ocupados.
4. Apenas RC: a saída autônoma é sempre rc[n]. Tags limpas são recusadas.
5. Propor, não enviar: stdout = uma tag. O humano (ou um fluxo de trabalho de promoção) realiza a mutação.

Uso

./skills/semver-howto/scripts/resolve-version.sh              # propõe próximo -rc[n]
./skills/semver-howto/scripts/resolve-version.sh --promote    # remove -rc do RC mais alto
./skills/semver-howto/scripts/resolve-version.sh --paths "a b" # zona de impacto explícita
./skills/semver-howto/scripts/resolve-version.sh --help       # flags + notas do algoritmo

Saída 0 em caso de sucesso. Diferente de zero em estado ambíguo/inseguro (detalhes no stderr).

Desempenho e Segurança

• git describe --match "<prefixo>*v*" <commit> limita a busca de tags a referências relevantes — crítico em monorepos com milhares de tags por módulo.
• git tag -l "<padrão>" é servido a partir de packed-refs; O(ocorrências), não O(histórico).
• git ls-remote --tags origin "refs/tags/<candidato>" solicita uma única referência. Nenhum fetch de objetos, sem rotatividade de FETCH_HEAD, tipicamente abaixo de um segundo mesmo contra repositórios remotos enormes. Evita git fetch --tags completamente.
• Consultas de diff e log são limitadas aos caminhos da zona de impacto, então cada execução toca apenas a fatia relevante do histórico.
• Segurança: apenas escritas RC, verificação dupla de colisão local+remota, sem push, sem bumps major, bootstrap determinístico (v0.1.0-rc1) quando nenhuma tag anterior existe — exibido no stderr para confirmação humana.