Tags do git, lançamentos e o seu changelog
5 min de leitura
Uma tag do git, um lançamento e uma entrada de changelog são três registros diferentes do mesmo evento, e confundi-los faz um changelog se desviar silenciosamente do que realmente foi lançado. Uma tag marca um commit. Um lançamento empacota essa tag com artefatos e uma descrição. Uma entrada de changelog explica, em termos que uma leitora fora do repositório consegue usar, o que mudou. Eles geralmente acontecem próximos no tempo, e é exatamente por isso que é fácil tratá-los como um único passo em vez de três, e exatamente por isso que a lacuna só fica visível meses depois, quando alguém pergunta “o que saiu na v2.4” e a resposta honesta exige uma investigação de verdade.
Qual é a diferença real entre os três?
| Registro | Vive em | Escrito para |
|---|---|---|
| Tag do git | O repositório, como uma referência | Quem faz checkout exatamente daquele commit |
| Lançamento | O hospedeiro de código (GitHub, GitLab) | Quem baixa um build |
| Entrada de changelog | O próprio changelog do produto | Quem usa o produto, não só o repo |
Uma tag é a mais mecânica dos três: git tag v2.4.0 e pronto, sem nenhuma exigência de que algo
explique o que ela contém. Um lançamento adiciona uma descrição e, geralmente, artefatos para
download, e o público continua sendo desenvolvedoras que sabem o que é uma página de lançamento.
Uma entrada de changelog é a única dos três escrita para uma leitora que talvez nunca abra o
repositório, por isso é a que precisa de mais atenção editorial e a mais provável de ser pulada
sob pressão de prazo.
Toda tag do git precisa de uma entrada de changelog?
Não, e tratá-las um a um é um erro comum. Uma tag pode marcar um marco interno, um release candidate, ou um hotfix que nunca chega à maioria das usuárias; nenhuma delas necessariamente precisa de uma entrada pública. O teste é o mesmo que decide se algo pertence a um changelog: se uma usuária ou quem chama notaria ou se importaria. A maioria das tags passa nesse teste. Algumas, como uma tag criada só para disparar um pipeline de CI, nunca.
Toda entrada de changelog precisa da própria tag?
Nem sempre, e é aqui que os times que fazem deploy contínuo divergem dos times que lançam pacotes versionados. Um produto SaaS que faz deploy várias vezes por dia pode agrupar vários deploys sob uma entrada de changelog datada sem uma tag 1:1 por deploy; uma biblioteca publicada em um registro de pacotes geralmente precisa de uma tag por versão publicada. Os módulos Go e o Swift Package Manager resolvem versões a partir das próprias tags; no npm ou no PyPI é o registro que guarda a versão publicada, e a tag é como qualquer pessoa liga essa versão de volta ao código-fonte. Um repositório com vários pacotes versionados de forma independente precisa decidir isso por pacote, não uma vez para o repositório inteiro; changelogs em monorepo cobre como os prefixos de tag e o escopo do changelog deveriam seguir os limites dos pacotes, não das pastas. Semantic versioning e o seu changelog cobre como o número de versão em si deveria mapear para as categorias de changelog; tags são o mecanismo que torna um número de versão verificável contra o código real.
Como uma descrição de lançamento deveria se relacionar com a entrada de changelog?
Podem ser o mesmo texto, mas só se o público dos dois for realmente o mesmo, o que é mais raro do que parece. Uma página de lançamento em um hospedeiro de código é lida quase exclusivamente por desenvolvedoras; se um produto também tem usuárias não técnicas lendo o changelog, duplicar a descrição do lançamento ao pé da letra manda termos internos e uma redação voltada para código a uma leitora que precisava da versão em linguagem simples. O padrão mais limpo: escrever a entrada de changelog como o artefato principal, voltado para a leitora, e deixar a descrição do lançamento linkar para ela ou manter um resumo mais curto e técnico para o público que já está confortável ali.
# Lançamento v2.4.0 (GitHub, para desenvolvedoras)
Atualiza o pipeline de relatórios para o novo motor de agregação. Veja
o changelog para o resumo voltado ao cliente:
https://example.com/changelog#v2.4.0
## 2026-09-07 (Changelog, voltado ao cliente)
### Added
- Relatórios agora carregam em menos de um segundo, mesmo para contas
com mais de um milhão de linhas.O mesmo lançamento, dois documentos, cada um com sua própria redação para sua própria leitora.
De onde a entrada de changelog realmente vem?
De dois pontos de partida, e a maioria dos pipelines reais é uma mistura dos dois. Ela pode ser gerada a partir de mensagens de commit no momento da tag, o que é rápido e nunca perde um pull request mesclado; de conventional commits a changelog cobre esse pipeline por completo. Ou pode ser escrita à mão, totalmente separada da tag, sincronizada com o momento em que uma funcionalidade é considerada pronta em vez do momento em que o código é mesclado. Entradas geradas são consistentes mas herdam cada mensagem de commit vaga; entradas escritas à mão são mais claras mas precisam de alguém para realmente escrevê-las. A maioria dos times que automatizam ainda mantém uma passada leve de edição no texto gerado antes que ele vire a entrada pública, a mesma disciplina que Keep a Changelog, na prática recomenda, independentemente de onde o texto bruto veio originalmente.
O que quebra quando os três saem de sincronia?
A confiança no que a leitora conferiu primeiro. Uma tag que existe sem uma entrada de changelog correspondente parece, do lado de quem lê o changelog, que nada aconteceu naquela semana. Uma entrada de changelog sem tag ou lançamento correspondente torna impossível para quem está depurando um problema de produção fazer checkout exatamente do código que estava ao vivo quando uma entrada foi publicada. A solução não é automação perfeita, é uma única fonte de verdade para esse mapeamento: um lugar, mesmo que seja só a própria checklist do processo de lançamento, que diz que uma mudança lançável recebe as três, no mesmo commit ou pull request que a introduz.
FAQ
Entradas de changelog deveriam ser geradas automaticamente a partir de tags do git? Podem ser um ponto de partida, mas uma tag sozinha não carrega nenhuma descrição voltada para a leitora, só um intervalo de commits. A geração automatizada precisa ler as mensagens de commit dentro desse intervalo, não só a existência da tag, para produzir algo utilizável.
E se não colocarmos tag em todo lançamento? Então a entrada de changelog vira o registro principal, e ainda assim deveria carregar uma data e, se o produto tiver uma, um número de versão, para que a entrada continue sendo algo a que uma leitora possa se referir depois mesmo sem uma tag correspondente.
Tags de pré-lançamento (como v2.4.0-rc.1) deveriam ter entradas de changelog?
Geralmente não. Um release candidate é para testes internos ou beta, e uma entrada de changelog
para ele treina leitoras a esperar entradas para versões que podem nunca ser lançadas exatamente
como descritas. Reserve entradas para tags que alcançam disponibilidade geral.
Uma única entrada de changelog pode cobrir várias tags do git? Sim, e frequentemente deveria para times que colocam tag com frequência. Agrupe tags relacionadas sob uma entrada datada descrevendo a mudança líquida, em vez de publicar uma entrada fina por tag que fragmenta uma funcionalidade em várias leituras.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.