Add @tallesl's pt-BR translation from #69.

This commit is contained in:
Nathaniel Bibler 2015-10-24 01:08:39 -04:00
parent e61c8cc1da
commit ae3da5c7e3
3 changed files with 190 additions and 1 deletions

View File

@ -4,7 +4,7 @@
# ----- Site ----- # # ----- Site ----- #
activate :i18n, langs: [:en, :ru], :mount_at_root => :en activate :i18n, langs: [:en, 'pt-BR', :ru], :mount_at_root => :en
set :gauges_id, '' set :gauges_id, ''
set :publisher_url, 'https://www.facebook.com/olivier.lacan.5' set :publisher_url, 'https://www.facebook.com/olivier.lacan.5'
set :site_url, 'http://keepachangelog.com' set :site_url, 'http://keepachangelog.com'

View File

@ -33,6 +33,7 @@
%nav.locales{role: "navigation"} %nav.locales{role: "navigation"}
%ul %ul
%li= link_to 'engish [en]', '/' %li= link_to 'engish [en]', '/'
%li= link_to 'português brasileiro [pt-BR]', '/pt-BR'
%li= link_to 'pyccкий [ru]', '/ru' %li= link_to 'pyccкий [ru]', '/ru'
.main{role: "main"}= yield .main{role: "main"}= yield

188
source/pt-BR/index.haml Normal file
View File

@ -0,0 +1,188 @@
---
description: Mantenha um CHANGELOG
title: Mantenha um CHANGELOG
language: pt-BR
---
:markdown
# Mantenha um CHANGELOG
## Não deixe seus amigos despejar logs de commits em CHANGELOGs™
### O que é um change log?
Um *change log* é um arquivo que contém uma lista selecionada, ordenada
cronologicamente de mudanças significativas para cada versão de um projeto
open source.
%pre.changelog= File.read(File.expand_path("../../../CHANGELOG.md", __FILE__))
:markdown
### Para que serve um *change log*?
Para facilitar para os usuários e contribuidores verem precisamente quais
mudanças significativas foram realizadas entre cada versão publicada.
### Por quê eu deveria me importar?
Porque softwares são feitos para pessoas. Se você não liga, porque está
contribuindo a projetos open source? Certamente deve haver um fundo de
carinho em algum lugar dessa sua cabeçinha.
Eu [conversei com Adam Stacoviak e Jerod Santo no podcast do The
Changelog][thechangelog] (faz sentido, hein?) sobre o por quê mantenedores e
contribuidores open source devem se importar, e as motivações por trás deste
projeto. Se você tem o tempo (1:06), é um bom programa.
### O que faz um *change log* ser bom?
Que bom que perguntou.
Um bom change log não foge desses princípios:
- É feito para seres humanos, não máquinas, então legibilidade é crucial.
- Ser fácil de referenciar (*linkar*) qualquer seção (por isso Markdown ao
invés de puro texto).
- Uma sub-seção por versão.
- Lista as versões publicadas em ordem cronológica decrescente (mais novo em
cima).
- Escreva todas as datas no formato `AAAA-MM-DD`. (Exemplo: `2012-06-02` para
`2 de Junho de 2012`.) É internacional, [sensato](http://xkcd.com/1179/), e
independente de língua.
- Explicite se o projeto segue [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` para novas funcionalidades.
- `Changed` para mudanças em funcionalidades existentes.
- `Deprecated` para funcionalidades uma vez estáveis removidas das
próximas publicações.
- `Removed` para funcionalidades removidas desta versão.
- `Fixed` para qualquer correção de bug.
- `Security` para convidar usuários a atualizar em caso de
vulnerabilidades.
### Como eu posso minimizar o esforço exigido?
Mantenha sempre uma seção `Unreleased` 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ê tem que somente mudar Não publicado para o
número de versão e adicionar um novo cabeçalho `Unreleased` 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 descontinuações. Quando as pessoas atualizam de uma
versão para outra, deve ser incrivelmente claro quando algo irá quebrar.
- 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
sobrescreve de maneira ambígua outros formatos, e é um [padrão
ISO](http://www.iso.org/iso/home/standards/iso8601.htm). Portanto, é o
formato recomendado para *change logs*.
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 *change log*?
Infelizmente, não. Calma. Eu sei que você está indo impetuosamente achar
aquele link do guia de estilo de *change log* GNU, ou o arquivo "guideline"
de dois paragráfos GNU NEWS. O estilo GNU é um bom começo mas é 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 projetos open source. Pode a comunidade open
source aprender com seus erros e não agir como se os dez mandamentos foram
escritos a muito tempo atrás e estavam inteiramente certos? Tudo bem. Então
por favor dê um olhada e lembre que [discussões e sugestões de melhorias são
bem-vindas][issues]!
### Qual deve ser o nome do arquivo *change log*?
Bom, se você não notou no exemplo acima, `CHANGELOG.md` é a melhor padrã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 nome só dificultam as pessoas acharem.
### Por quê as pessoas não podem simplesmente utilizar `git log`?
Porque logs de commit são cheios de distrações. Podemos realmente esperar que
cada commit do projeto seja significativo e auto-explicativo? Só em sonho.
### Podem os *change logs* ser automaticamente interpretados?
É difícil, por que 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) change logs de projetos open source.
### Por que você alterna entre as grafias "CHANGELOG" e "change log"?
"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 serem mantidos no topo) é utilizado para chamar atenção a
eles. Já que eles são importante metadados sobre o projeto, eles podem ser
úteis a qualquer um pretendendo usar ou contribuir com ele, assim como os [as
badges de projeto open source][shields].
Quando eu me refiro a "*change log*", eu estou falando sobre a função deste
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 *change logs*. Deveriam. É assim que você deve exibi-las:
`## 0.0.5 - 2014-12-13 [YANKED]`
A tag `[YANKED]` é chamativa por uma razão. É importante que as pessoas a
notem. E já que é cercada por colchetes é mais fácil detectá-la
programaticamente.
### 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/master/CHANGELOG.md
[CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md
[LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE
[README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md
[gemnasium]: https://gemnasium.com/
[gh]: https://github.com/olivierlacan/keep-a-changelog
[issues]: https://github.com/olivierlacan/keep-a-changelog/issues
[semver]: http://semver.org/
[shields]: http://shields.io/
[thechangelog]: http://5by5.tv/changelog/127
[vandamme]: https://github.com/tech-angels/vandamme/