Update brazilian portuguese translation to v1.1.0 (#577)
Co-authored-by: Olivier Lacan <hi@olivierlacan.com>
This commit is contained in:
João Lucas Farias
GitHub
parent
8c11222179
commit
45ce45409a
|
|
@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- v1.1 Brazilian Portuguese translation.
|
||||
- v1.1 German Translation
|
||||
- v1.1 Spanish translation.
|
||||
- v1.1 Italian translation.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,316 @@
|
|||
---
|
||||
description: Mantenha um Changelog
|
||||
title: Mantenha um Changelog
|
||||
language: pt-BR
|
||||
version: 1.1.0
|
||||
---
|
||||
.header
|
||||
.title
|
||||
%h1 Mantenha um Changelog
|
||||
%h2 Não deixe seus amigos despejarem logs de commits no Changelog
|
||||
|
||||
= 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 Adicionado
|
||||
para novas funcionalidades.
|
||||
%li
|
||||
%code Modificado
|
||||
para alterações em funcionalidades existentes.
|
||||
%li
|
||||
%code Obsoleto
|
||||
para funcionalidades que estão para ser removidas.
|
||||
%li
|
||||
%code Removido
|
||||
para funcionalidades removidas nesta versão.
|
||||
%li
|
||||
%code Corrigido
|
||||
para qualquer correção de bug.
|
||||
%li
|
||||
%code 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>Não publicado</code> no topo para rastrear alterações
|
||||
vindouras.
|
||||
|
||||
%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ê pode mover a seção de mudanças <code>Não publicado</code>
|
||||
como uma seção para uma nova publicação.
|
||||
|
||||
.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" }
|
||||
Diffs de registros de commits
|
||||
|
||||
%p
|
||||
Utilizar diffs de registros de commits como changelogs é uma má ideia: eles estão cheios de
|
||||
bagunça. Coisas como commits de mesclagem, commits 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 comunicá-las de forma
|
||||
clara aos usuários.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignorando descontinuaçõ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 que liste descontinuações, remova o que foi descontinuado,
|
||||
e então atualize para a versão em que descontinuações foram removidas.
|
||||
|
||||
%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.
|
||||
|
||||
%h4#inconsistent-changes
|
||||
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
||||
Alterações Inconsistentes
|
||||
|
||||
%p
|
||||
Um changelog que apenas menciona algumas das alterações pode ser tão perigoso
|
||||
quanto não ter um changelog. Enquanto muitas das alterações talvez não sejam
|
||||
relevantes - como por exemplo remover um único espaço em branco talvez não necessite
|
||||
ser registrado todas as vezes - qualquer alteração importante deve ser
|
||||
mencionada no changelog. Por registrar alterações de forma inconsistente,
|
||||
seus usuários podem pensar, incorretamente, que o changelog é a fonte única de verdade.
|
||||
Deveria ser. Com grandes poderes vem grandes responsabilidade -
|
||||
ter um bom changelog siginifica ter um changelog consistentemente atualizado.
|
||||
|
||||
%aside
|
||||
Tem mais. Me ajude a colecionar essas más práticas
|
||||
= link_to "enviando uma dúvida", data.links.issue
|
||||
ou um 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 #{link_to "guia de estilo de changelog do GNU", data.links.gnustyle},
|
||||
ou o "guia" #{link_to "de dois parágrafos do GNU NEWS file", data.links.gnunews}.
|
||||
Ambos são inadequados ou insuficientes.
|
||||
|
||||
%p
|
||||
Este projeto pretende ser
|
||||
= link_to "uma convenção para um changelog melhor.", data.links.changelog
|
||||
Ele vem da observação de boas práticas na comunidade de código aberto
|
||||
e a reunião delas.
|
||||
|
||||
%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 de 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 de 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 chamada <code>v1.0.0</code>)
|
||||
em ricas anotações de lançamento, adicionando manualmente anotações de lançamento 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
|
||||
É possível argumentar também que a versão atual do GitHub releases não é de fácil
|
||||
descoberta por usuários finais, ao contrário dos típicos arquivos em maiúsculo
|
||||
(<code>README</code>, <code>CONTRIBUTING</code> etc.). Outra questão é que a
|
||||
interface atualmente não oferece ligação (com links) para registros de commits
|
||||
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 muitos (mas
|
||||
não todos) changelogs de projetos de código aberto.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
E sobre 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
|
||||
fica mais fácil ser analisado programaticamente também.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Você deve reescrever um changelog?
|
||||
|
||||
%p
|
||||
Claro. Sempre existe uma boa razão para melhorar um changelog.
|
||||
Eu regularmente solicito alterações para adicionar lançamentos faltantes
|
||||
em projetos de código aberto que não mantém um changelog.
|
||||
|
||||
%p
|
||||
Também é possível que você descubra que você esqueceu de abordar
|
||||
uma mudança abrupta nas anotações 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 deveriam se preocupar
|
||||
com os changelogs, e também sobre as motivações por trás desse projeto.
|
||||
Loading…
Reference in New Issue