Embed Notice

Tópicos:

1. Changelogs, release notes e notas de lançamento são coisas diferentes
1.1 Commits "convencionais" não são changelogs
1.2 Escreva manualmente o que é relevante no changelog e versione e isso
1.3 Escreva release notes além dos changelogs
1.4 Escreva para humanos
1.5 Link a porra das issues, se não tiver issue? CRIE

2. Versione a documentação
2.1 Mantenha online as múltiplas versões
2.2 links absolutos são uma droga, eles quebram entre versões
2.3 mantenha a mesma estrutura, se eu mudar de versão, não quero um 404 (sempre que possível)
2.4 adicione o changelog na documentação
2.5 Use exemplos diretamente de arquivos de código
2.5.1 eles são executáveis e podem quebrar, diferentes de código escrito direto na documentação
2.5.2 rode esses exemplos no CI

3. Mantenha branches de código para tags
3.1 Você nunca sabe quando vai precisar adicionar um aviso na doc ou no código
3.2 algum momento é possível que tenha que corrigir uma coisa maluca em uma versão passada

...