Olivier Lacan bee0534514 Make page title & description dynamic
Previously they had to be duplicated from the page
frontmatter but that's not necessary and also makes
it possible to have correct OpenGraph title and
descriptions.
2024-02-04 21:13:49 -08:00

300 lines
10 KiB
Plaintext

---
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.