keep-a-changelog/source/pt-BR/0.3.0/index.html.haml

---
title: Mantenha um CHANGELOG
description: Não deixe seus amigos despejarem logs de commits em CHANGELOGs
language: pt-BR
version: 0.3.0
---

%h1= current_page.data.title
%h2= current_page.data.description

Version <strong>#{current_page.metadata[:page][:version]}</strong>

:markdown
  ### O que é um *changelog*?

  Um *changelog* é um arquivo que contém uma lista selecionada, ordenada
  cronologicamente, de mudanças significativas para cada versão de um projeto
  *open source*.

<pre class="changelog">#{File.read("CHANGELOG.md")}</pre>

:markdown
  ### Para que serve um *changelog*?

  Para facilitar que usuários e contribuidores vejam precisamente quais
  mudanças significativas foram realizadas entre cada versão publicada.

  ### Por que eu deveria me importar?

  Porque softwares são feitos para pessoas. Se você não liga, por que está
  contribuindo com projetos *open source*? Certamente deve haver um fundo de
  carinho em algum lugar desse seu amável cerebrinho.

  Eu [conversei com Adam Stacoviak e Jerod Santo no podcast do The
  Changelog][thechangelog] (faz sentido, hein?) sobre por que mantenedores e
  contribuidores *open source* devem se importar e as motivações por trás desse
  projeto. Se você tem tempo (1:06), é um bom programa.

  ### O que faz um *changelog* ser bom?

  Que bom que perguntou.

  Um bom *changelog* se atém a esses princípios:

  - É feito para seres humanos, não máquinas, então legibilidade é crucial.
  - É fácil de referenciar (*linkar*) qualquer seção (por isso Markdown ao
    invés de puro texto).
  - Uma subseção por versão.
  - Lista as versões publicadas em ordem cronológica decrescente (mais novo em
    cima).
  - Usa todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para
    `2 de Junho de 2012`.) É internacional, [sensato](https://xkcd.com/1179/), e
    independente de língua.
  - Menciona explicitamente se o projeto segue o [Versionamento Semântico][semver].
  - Cada versão deve:
    - Listar sua data de publicação no formato acima.
    - Agrupar mudanças descrevendo seus impactos no projeto, como segue:
      - `Added`/`Adicionado` para novas funcionalidades.
      - `Changed`/`Modificado` para mudanças em funcionalidades existentes.
      - `Deprecated`/`Obsoleto` para funcionalidades estáveis que foram removidas das
        próximas versões.
      - `Removed`/`Removido` para funcionalidades removidas desta versão.
      - `Fixed`/`Consertado` para qualquer correção de bug.
      - `Security`/`Segurança` para incentivar usuários a atualizarem em caso de
        vulnerabilidades.

  ### Como eu posso minimizar o esforço exigido?

  Mantenha sempre uma seção `"Unreleased"`\`"A publicar"` no topo para manter o controle de
  quaisquer mudanças.

  Isso serve a dois propósitos:

  - As pessoas podem ver quais mudanças elas podem esperar em publicações
    futuras.
  - No momento da publicação, você apenas tem de mudar o `"Unreleased"`\`"A publicar"` para o
    número de versão e adicionar um novo cabeçalho `"Unreleased"`\`"A publicar"` no topo.

  ### O que faz os unicórnios chorarem?

  Tudo bem... vamos lá.

  - **Despejar logs de commits.** Simplesmente não faça isso, você não está
    ajudando ninguém.
  - **Não dar ênfase nas obsolências.** Quando as pessoas atualizam de uma versão
    para outra, deve ser incrivelmente claro quando algo irá parar de funcionar.
  - **Datas em formatos específicos de uma região.** Nos Estados Unidos, as pessoas
    colocam o mês primeiro ("06-02-2012" para 2 de Junho de 2012, o que *não*
    faz sentido), enquanto muitos no resto do mundo escrevem em aspecto
    robótico "2 Junho 2012", e mesmo assim leem de forma diferente.
    "2012-06-02" funciona de maneira lógica do maior para o menor, não
    se confunde de maneira ambígua com outros formatos, e é um [padrão
    ISO](http://www.iso.org/iso/home/standards/iso8601.htm).  Portanto, é o
    formato recomendado para *changelogs*.

  Tem mais. Ajude-me a coletar essas lágrimas de unicórnio [abrindo uma
  issue][issues] ou um *pull request*.

  ### Existe um padrão de formato de *changelog*?

  Infelizmente, não. Calma. Eu sei que você está buscando furiosamente
  aquele link do guia GNU de estilo de *changelog*, ou o arquivo "guideline"
  de dois paragráfos do GNU NEWS. O estilo GNU é um bom começo mas, infelizmente, é ingênuo.
  Não há nada de errado em ser ingênuo mas, quando as pessoas precisam de orientação,
  raramente ajuda. Especialmente quando existem muitas situações excepcionais
  para lidar.

  Este projeto [contém o que eu espero se tornar um melhor padrão de arquivo
  CHANGELOG][CHANGELOG] para todos os projetos *open source*. Eu não acredito que o status quo 
  seja bom o suficiente, e acho que, como uma comunidade, nós podemos encontrar novas convenções
  se tentarmos extrair boas práticas de projetos de software reais. Por favor, dê uma olhada e 
  lembre-se de que [discussões e sugestões de melhorias são bem-vindas][issues]!

  ### Qual deve ser o nome do arquivo *changelog*?

  Bom, se você não notou no exemplo acima, `CHANGELOG.md` é a melhor convenção até agora.

  Alguns outros projetos também utilizam `HISTORY.txt`, `HISTORY.md`,
  `History.md`, `NEWS.txt`, `NEWS.md`, `News.txt`, `RELEASES.txt`,
  `RELEASE.md`, `releases.md`, etc.

  É uma bagunça. Todos esses nomes só dificultam encontrar o *changelog*.

  ### Por que as pessoas não podem simplesmente utilizar `git log`?

  Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um 
  changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que
  nunca erram uma letra, nunca esquecem de *commitar* arquivos, nunca cometem deslizes
  em uma refatoração. O propósito de um *commit* é documentar um passo atômico no 
  processo pelo qual o código evolui de um estado a outro. O propósito de um *changelog*
  é documentar as diferenças relevantes entre esses estados.
  
  A mesma diferença que existe entre bons comentários e o código em si existe entre o 
  *changelog* e o *commit log*: um descreve o *porquê*, o outro descreve o *como*.

  ### Podem os *changelogs* ser automaticamente interpretados?

  É difícil, porque as pessoas seguem formatos e nomes de arquivos
  radicalmente diferentes.

  [Vandamme][vandamme] é uma gem criada pelo time [Gemnasium][gemnasium] que
  interpreta muitos (mas não todos) *changelogs* de projetos *open source*.

  ### Por que você alterna entre as grafias "CHANGELOG" e "changelog"?

  "CHANGELOG" é o nome do arquivo em si. É um pouco chamativo mas é uma
  convenção histórica seguida por muitos projetos *open source*. Outros exemplos
  similares de arquivo incluem [`README`][README], [`LICENSE`][LICENSE], e
  [`CONTRIBUTING`][CONTRIBUTING].

  O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam
  estes arquivos ficarem no topo da lista) é utilizado para chamar atenção.
  Por conterem importantes metadados do projeto, *changelogs* são úteis a
  qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira
  equivalente às [badges de projetos *open source*][shields].

  Quando eu me refiro a "*changelog*", eu estou falando sobre a função desse
  arquivo: listar mudanças.

  ### E sobre as publicações removidas?

  Publicações removidas são versões que tiveram que ser removidas devido a um
  sério bug ou problema de segurança. Com frequência essas versões sequer
  aparecem em *changelogs*. Deveriam. É assim que você deve exibi-las:

  `## [0.0.5] - 2014-12-13 [YANKED]`
  
  A tag `[YANKED]`/`[REMOVIDA]` é chamativa por uma razão. É importante que
  as pessoas a notem. Além disso, já que é cercada por colchetes, é mais
  fácil detectá-la programaticamente.

  ### Devemos alterar o *changelog* em alguma circunstância?
 
  Claro. Sempre existem bons motivos para melhorar um *changelog*. Eu regularmente
  abro *pull requests* para adicionar versões faltantes em projetos *open source*
  com *changelogs* abandonados.

  Também é possível que você perceba que se esqueceu de registrar mudanças
  importantes nas notas de uma versão. É obviamente importante que você atualize
  seu *changelog* nesse caso.

  ### Como eu posso contribuir?

  Este documento não é a verdade; é minha cuidadosa opinião, junto com as
  informações e exemplos que reuni. Embora eu tenha providenciado um
  [CHANGELOG][] no [repositório no GitHub][gh], eu não criei de propósito uma
  lista clara de regras a serem seguidas (como o [SemVer.org][semver] faz, por
  exemplo).

  Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu
  acredito que a discussão é tão importante quanto o resultado final.

  Então, por favor, [entre em campo][gh].

  [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CHANGELOG.md
  [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/main/CONTRIBUTING.md
  [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/main/LICENSE
  [README]: https://github.com/olivierlacan/keep-a-changelog/blob/main/README.md
  [gemnasium]: https://gemnasium.com/
  [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/