This commit is contained in:
Webysther Nunes 2017-10-10 18:10:24 -03:00
parent f8e8ed2304
commit 9d170cae75
No known key found for this signature in database
GPG Key ID: 5A00E5B36F1D82B0

View File

@ -177,136 +177,134 @@ version: 1.0.0
recomendado para as entradas do <em>changelog</em>. recomendado para as entradas do <em>changelog</em>.
%aside %aside
Theres more. Help me collect these antipatterns by Tem mais. Me ajude a colecionar essas más práticas
= link_to "opening an issue", issues      = link_to "enviando uma dúvida", issues
or a pull request.      ou pedindo mudanças.
.frequently-asked-questions .frequently-asked-questions
%h3#frequently-asked-questions %h3#frequently-asked-questions
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" } %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
Frequently Asked Questions Perguntas frequentes
%h4#standard %h4#standard
%a.anchor{ href: "#standard", aria_hidden: "true" } %a.anchor{ href: "#standard", aria_hidden: "true" }
Is there a standard changelog format? Existe um padrão para o formato do <em>changelog</em>?
%p %p
Not really. There's the GNU changelog style guide, or the two- Na verdade não. Existe o guia de estilo de <em>changelog</em> do
paragraph-long GNU NEWS file "guideline". Both are inadequate or GNU ou o "guia" de dois parágrafos do GNU NEWS. Ambos são inadequados
insufficient. ou insuficientes.
%p %p
This project aims to be Este projeto pretende ser
= link_to "a better changelog convention.", changelog     = link_to "uma convenção de <em>changelog</em> melhor.", changelog
It comes from observing good practices in the open source     Ele vem de observar e coletar as boas práticas em código aberto da comunidade.
community and gathering them.
%p %p
Healthy criticism, discussion and suggestions for improvements Críticas saudáveis, discussões e sugestões de melhorias
= link_to "are welcome.", issues = link_to "são bem-vindas.", issues
%h4#filename %h4#filename
%a.anchor{ href: "#filename", aria_hidden: "true" } %a.anchor{ href: "#filename", aria_hidden: "true" }
What should the changelog file be named? Qual nome o arquivo <em>changelog</em> deve ter?
%p %p
Call it <code>CHANGELOG.md</code>. Some projects use Chame-o <code>CHANGELOG.md</code>. Alguns projetos usam
<code>HISTORY</code>, <code>NEWS</code> or <code>RELEASES</code>. <code>HISTORY</code>, <code>NEWS</code> ou <code>RELEASES</code>.
%p %p
While it's easy to think that the name of your changelog file Embora seja fácil pensar que o nome do seu arquivo <em>changelog</em>
doesn't matter that much, why make it harder for your end users to não importa muito, por que tornar mais difícil para seus usuários
consistently find notable changes? finais encontrarem consistentemente mudanças notáveis?
%h4#github-releases %h4#github-releases
%a.anchor{ href: "#github-releases", aria_hidden: "true" } %a.anchor{ href: "#github-releases", aria_hidden: "true" }
What about GitHub Releases? E sobre o <em>GitHub Releases</em>?
%p %p
It's a great initiative. #{link_to "Releases", ghr} can be used to É uma grande iniciativa. #{link_to "Lançamentos", ghr} podem ser usados
turn simple git tags (for example a tag named <code>v1.0.0</code>) para converter simples marcadores do <em>git</em> (por exemplo, um
into rich release notes by manually adding release notes or it can marcador chamado <code>v1.0.0</code>) em notas de versão ricas,
pull annotated git tag messages and turn them into notes. adicionando manualmente notas de versão ou pode puxar as mensagens
anotadas no marcador do <em>git</em> e transformá-las em notas.
%p %p
GitHub Releases create a non-portable changelog that can only be <em>GitHub Releases</em> cria um <em>changelog</em> não portátil
displayed to users within the context of GitHub. It's possible to que só pode ser exibido para usuários no contexto do GitHub.
make them look very much like the Keep a Changelog format, but it É possível fazê-los parecer muito como o formato
tends to be a bit more involved. <em>Keep a Changelog</em>, mas tende a estar um pouco mais envolvido.
%p %p
The current version of GitHub releases is also arguably not very A versão atual do <em>GitHub Releases</em> não são facilmente
discoverable by end-users, unlike the typical uppercase files por usuários finais, ao contrário dos arquivos maiúsculos típicos
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Another (<code>README</code>, <code>CONTRIBUTING</code>, etc.). Outro
minor issue is that the interface doesn't currently offer links to problema menor é que a interface atualmente não oferece links para
commit logs between each release. confirmar alterações entre cada lançamento.
%h4#automatic %h4#automatic
%a.anchor{ href: "#automatic", aria_hidden: "true" } %a.anchor{ href: "#automatic", aria_hidden: "true" }
Can changelogs be automatically parsed? Os <em>changelogs</em> podem ser criados automaticamente?
%p %p
Its difficult, because people follow wildly different formats and É difícil, porque as pessoas seguem formatos e nomes de arquivos
file names. totalmente diferentes.
%p %p
#{link_to "Vandamme", vandamme} is a Ruby gem created by the #{link_to "Vandamme", vandamme} é um <em>gem Ruby</em> criado pelo
#{link_to "Gemnasium", gemnasium} team and which parses many (but time #{link_to "Gemnasium", gemnasium} e que analisa muitas
not all) open source project changelogs. (mas não todas) alterações de projetos de código aberto.
%h4#yanked %h4#yanked
%a.anchor{ href: "#yanked", aria_hidden: "true" } %a.anchor{ href: "#yanked", aria_hidden: "true" }
What about yanked releases? E o lançamentos removidos?
%p %p
Yanked releases are versions that had to be pulled because of a Lançamentos removidos são versões que foram retiradas por causa de
serious bug or security issue. Often these versions don't even problemas sérios ou falhas de segurança. Muitas vezes essas versões
appear in change logs. They should. This is how you should display nem aparecem no histórico de alterações. Eles deviam. É assim que
them: você deve exibi-los:
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code> %p <code>## 0.0.5 - 2014-12-13 [REMOVIDO]</code>
%p %p
The <code>[YANKED]</code> tag is loud for a reason. It's important O marcador <code>[REMOVIDO]</code> está em caixa alta por uma razão.
for people to notice it. Since it's surrounded by brackets it's also É importante que as pessoas o percebam. Uma vez que está entre
easier to parse programmatically. colchetes é fácil de ser analisado programaticamente.
%h4#rewrite %h4#rewrite
%a.anchor{ href: "#rewrite", aria_hidden: "true" } %a.anchor{ href: "#rewrite", aria_hidden: "true" }
Should you ever rewrite a changelog? Você deve reescrever um <em>changelog</em>?
%p %p
Sure. There are always good reasons to improve a changelog. I Claro. Sempre existe razão para melhorar um <em>changelog</em>. Eu
regularly open pull requests to add missing releases to open source regularmente solicito uma alteração em projetos de código livre
projects with unmaintained changelogs. para adicionar <em>changelogs</em> não mantidos.
%p %p
It's also possible you may discover that you forgot to address a Também é possível que você descubra que você esqueceu de abordar
breaking change in the notes for a version. It's obviously important uma mudança abrupta nas notas para uma versão.
for you to update your changelog in this case. Obviamente é importante para você atualizar seu <em>changelog</em> neste caso.
%h4#contribute %h4#contribute
%a.anchor{ href: "#contribute", aria_hidden: "true" } %a.anchor{ href: "#contribute", aria_hidden: "true" }
How can I contribute? Como eu posso ajudar?
%p %p
This document is not the <strong>truth</strong>; its my carefully Esse documento não é uma <strong>verdade absoluta</strong>; É minha
considered opinion, along with information and examples I gathered. opinião cuidadosamente considerada, juntamente com informações e
exemplos que eu reuni.
%p %p
This is because I want our community to reach a consensus. I believe Isso é porque eu quero que nossa comunidade chegue a um consenso.
the discussion is as important as the end result. Eu acredito que a discussão é tão importante quanto o resultado final.
%p %p
So please <strong>#{link_to "pitch in", gh}</strong>. Então, por favor <strong>#{link_to "contribua", gh}</strong>.
.press .press
%h3 Conversations %h3 Discussões
%p %p
I went on #{link_to "The Changelog podcast", thechangelog} Eu fui em #{link_to "<em>The Changelog podcast</em>", thechangelog}
to talk about why maintainers and contributors should care about changelogs, para falar sobre por que os mantenedores e contribuidores devem se
and also about the motivations behind this project. preocupar com os <em>changelogs</em>, e também sobre as motivações
por trás desse projeto.