---
title: Mantenha um Changelog
description: Não deixe seus amigos despejarem logs de commits no Changelog
language: pt-BR
version: 1.0.0
---
.header
  .title
    %h1= current_page.data.title
    %h2= current_page.data.description

  = link_to data.links.changelog do
    Version
    %strong= current_page.metadata[:page][:version]

  %pre.changelog{ lang: "en" }= 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", data.links.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", data.links.isodate} 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", data.links.issue
    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.", data.links.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.", data.links.issue

  %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", data.links.github_releases} 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", data.links.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", data.links.repo}</strong>.

.press
  %h3 Discussões
  %p
    Eu fui no #{link_to "The Changelog podcast", data.links.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.