Tema: release-management
-
Tags e releases: tags leves versus anotadas e como elas se propagam
Uma tag leve é apenas um nome para um commit; uma tag anotada é um objeto com autor, data, mensagem e assinatura opcional. Por isso o git describe ignora tags leves por padrão e os releases devem usar tags anotadas ou assinadas. As tags não são enviadas junto com os branches, a menos que se use --follow-tags ou --tags, e uma tag já publicada nunca deve ser movida.
-
Cherry-pick: quando é adequado e o que custa ao histórico
O git cherry-pick reaplica a alteração de um commit como um novo commit com outro ID; é a ferramenta certa para fazer backport de uma correção para uma branch de manutenção ou resgatar um commit de uma branch abandonada, mas cada pick cria uma duplicata que os merges não reconhecem. Por isso, registre a origem com -x e faça merge em vez de pick quando quiser a branch inteira.
-
Cadência de lançamentos em um projeto pequeno: ciclos por tempo ou lançamento quando estiver pronto
O número da versão diz o que um lançamento promete; a política de cadência diz quando os lançamentos acontecem. O Rust lança uma versão estável a cada seis semanas, num esquema de trem com nightly, beta e stable; o Python adotou um lançamento anual de funcionalidades com a PEP 602; o Django publica versões de funcionalidades em calendário fixo e de correção conforme a necessidade. Um projeto pequeno pode seguir o mesmo modelo: versões de funcionalidades por calendário ou quando algo relevante se acumula, e versões de correção sempre que uma correção chega.
-
Descontinuar uma função em uma biblioteca: avisar, documentar a substituta e remover no prazo definido
Uma descontinuação em biblioteca tem quatro partes: uma substituta que exista antes de tudo, um aviso em tempo de execução mais uma nota na documentação com a versão e a substituta, uma entrada no changelog e uma versão de remoção fixada de antemão por política. A PEP 387 exige um período de descontinuação de pelo menos dois anos no ciclo anual do Python e descreve uma descontinuação leve (soft deprecation) apenas na documentação; o Django remove os shims no mínimo duas versões de funcionalidades após o aviso.
-
Conventional Commits: tipos de commit legíveis por máquina
A especificação Conventional Commits acrescenta às mensagens de commit um prefixo tipado (feat, fix e outros) e marcadores de breaking change, para que changelogs e incrementos de versão possam ser derivados automaticamente.
-
Versionamento Semântico: o que um número de versão promete
O Versionamento Semântico 2.0.0 codifica promessas de compatibilidade em MAJOR.MINOR.PATCH e define sufixos de pré-lançamento e de metadados de build; só funciona quando a API pública é declarada.
-
Versionamento de API: quando e como quebrar a compatibilidade
A maioria das mudanças pode ser aditiva; uma nova versão principal é o último recurso, pois duplica a superfície a ser mantida. Versione no caminho ou no tipo de mídia, documente as regras de compatibilidade e marque como obsoleto antes de remover.
-
Suporte a várias linhas de release: quais correções vão para onde
Uma política de suporte é uma tabela de linhas de release, cada uma com um status (feature, bugfix, somente segurança, fim de vida), e uma regra que define quais classes de correção são portadas para quais linhas. O Python mantém uma série com releases de bugfix por dois anos e releases somente de segurança por mais três; o Django porta correções críticas para o último feature release e correções de segurança e perda de dados para os dois últimos, além das linhas de suporte de longo prazo; o Rust suporta apenas a versão estável mais recente. Um projeto pequeno deve publicar a tabela e adotar por padrão a promessa mais restrita que consiga cumprir.
-
Como manter um changelog pensado para pessoas
Um changelog é uma lista curada e em ordem cronológica das alterações relevantes de cada versão; o Keep a Changelog define uma estrutura simples (Added, Changed, Deprecated, Removed, Fixed, Security) e uma seção Unreleased.
Legível por máquina: JSON