diff --git a/CHANGELOG.md b/CHANGELOG.md index c71ab8d..d28bf4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/source/pt-BR/1.1.0/index.html.haml b/source/pt-BR/1.1.0/index.html.haml new file mode 100644 index 0000000..927077b --- /dev/null +++ b/source/pt-BR/1.1.0/index.html.haml @@ -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 para humanos, 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 Não publicado 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 Não publicado + 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 2017-07-17 é 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 CHANGELOG.md. Alguns projetos usam + HISTORY, NEWS ou RELEASES. + + %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 v1.0.0) + 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 + (README, CONTRIBUTING 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 ## [0.0.5] - 2014-12-13 [REMOVIDO] + + %p + O marcador [REMOVIDO] 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 verdade absoluta; É 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 #{link_to "contribua", data.links.repo}. + +.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.