mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-26 12:18:16 +02:00
311 lines
10 KiB
Plaintext
311 lines
10 KiB
Plaintext
---
|
|
description: Mantenha um Changelog
|
|
title: Mantenha um Changelog
|
|
language: pt-BR
|
|
version: 1.0.0
|
|
---
|
|
|
|
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
|
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
|
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
|
- semver = "https://semver.org/"
|
|
- shields = "https://shields.io/"
|
|
- thechangelog = "https://changelog.com/podcast/127"
|
|
- vandamme = "https://github.com/tech-angels/vandamme/"
|
|
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
|
- ghr = "https://help.github.com/articles/creating-releases/"
|
|
|
|
.header
|
|
.title
|
|
%h1 Mantenha um Changelog
|
|
%h2 Não deixe seus amigos despejarem logs de commits no Changelog
|
|
|
|
= link_to changelog do
|
|
Version
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
O que é um changelog?
|
|
|
|
%p
|
|
Um changelog é um arquivo que contém uma lista selecionada, ordenada
|
|
cronologicamente, de mudanças significativas para cada versão de um projeto.
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
Por que manter um changelog?
|
|
|
|
%p
|
|
Para facilitar que usuários e contribuidores vejam precisamente quais
|
|
mudanças significativas foram realizadas entre cada versão publicada de
|
|
um projeto.
|
|
|
|
%h3#who
|
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
|
Quem precisa de um changelog?
|
|
|
|
%p
|
|
Pessoas precisam. Seja consumidores ou desenvolvedores,
|
|
os usuários finais de softwares são seres humanos
|
|
que se preocupam com o que está no software. Quando
|
|
o software muda, as pessoas querem saber por que e como.
|
|
|
|
.good-practices
|
|
%h3#how
|
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
|
Como fazer um bom changelog?
|
|
|
|
%h4#principles
|
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
|
Princípios fundamentais
|
|
|
|
%ul
|
|
%li
|
|
Changelogs são <em>para humanos</em>, não máquinas.
|
|
%li
|
|
Deve haver uma entrada para cada versão.
|
|
%li
|
|
Alterações do mesmo tipo devem ser agrupadas.
|
|
%li
|
|
Versões e seções devem ser vinculáveis (com links).
|
|
%li
|
|
A versão mais recente vem em primeiro lugar.
|
|
%li
|
|
A data de lançamento de cada versão é exibida.
|
|
%li
|
|
Mencione se você segue o #{link_to "versionamento semântico", semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types Tipos de mudanças
|
|
|
|
%ul
|
|
%li
|
|
%code Added/Adicionado
|
|
para novos recursos.
|
|
%li
|
|
%code Changed/Modificado
|
|
para alterações em recursos existentes.
|
|
%li
|
|
%code Deprecated/Obsoleto
|
|
para recursos que serão removidos nas próximas versões.
|
|
%li
|
|
%code Removed/Removido
|
|
para recursos removidos nesta versão.
|
|
%li
|
|
%code Fixed/Corrigido
|
|
para qualquer correção de bug.
|
|
%li
|
|
%code Security/Segurança
|
|
em caso de vulnerabilidades.
|
|
|
|
.effort
|
|
|
|
%h3#effort
|
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
|
Como eu posso minimizar o esforço exigido para manter um changelog?
|
|
|
|
%p
|
|
Mantenha sempre uma seção <code>Unreleased/Não publicado</code> no topo para manter o controle das novas mudanças.
|
|
|
|
%p Isso serve a dois propósitos:
|
|
|
|
%ul
|
|
%li
|
|
As pessoas podem ver quais mudanças elas podem esperar em publicações futuras.
|
|
%li
|
|
No momento da publicação, você apenas tem de mudar a seção
|
|
<code>Unreleased/Não publicado</code> para o número de versão e adicionar uma
|
|
nova seção <code>Unreleased/Não publicado</code> no topo.
|
|
|
|
.bad-practices
|
|
%h3#bad-practices
|
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
|
Os changelogs podem ser ruins?
|
|
|
|
%p Sim. Aqui estão algumas maneiras pelas quais eles podem ser inúteis.
|
|
|
|
%h4#log-diffs
|
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
|
Usar um registro de alterações automático
|
|
|
|
%p
|
|
Usar um registro de alterações automático é uma má ideia: eles estão
|
|
cheios de bagunça. Coisas como solicitação de mesclagem, envio com títulos
|
|
estranhos, alterações de documentação, etc.
|
|
|
|
%p
|
|
O propósito de um commit é documentar a etapa na evolução do código
|
|
fonte. Alguns projetos limpam os commits, outros não.
|
|
|
|
%p
|
|
O propósito de uma entrada de changelog é documentar as diferenças
|
|
notáveis, muitas vezes de múltiplos commits, para comunicar de forma
|
|
clara os usuários.
|
|
|
|
%h4#ignoring-deprecations
|
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
|
Ignorando depreciações
|
|
|
|
%p
|
|
Quando pessoas atualizam de uma versão para outra, deve ficar muitíssimo claro
|
|
quando algo vai quebrar. Deve ser possível atualizar para uma versão
|
|
com depreciações listadas, remova o que é obsoleto, depois atualize
|
|
para a versão onde as depreciações se tornam remoções.
|
|
|
|
%p
|
|
Se você não fizer mais nada, liste no seu changelog as depreciações,
|
|
remoções e quaisquer mudanças que gerem falhas.
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
Datas confusas
|
|
|
|
%p
|
|
Os formatos regionais de data variam em todo o mundo e muitas vezes
|
|
é difícil encontrar um formato de data amigável que seja intuitivo para todos.
|
|
A vantagem das datas formatadas como <code>2017-07-17</code> é que elas seguem
|
|
a ordem da maior para a menor unidade de tempo: ano, mês e dia. Este formato
|
|
também não se confunde de maneira ambígua com outros formatos de data, ao
|
|
contrário de alguns formatos regionais que alteram a posição dos números do mês
|
|
e dia. Esses motivos, e o fato de ser um formato de data suportado pela
|
|
#{link_to "norma ISO", iso} são as razões para ele ser o formato de data
|
|
recomendado para as entradas do changelog.
|
|
|
|
%aside
|
|
Tem mais. Me ajude a colecionar essas más práticas
|
|
= link_to "enviando uma dúvida", issues
|
|
ou pedindo mudanças.
|
|
|
|
.frequently-asked-questions
|
|
%h3#frequently-asked-questions
|
|
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
|
Perguntas frequentes
|
|
|
|
%h4#standard
|
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
|
Existe um padrão para o formato do changelog?
|
|
|
|
%p
|
|
Na verdade não. Existe o guia de estilo de changelog do GNU
|
|
ou o "guia" de dois parágrafos do GNU NEWS. Ambos são inadequados ou
|
|
insuficientes.
|
|
|
|
%p
|
|
Este projeto pretende ser #{link_to "uma convenção de changelog melhor.", changelog}
|
|
Ele vem de observar e coletar as boas práticas em código aberto da
|
|
comunidade.
|
|
|
|
%p
|
|
Críticas saudáveis, discussões e sugestões de melhorias
|
|
= link_to "são bem-vindas.", issues
|
|
|
|
%h4#filename
|
|
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
|
Qual nome o arquivo changelog deve ter?
|
|
|
|
%p
|
|
Chame-o <code>CHANGELOG.md</code>. Alguns projetos usam
|
|
<code>HISTORY</code>, <code>NEWS</code> ou <code>RELEASES</code>.
|
|
|
|
%p
|
|
Embora seja fácil pensar que o nome do seu arquivo changelog
|
|
não importa muito, por que tornar mais difícil para seus usuários
|
|
finais encontrarem consistentemente mudanças notáveis?
|
|
|
|
%h4#github-releases
|
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
|
E sobre o GitHub Releases?
|
|
|
|
%p
|
|
É uma grande iniciativa. #{link_to "Lançamentos", ghr} podem ser usados
|
|
para converter simples marcadores do git (por exemplo, um
|
|
marcador chamado <code>v1.0.0</code>) em notas de versão ricas,
|
|
adicionando manualmente notas de versão ou pode puxar as mensagens
|
|
anotadas no marcador do git e transformá-las em notas.
|
|
|
|
%p
|
|
GitHub Releases cria um changelog não portátil
|
|
que só pode ser exibido para usuários no contexto do GitHub.
|
|
É possível fazê-los parecer muito como o formato
|
|
Keep a Changelog, mas tende a ser um pouco mais complicado.
|
|
|
|
%p
|
|
A versão atual do GitHub Releases não é facilmente descoberta
|
|
por usuários finais, ao contrário dos arquivos maiúsculos típicos
|
|
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Outro
|
|
problema de menor magnitude é que a interface atualmente não oferece
|
|
links para confirmar alterações entre cada lançamento.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
Os changelogs podem ser criados automaticamente?
|
|
|
|
%p
|
|
É difícil, porque as pessoas seguem formatos e nomes de arquivos
|
|
totalmente diferentes.
|
|
|
|
%p
|
|
#{link_to "Vandamme", vandamme} é um gem Ruby criado pelo
|
|
time Gemnasium e que analisa muitas
|
|
(mas não todas) alterações de projetos de código aberto.
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
E o lançamentos removidos?
|
|
|
|
%p
|
|
Lançamentos removidos são versões que foram retiradas por causa de
|
|
problemas sérios ou falhas de segurança. Muitas vezes essas versões
|
|
nem aparecem no histórico de alterações. Eles deviam. É assim que
|
|
você deve exibi-los:
|
|
|
|
%p <code>## 0.0.5 - 2014-12-13 [REMOVIDO]</code>
|
|
|
|
%p
|
|
O marcador <code>[REMOVIDO]</code> está em caixa alta por uma razão.
|
|
É importante que as pessoas o percebam. Já que está entre
|
|
colchetes, também fica mais fácil de ser analisado programaticamente.
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
Você deve reescrever um changelog?
|
|
|
|
%p
|
|
Claro. Sempre existe razão para melhorar um changelog.
|
|
Eu regularmente solicito alterações em projetos de código livre que
|
|
possuem changelogs não mantidos para adicionar lançamentos
|
|
que não estão presentes nestes.
|
|
|
|
%p
|
|
Também é possível que você descubra que você esqueceu de abordar
|
|
uma mudança abrupta nas notas para uma versão.
|
|
Obviamente é importante que você atualize seu changelog neste caso.
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
Como eu posso ajudar?
|
|
|
|
%p
|
|
Esse documento não é uma <strong>verdade absoluta</strong>; É minha
|
|
opinião cuidadosamente considerada, juntamente com informações e
|
|
exemplos que eu reuni.
|
|
|
|
%p
|
|
Isso porque o que eu quero é que nossa comunidade chegue a um consenso.
|
|
Eu acredito que a discussão é tão importante quanto o resultado final.
|
|
|
|
%p
|
|
Então, por favor <strong>#{link_to "contribua", gh}</strong>.
|
|
|
|
.press
|
|
%h3 Discussões
|
|
%p
|
|
Eu fui no #{link_to "The Changelog podcast", thechangelog}
|
|
para falar sobre por que os mantenedores e contribuidores devem se
|
|
preocupar com os changelogs, e também sobre as motivações
|
|
por trás desse projeto.
|