svn commit: r52248 - head/pt_BR.ISO8859-1/articles/problem-reports
Edson Brandi
ebrandi at FreeBSD.org
Wed Sep 12 02:10:26 UTC 2018
Author: ebrandi
Date: Wed Sep 12 02:10:25 2018
New Revision: 52248
URL: https://svnweb.freebsd.org/changeset/doc/52248
Log:
pt_BR.ISO8859-1/articles/problem-reports: converted to .po
* content synchronized with en_US document (rev 51348)
* article.xml converted to .po
* .po file was translated to pt_BR
* pt_BR.po and article.xml file has been set to UTF-8 encoding
* information about volunteers who translated and/or revised the document was added to the header of the .po file.
Approved by: gabor (mentor, implicit)
Obtained from: The FreeBSD Brazilian Portuguese Documentation Project
Added:
head/pt_BR.ISO8859-1/articles/problem-reports/pt_BR.po (contents, props changed)
Modified:
head/pt_BR.ISO8859-1/articles/problem-reports/article.xml (contents, props changed)
Modified: head/pt_BR.ISO8859-1/articles/problem-reports/article.xml
==============================================================================
--- head/pt_BR.ISO8859-1/articles/problem-reports/article.xml Wed Sep 12 00:52:17 2018 (r52247)
+++ head/pt_BR.ISO8859-1/articles/problem-reports/article.xml Wed Sep 12 02:10:25 2018 (r52248)
@@ -1,1063 +1,342 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<!--
- The FreeBSD Documentation Project
- The FreeBSD Brazilian Portuguese Documentation Project
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:its="http://www.w3.org/2005/11/its" version="5.0" xml:lang="pt_BR">
- Original revision: r39544
--->
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="pt_br">
- <info><title>Escrevendo Relatórios de Problema no &os;</title>
-
+ <info>
+ <title>Escrevendo Relatórios de Problemas para o FreeBSD</title>
<legalnotice xml:id="trademarks" role="trademarks">
- &tm-attrib.freebsd;
- &tm-attrib.cvsup;
- &tm-attrib.ibm;
- &tm-attrib.intel;
- &tm-attrib.sparc;
- &tm-attrib.sun;
- &tm-attrib.general;
+ <para>FreeBSD is a registered trademark of the FreeBSD Foundation.</para>
+ <para>IBM, AIX, OS/2, PowerPC, PS/2, S/390, and ThinkPad are trademarks of International Business Machines Corporation in the United States, other countries, or both.</para>
+ <para>Intel, Celeron, Centrino, Core, EtherExpress, i386, i486, Itanium, Pentium, and Xeon are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.</para>
+ <para>SPARC, SPARC64, and UltraSPARC are trademarks of SPARC International, Inc in the United States and other countries. SPARC International, Inc owns all of the SPARC trademarks and under licensing agreements allows the proper use of these trademarks by its members.</para>
+ <para>Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS and VirtualBox are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.</para>
+ <para>Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the <quote>™</quote> or the <quote>®</quote> symbol.</para>
</legalnotice>
- <pubdate>$FreeBSD$</pubdate>
+ <pubdate xml:lang="en">$FreeBSD$</pubdate>
- <releaseinfo>$FreeBSD$</releaseinfo>
+ <releaseinfo xml:lang="en">$FreeBSD$</releaseinfo>
<abstract>
- <para>Este artigo descreve qual a melhor forma de formular e
- de submeter um relatório de problema para Projeto
- &os;.</para>
+ <para>Este artigo descreve como redigir e submeter um bom relatório de problemas ao Projeto FreeBSD.</para>
</abstract>
<authorgroup>
- <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contribuido por</contrib></author>
+ <author><personname> <firstname>Dag-Erling</firstname> <surname>Smørgrav</surname> </personname> <contrib> ContribuÃdo por </contrib></author>
- <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
+ <author><personname> <firstname> Mark</firstname> <surname>Linimon</surname> </personname></author>
</authorgroup>
</info>
- <indexterm><primary>relatório de problema</primary>
- </indexterm>
+ <indexterm><primary>relatórios de problemas</primary></indexterm>
<section xml:id="pr-intro">
- <title>Introdução</title>
+ <title>Introdução</title>
- <para>Uma das experiências mais frustrantes que
- alguém pode ter como um usuário de um software
- é submeter um relatório sobre um problema
- que está enfrentando apenas para vê-lo ser
- sumariamente fechado com uma informação curta
- e pouco útil do tipo <quote>isto não é
- um bug</quote> ou ainda <quote>este relatório de
- problema não procede</quote>. Da mesma forma, uma das
- experiências mais frustrantes para um desenvolvedor de
- software é ser inundado com relatórios de
- problemas que na verdade não são realmente
- relatórios de problemas, mas sim
- solicitações de suporte, ou então que
- contenham pouca ou nenhuma informação sobre como
- o problema ocorre e sobre como proceder para
- reproduzi-lo.</para>
-
- <para>Este documento tem por objetivo descrever como escrever
- bons relatórios de problema. Mas o que vem a ser um
- bom relatório de problema? Bem, indo direto ao ponto,
- um bom relatório de problema é aquele que se
- pode analisar e tratar rapidamente, para a
- satisfação mútua do usuário e do
- desenvolvedor.</para>
-
- <para>Embora o foco primário deste artigo seja a
- elaboração de relatórios de problemas no
- &os;, a maior parte das recomendações deve
- aplicar-se muito bem a outros projetos de software.</para>
-
- <para>Observe que este artigo esta organizado de forma
- temática, e não de forma cronológica,
- desta forma você deve ler o documento inteiro antes
- de enviar um relatório de problema, ao invés
- de tratá-lo como um tutorial passo-a-passo.</para>
+ <para>Uma das experiências mais frustrantes que alguém pode ter como usuário de um software é submeter um relatório de problema apenas para vê-lo ser encerrado sumariamente com uma explicação curta e inútil tal como <quote>não é um bug</quote> ou <quote>PR Falso</quote>. Da mesma forma, uma das experiências mais frustrantes como desenvolvedor de software é ser inundado com relatórios de problemas que não são realmente relatórios de problemas mas sim pedidos de suporte, ou então por relatórios que contêm pouca ou nenhuma informação sobre o que é o problema e sobre como reproduzi-lo.</para>
+
+ <para>Este documento tenta descrever como escrever bons relatórios de problemas. O que, alguém pergunta, é um bom relatório de problemas? Bem, para ir diretamente para ao ponto, um bom relatório de problema é aquele que pode ser analisado e tratado rapidamente, para a satisfação mútua do usuário e do desenvolvedor.</para>
+
+ <para>Embora o foco principal deste artigo esteja nos relatórios de problemas do FreeBSD, a maioria das recomendações deve se aplicar muito bem a outros projetos de software.</para>
+
+ <para>Observe que este artigo é organizado por temas, não de uma forma cronológica. Leia todo o documento antes de enviar um relatório de problemas, em vez de tratá-lo como um tutorial passo a passo.</para>
</section>
<section xml:id="pr-when">
- <title>Quando enviar um relatório de problema</title>
+ <title>Quando Enviar um Relatório de Problemas</title>
- <para>Existem muitos tipos de problemas, e nem todos eles devem
- gerar um relatório de problema. É claro,
- ninguém é perfeito e em algumas ocasiões
- você terá certeza de que encontrou um bug em um
- determinado software quando na verdade você compreendeu
- errado a sintaxe de um comando ou mesmo cometeu um erro de
- digitação em um arquivo de
- configuração (o que por sua vez pode indicar
- uma documentação pouco detalhada ou
- então um tratamento inadequado do erro por parte
- da aplicação). Existem ainda muitas outras
- situações nas quais enviar um relatório de
- problema claramente <emphasis>não</emphasis> é
- a melhor ação a ser tomada, e só vai
- servir para frustrar a você e aos desenvolvedores. Em
- contrapartida, existem situações nas quais
- é recomendado que você nos envie um
- relatório de problema sobre outras coisas que
- não um bug, como por exemplo para nos enviar uma
- sugestão de melhoria ou um pedido de uma nova
- funcionalidade.</para>
-
- <para>Então como você irá diferenciar o que
- é e o que não é um bug? Existe uma regra
- de ouro que diz que o seu problema <emphasis>não
- é</emphasis> um bug se ele pode ser expresso como uma
- pergunta (normalmente na forma <quote>Como eu faço
- X</quote> ou <quote>Onde eu posso encontrar Y</quote>). Na
- maior parte das vezes não será sempre
- tão claro desta forma, mas a regra acima cobre a grande
- maioria dos casos. Se você estiver procurando por uma
- resposta, considere enviar a sua pergunta para
- &a.questions;.</para>
-
- <para>Veja alguns casos nos quais pode ser apropriado enviar um
- relatório de problema sobre algo que não é
- um bug:</para>
+ <para>Existem muitos tipos de problemas, e nem todos devem gerar um relatório de problemas. Naturalmente, ninguém é perfeito, e haverá momentos em que o que parece ser um bug em um programa é, na verdade, um equÃvoco na sintaxe de um comando ou um erro tipográfico em um arquivo de configuração (embora isto por si só possa ser um indicativo de uma documentação deficiente ou de deficiências no manuseio de erros pelo aplicativo). Existem ainda muitos casos em que submeter um relatório de problema claramente <emphasis>não</emphasis> é o curso de ação correto, e só servirá para frustrar tanto o usuário e quanto o desenvolvedor. Por outro lado, existem casos em que pode ser apropriado enviar um relatório de problema sobre algo diferente de um bug - tal como um aprimoramento ou um novo recurso, por exemplo.</para>
+ <para>Então, como se determina o que é um bug e o que não é? Como uma regra simples, o problema <emphasis>não</emphasis> é um bug se ele puder ser expresso como uma pergunta (geralmente na forma <quote>Como faço X?</quote> ou <quote>Onde posso encontrar Y?</quote>). Nem sempre é tão preto e branco, mas a regra da pergunta cobre a grande maioria dos casos. Ao procurar por uma resposta, considere colocar a questão na <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions">lista de discussão de perguntas gerais sobre o FreeBSD</link>.</para>
+
+ <para>Considere estes fatores ao enviar PRs sobre ports ou outros softwares que não fazem parte do próprio FreeBSD:</para>
+
<itemizedlist>
<listitem>
- <para>Pedidos de melhorias nas funcionalidades. Geralmente
- é uma boa idéia debater estas propostas nas
- listas de discussão antes de enviá-las em um
- relatório de problemas.</para>
+ <para>Por favor, não envie relatórios de problemas que simplesmente afirmam que uma versão mais nova de um aplicativo está disponÃvel. Os mantenedores de ports são notificados automaticamente pelo <application>portscout</application> quando uma nova versão de um aplicativo fica disponÃvel. Patches para atualizar um port para uma versão mais recente do software são sempre bem-vindos.</para>
</listitem>
<listitem>
- <para>Notificações sobre
- atualizações de softwares mantidos
- externamente (principalmente do ports, mas também
- de componentes do sistema base como, por exemplo, o BIND e
- vários outros utilitários GNU).</para>
+ <para>Para ports não mantidos (O seu <varname>MAINTAINER</varname> é <literal>ports at FreeBSD.org</literal>), é improvável que um PR que não tenha um patch incluÃdo seja escolhido para ser trabalhado por um committer. Para se tornar o mantenedor de um port não mantido, envie um PR com o pedido (será ótimo se o pedido vier com um patch, mas isso não é obrigatório).</para>
+ </listitem>
- <para>Para os ports sem manutenção
- (aqueles nos quais a variável
- <varname>MAINTAINER</varname> contém
- <literal>ports at FreeBSD.org</literal>), essas
- notificações de atualização
- podem ser capturadas por um <literal>committer</literal>
- interessado, ou você pode ser solicitado a fornecer
- um <literal>patch</literal> para atualizar o port;
- disponibilizar este <literal>patch</literal> antecipadamente
- irá melhorar de forma significativa as suas chances
- de ter o port atualizado rapidamente.</para>
-
- <para>Se o port possui um mantenedor, o envio de um
- relatório de problema comunicando sobre o
- lançamento de uma nova versão geralmente
- não é muito útil uma vez que eles geram
- trabalho adicional para os <literal>committers</literal>,
- e o mantenedor provavelmente já tem conhecimento de
- que existe uma nova versão, ele provavelmente
- já trabalhou com os desenvolvedores para
- atualizá-lo e está provavelmente executando
- testes para verificar se não existem problemas,
- etc.</para>
-
- <para>Em ambos os casos, você irá obter melhores
- resultados se seguir o processo descrito no <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's Handbook</link>.
- (Talvez você também queira ler o artigo <link xlink:href="&url.articles.contributing-ports;/article.html">
- Contribuindo para a Coleção de Ports
- do &os;</link>.)</para>
+ <listitem>
+ <para>Em ambos os casos, seguir o processo descrito no <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/porters-handbook/port-upgrading.html">Porter's Handbook</link> produzirá os melhores resultados. (Você também pode desejar ler a seção <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributing/ports-contributing.html">Contribuindo para a Coleção de Ports do FreeBSD</link>.)</para>
</listitem>
</itemizedlist>
- <para>Um bug que não pode ser reproduzido, raramente
- será corrigido. Se o bug ocorreu uma única
- vez e você não consegue reproduzi-lo, e
- se aparentemente ele não ocorre com mais ninguém,
- as chances são de que nenhum dos desenvolvedores
- será capaz de reproduzir ou de saber o que está
- errado. Isso não significa que não seja
- possível, mas significa que a probabilidade do seu
- relatório de problema resultar na correção
- do bug é muito pequena. Para piorar a
- situação, muitas vezes este tipo de erro
- é, na realidade, causado por falhas nos discos
- rígidos ou por superaquecimento do processador —
- sempre que possível você deve tentar excluir estas
- causas antes de enviar um relatório de problema.</para>
+ <para>Um bug que não pode ser reproduzido raramente pode ser corrigido. Se o bug ocorreu apenas uma vez e você não pode reproduzi-lo, e não parece acontecer com mais ninguém, é muito provável que nenhum dos desenvolvedores consiga reproduzi-lo ou descobrir o que está errado. Isso não significa que isso não tenha acontecido, mas significa que as chances do seu relatório de problema levar à correção do bug são muito pequenas. Para piorar, muitas vezes esses tipos de bugs são causados por discos rÃgidos com defeito ou por processadores superaquecidos - sempre que possÃvel você deve tentar descartar essas causas antes de enviar um PR.</para>
- <para>Em seguida, para decidir a quem você deve apresentar
- o seu relatório de problema, você precisa
- entender que o &os; é composto de vários
- elementos de software diferentes:</para>
-
+ <para>Em seguida, para decidir para quem você deve enviar seu relatório de problema, você precisa entender que o software que compõe o FreeBSD é composto por vários elementos diferentes:</para>
+
<itemizedlist>
<listitem>
- <para>Código na base do sistema que é escrito
- e mantido por colaboradores do &os;, tais como o Kernel, a
- biblioteca C, os drivers de dispositivos (categorizados
- como <literal>kern</literal>); os utilitários
- binários (<literal>bin</literal>); as páginas
- de manual e a documentação
- (<literal>docs</literal>); e as páginas web
- (<literal>www</literal>). Todos os bugs nestas
- áreas devem ser reportados para os desenvolvedores
- do &os;</para>
+ <para>Código no sistema base que é escrito e mantido por contribuidores do FreeBSD, como o kernel, a biblioteca C e os drivers de dispositivo (categorizados como <literal>kern</literal>); os utilitários binários (<literal>bin</literal>); as páginas de manual e documentação (<literal>docs</literal>); e as páginas web (<literal>www</literal>). Todos os erros nestas áreas devem ser reportados aos desenvolvedores do FreeBSD.</para>
</listitem>
<listitem>
- <para>Código na base do sistema que é escrito
- e mantido por outros, e que foram adaptados e importados
- no &os;. Exemplos incluen <application>bind</application>,
- &man.gcc.1;, e &man.sendmail.8;. A maioria dos bugs nestas
- áreas devem ser reportados para os desenvolvedores do
- &os;; mas em alguns casos pode ser necessário
- reportá-los aos autores originais, caso o problema
- não seja especifico do &os;. Normalmente estes bugs
- irão ficar sob as categorias <literal>bin</literal>
- ou <literal>gnu</literal>.</para>
+ <para>Código no sistema base que é escrito e mantido por outras pessoas, o qual é importado e adaptado para o FreeBSD. Exemplos incluem o <citerefentry><refentrytitle>clang</refentrytitle><manvolnum>1</manvolnum></citerefentry> e o <citerefentry><refentrytitle>sendmail</refentrytitle><manvolnum>8</manvolnum></citerefentry>. A maioria dos bugs nessas áreas deve ser reportada aos desenvolvedores do FreeBSD; mas em alguns casos eles podem precisar ser relatados aos autores originais se os problemas não forem especÃficos do FreeBSD.</para>
</listitem>
<listitem>
- <para>Os aplicativos individuais que não estão
- na base do sistema, mas que fazem parte da
- coleção de Ports do &os; (Categoria
- <literal>ports</literal>). A maioria destes aplicativos
- não são escritos por desenvolvedores do
- &os;; o que o &os; oferece é apenas um sistema para
- facilitar a instalação do aplicativo.
- Portanto, você deve relatar um problema para os
- desenvolvedores do &os; apenas quando você acreditar
- que o problema é específico do &os;, caso
- contrário, você deve reportá-lo aos
- autores do software.</para>
+ <para>Aplicativos individuais que não estão no sistema base, mas que são parte da coleção de ports do FreeBSD (categoria <literal>ports</literal>). A maioria desses aplicativos não são escritos por desenvolvedores do FreeBSD; o que o FreeBSD fornece é meramente um framework para instalar o aplicativo. Portanto, apenas relate um problema para os desenvolvedores do FreeBSD quando o problema for considerado especÃfico do FreeBSD; caso contrário, informe aos autores do software.</para>
</listitem>
-
</itemizedlist>
- <para>A seguir você deve verificar se o problema é
- ou não atual. Existem poucas coisas que aborrecem um
- desenvolvedor mais do que receber um relatório de
- problema a respeito de um bug que ele já corrigiu.</para>
-
- <para>Se o problema está na base do sistema, você
- deverá primeiro ler a seção do FAQ sobre
- <link xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION">
- Versões do &os;</link>, se você não estiver
- familiarizado com o tema. Não é possível
- para o &os; corrigir problemas em versões muito antigas
- do sistema base, desta forma enviar um relatório de
- problema sobre um bug em uma versão muito antiga vai
- provavelmente resultar apenas em um desenvolvedor aconselhando
- que você atualize o seu sistema para uma versão
- suportada para ver se o problema ainda ocorre. A equipe
- de <literal>Security Officer</literal> mantém a
- <link xlink:href="&url.base;/security/">lista de versões
- suportadas</link>.</para>
+ <para>Em seguida, verifique se o problema é oportuno. Há poucas coisas que incomodarão mais um desenvolvedor do que receber um relatório de problemas sobre um bug que ele já corrigiu.</para>
- <para>Se o problema está em um port, observe que
- você deverá primeiro atualizar seu sistema para a
- versão mais atual da coleção de ports e ver
- se o problema ainda se aplica. Devido ao ritmo acelerado de
- mudanças nestas aplicações, é
- inviável para o &os; suportar qualquer coisa que
- não seja obrigatoriamente a versão mais
- recente, e problemas com uma versão antiga do
- aplicativo simplesmente não podem ser corrigidos.</para>
+ <para>Se o problema estiver no sistema base, primeiro leia a seção <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/introduction.html#LATEST-VERSION"> Versões do FreeBSD</link> do FAQ, se você ainda não estiver familiarizado com o tópico. Não é possÃvel para o FreeBSD consertar problemas em nada além de certas branchs recentes do sistema base, de forma que enviar um relatório de bug sobre uma versão mais antiga provavelmente resultará em um desenvolvedor aconselhando você a atualizar para uma versão suportada para ver se o problema ainda continua ocorrendo. A equipe do Security Officer mantém a <link xlink:href="@@URL_RELPREFIX@@/security/">lista das versões suportadas </link>.</para>
+
+ <para>Se o problema estiver em um port, observe que você deverá primeiro atualizar para a versão mais recente da Coleção de Ports e verificar se o problema ainda se aplica. Devido ao ritmo acelerado de mudanças nesses aplicativos, é inviável que o FreeBSD ofereça suporte para qualquer coisa que não seja absolutamente a versão mais recente e os problemas com versões mais antigas de aplicativos simplesmente não podem ser corrigidos.</para>
</section>
<section xml:id="pr-prep">
- <title>Preparação</title>
+ <title>Preparativos</title>
- <para>Uma boa regra a ser seguida sempre é realizar uma
- busca a respeito do assunto antes de enviar um relatório
- de problema. Pode ser que o seu problema já tenha sido
- reportado anteriormente; pode ser que esteja sendo debatido nas
- listas de discussão ou que tenha sido recentemente; pode
- até ser que o problema já tenha sido corrigido em
- uma versão mais recente do que a que você
- está utilizando. Você deve portanto verificar
- em todos os lugares óbvios antes de enviar o
- relatório de problema. Para o &os;, isto
- significa:</para>
-
+ <para>Uma boa regra a seguir é sempre fazer uma pesquisa sobre o tema antes de enviar um relatório de problemas. Talvez o problema já tenha sido relatado anteriormente; talvez esteja sendo discutido nas listas de discussão, ou foi discutido recentemente; pode até mesmo já estar corrigido em uma versão mais recente da que você está executando. Portanto, você deve verificar todos os lugares óbvios antes de enviar seu relatório de problemas. Para o FreeBSD, isso significa:</para>
+
<itemizedlist>
<listitem>
- <para>A lista de <link xlink:href="&url.books.faq;/index.html">Perguntas e Respostas mais
- Frequentes</link> sobre o &os; (FAQ). A FAQ tem por
- objetivo fornecer respostas para uma grande variedade de
- perguntas, tais como as que dizem respeito a <link xlink:href="&url.books.faq;/hardware.html">compatibilidade de
- hardware</link>, <link xlink:href="&url.books.faq;/applications.html">aplicações
- do usuário</link>, <link xlink:href="&url.books.faq;/kernelconfig.html">Configuração
- do kernel</link>, etc.</para>
+ <para>A lista das <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/index.html">Perguntas Mais Freqüentes</link> (FAQ) sobre o FreeBSD. A FAQ tenta fornecer respostas para uma ampla variedade de perguntas, como aquelas relacionadas à <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/hardware.html">compatibilidade de hardware </link>, <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/applications.html"> aplicativos de usuário</link> e <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/faq/kernelconfig.html"> configuração do kernel</link>.</para>
</listitem>
<listitem>
- <para>As <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">
- listas de discussão</link> — se você
- não está inscrito, utilize a <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">
- busca do histórico</link> no web site do
- &os;. Se o seu problema não tiver sido discutido nas
- listas, você pode tentar enviar uma mensagem sobre ele
- e aguardar alguns dias para ver se alguém consegue
- perceber algo que você tenha deixado passar
- desapercebido.</para>
+ <para>As <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">listas de discussão</link> - se você não está inscrito, faça uma pesquisa nos arquivos <link xlink:href="https://www.FreeBSD.org/search/search.html#mailinglists">históricos das listas</link> no site do FreeBSD. Se o problema não tiver sido discutido nas listas, você pode tentar postar uma mensagem sobre ele e aguardar alguns dias para ver se alguém consegue detectar algo que foi esquecido.</para>
</listitem>
<listitem>
- <para>Opcionalmente, na internet inteira — utilize seu
- mecanismo de busca preferido para localizar
- referências sobre o seu problema. Você pode
- encontrar referências a ele em mensagens de listas de
- discussão ou de grupos de noticias dos quais
- você nunca ouviu falar ou nos quais sequer pensou
- em procurar.</para>
+ <para>Opcionalmente, na web toda - use seu mecanismo de pesquisa favorito para localizar qualquer referência ao problema. Você pode até receber hits de listas de discussão arquivadas ou grupos de notÃcias que você não conhecia ou que não pensou em pesquisar.</para>
</listitem>
<listitem>
- <para>Na sequência, verifique o <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
- banco de dados com os relatórios de problema do
- &os;</link> (GNATS). A menos que o seu problema seja
- recente ou muito obscuro, existe uma boa chance dele
- já ter sido reportado.</para>
+ <para>Em seguida, faça uma pesquisa no <link xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">banco de dados de Relatórios de Problemas do FreeBSD</link> (Bugzilla). A menos que o problema seja recente ou obscuro, há uma boa chance de que ele já tenha sido relatado.</para>
</listitem>
<listitem>
- <para>E o mais importante, você deve verificar se a
- documentação existente no código base
- não endereça o seu problema.</para>
-
- <para>Para o código base do &os; você deve
- estudar cuidadosamente o conteúdo do arquivo
- <filename>/usr/src/UPDATING</filename> disponível no
- seu sistema de arquivos ou a sua versão mais
- recente no <link xlink:href="http://svnweb.freebsd.org/base/head/UPDATING">
- Repositório Subversion</link>. (Esta
- informação é vital se você
- estiver atualizando de uma versão para outra
- — especialmente se estiver atualizando para o
- &os.current;).</para>
-
- <para>No entanto, se o problema é com algo que foi
- instalado como uma parte da coleção de ports
- do &os; você deve consultar o
- <filename>/usr/ports/UPDATING</filename> (para os ports
- individuais) ou o <filename>/usr/ports/CHANGES</filename>
- (para mudanças que afetam a Coleção de
- Ports inteira). Estes arquivos também estão
- disponíveis no SVNWeb, nos urls <uri xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING">http://svnweb.freebsd.org/ports/head/UPDATING</uri>
- e <uri xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES">http://svnweb.freebsd.org/ports/head/CHANGES</uri>
- respectivamente.</para>
+ <para>Mais importante ainda, tente verificar se a documentação existente não endereça o seu problema.</para>
+
+ <para>Para o código fonte do FreeBSD, você deve estudar cuidadosamente o conteúdo do <filename>/usr/src/UPDATING</filename> em seu sistema ou a última versão disponÃvel em <uri xlink:href="https://svnweb.freebsd.org/base/head/UPDATING?view=log"> https://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>. (Esta é uma informação vital se você estiver atualizando de uma versão para outra - especialmente se você estiver atualizando para a Branch FreeBSD-CURRENT).</para>
+
+ <para>No entanto, se o problema estiver em algo que foi instalado como parte da coleção de ports do FreeBSD, você deve consultar <filename>/usr/ports/UPDATING</filename> (para ports individuais) ou <filename>/usr/ports/CHANGES</filename> (para alterações que afetam toda a coleção de ports). O <uri xlink:href="https://svnweb.freebsd.org/ports/head/UPDATING?view=log">https://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri> e o <uri xlink:href="https://svnweb.freebsd.org/ports/head/CHANGES?view=log">https://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri> também estão disponÃveis via svnweb.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="pr-writing">
- <title>Escrevendo o Relatório de Problema</title>
+ <title>Escrevendo o Relatório do Problema</title>
- <para>Agora que você decidiu que o seu assunto merece um
- relatório de problema (PR), e que ele é um
- problema do &os;, é hora de escrever o relatório
- em si. Mas antes de entrarmos na mecânica do programa
- utilizado para gerar e enviar os PRs, aqui estão
- algumas dicas e truques para ajudá-lo a garantir que o
- seu PR será o mais efetivo possível.</para>
-
- <section>
- <title>Dicas e truques para escrever um bom relatório de
- problema.</title>
+ <para>Agora que você decidiu que seu problema merece um relatório de problema e que ele é um problema especifico do FreeBSD, é hora de escrever o relatório de problema. Antes de entrarmos na mecânica do sistema utilizado para gerar e enviar os PRs, aqui estão algumas dicas e truques para ajudar a garantir que seu o PR seja mais eficaz.</para>
+ <section xml:id="pr-writing-tips">
+ <title>Dicas e Truques para Escrever um Bom Relatório de Problemas</title>
+
<itemizedlist>
<listitem>
- <para><emphasis>Não deixe a linha de
- <quote>Synopsis</quote> (sinopse) em branco.</emphasis>
- Os PRs são enviados para listas de discussão
- no mundo todo (nas quais a <quote>Synopsis</quote>
- é utilizada como linha de
- <literal>Subject:</literal>), além de serem
- armazenados em um banco de dados. Qualquer pessoa
- que vier a navegar no banco de dados pelas
- sinopses, e encontrar um PR com a linha de assunto
- em branco, tende a pulá-lo. Lembre-se que os PRs
- permanecem na base de dados até que sejam fechados
- por alguém; os anônimos normalmente
- irão desaparecer em meio ao ruído.</para>
+ <para><emphasis>Não deixe a linha <quote>Synopsis</quote> (Sinopse) vazia. </emphasis>Os PRs são enviados para listas de discussão no mundo todo (nas quais <quote>Synopsis</quote> é usado para na linha de <literal>Subject:</literal>), além de serem armazenadas em um banco de dados. Qualquer pessoa que vier a navegar no banco de dados pelas sinopses, e encontrar um PR com a linha de assunto em branco, tende a pulá-lo. Lembre-se que os PRs permanecem na base de dados até que sejam fechados por alguém; os anônimos normalmente irão desaparecer em meio ao ruÃdo.</para>
</listitem>
<listitem>
- <para><emphasis>Evite utilizar uma <quote>Synopsis</quote>
- (sinopse) fraca.</emphasis> Você não
- pode assumir que alguém que esteja lendo o seu PR
- conheça todo o contexto que motivou o seu envio,
- desta forma quanto mais informação
- você fornecer, melhor. Por exemplo, a que
- parte do sistema o problema se aplica? O problema
- ocorre durante a instalação ou durante a
- execução do sistema? Para ilustrar, ao
- invés de utilizar <literal>Synopsis: o
- portupgrade está quebrado</literal>, veja o
- quão mais claro e mais eficiente seria
- utilizar <literal>Synopsis: port sysutils/portupgrade
- gerando coredumps no -current</literal>. (No caso de um
- port, é especialmente útil ter a categoria
- e o nome do port na linha de sinopse.)</para>
+ <para><emphasis>Evite usar uma <quote>Sinopse</quote> (Sinopse) fraca. </emphasis> Você não deve presumir que alguém que esteja lendo seu PR conheça o contexto que motivou o seu envio, desta forma, quanto mais informação você fornecer, melhor. Por exemplo, a parte do sistema o problema se aplica? O problema ocorre durante a instalação ou durante a execução do sistema? Para ilustrar, em vez de usa <literal>Sinopse: o portupgrade está quebrado</literal>, veja o quanto mais informativo isso parece: <literal> Sinopse: port ports-mgmt/portupgrade gerando coredumps on -current</literal>. (No caso de um port, é especialmente útil ter tanto o nome da categoria quanto o nome do port na linha <quote>Sinopse</quote>.)</para>
</listitem>
<listitem>
- <para><emphasis>Se você possui um patch,
- mencione-o.</emphasis> Um PR que inclui um
- <literal>patch</literal> é muito mais
- provável de ser analisado do que um sem. Se
- você estiver incluindo um, coloque a palavra
- <literal>[patch]</literal> no inicio da linha
- de sinopse. (Embora não seja obrigatório
- utilizar exatamente esta palavra, por
- convenção, é ela que é
- utilizada.)</para>
+ <para><emphasis>Se você tem um patch, mencione-o.</emphasis> Um PR com um patch incluÃdo é muito mais provável de ser analisado do que um sem. Se você está incluindo um, coloque a palavra <literal>[patch]</literal> (incluindo os colchetes) no inÃcio da linha de <quote>Sinopse</quote>. (Embora não seja obrigatório usar exatamente essa palavra, por convenção, essa é a que é usada.)</para>
</listitem>
<listitem>
- <para><emphasis>Se você é um
- <literal>maintainer</literal> (mantenedor),
- diga-o.</emphasis> Se você está mantendo uma
- parte do código fonte (por exemplo, um port),
- você deve considerar a possibilidade de incluir as
- palavras <literal>[maintainer update]</literal> (incluindo
- os colchetes) no inicio da linha de sinópse e
- deve definir a <quote><literal>class</literal></quote>
- (classe) do seu PR para maintainer-update. Desta forma
- qualquer <literal>committer</literal> que manusear o seu
- PR não terá de verificar o
- <filename>Makefile</filename> do port, para certificar-se
- de que a atualização foi enviada pelo
- maintainer.</para>
+ <para><emphasis>Se você é um mantenedor, diga.</emphasis> Se você está mantendo uma parte do código fonte (por exemplo, um port), você pode considerar adicionar as palavras <literal>[atualização do mantenedor]</literal> (incluindo os colchetes) no inÃcio da sua linha de sinopse, e você definitivamente deve definir a <quote>Class</quote> (Classe) do seu PR para <literal>maintainer-update</literal>. Desta forma, qualquer committer que lide com seu PR não terá que verificar o Makefile do port, para certificar-se de que a atualização foi enviada pelo maintainer.</para>
</listitem>
<listitem>
- <para><emphasis>Seja específico.</emphasis> Quanto
- mais informações você fornecer sobre o
- problema que você está tendo, melhores
- serão as suas chances de obter uma resposta.</para>
+ <para><emphasis>Seja especÃfico.</emphasis> Quanto mais informações você fornecer sobre o problema que está tendo, maiores serão suas chances de obter uma resposta.</para>
<itemizedlist>
<listitem>
- <para>Inclua a versão do &os; que você
- está utilizando (existe um lugar para colocar
- esta informação, veja abaixo) e em qual
- arquitetura. Você incluir a
- informação se está executando a
- partir de um Release (e.g. de um CDROM ou Download),
- ou a partir de um sistema mantido com o &man.cvsup.1;
- (e neste caso, quando foi atualizado pela ultima
- vez). Se você estiver utilizando o
- &os.current;, esta vai ser a primeira coisa que
- alguém irá lhe perguntar, porque as
- correções (especialmente para os
- problemas de alto nível) tendem a serem
- realizadas muito rapidamente, e espera-se que os
- usuários do &os.current; mantenham-se
- atualizados.</para>
+ <para>Inclua a versão do FreeBSD que você está utilizando (há um lugar para colocar essa informação, veja abaixo) e em qual arquitetura. Você deve incluir se você está executando a partir de uma release (por exemplo, de um <acronym>CD-ROM</acronym> ou feito um download), ou de um sistema mantido pelo Subversion (e, caso seja afirmativo, em qual número de revisão você está). Se você estiver utilizando a branch FreeBSD-CURRENT, essa é a primeira coisa que alguém vai perguntar, porque as correções (especialmente para problemas de alto nÃvel) tendem a ser realizadas muito rapidamente, e é esperado que usuários do FreeBSD-CURRENT se mantenham atualizados.</para>
</listitem>
<listitem>
- <para>Inclua quais opções globais
- você especificou no seu
- <filename>make.conf</filename>.
- Observação: É conhecido que
- utilizar <literal>-O2</literal> (e acima disso) com o
- &man.gcc.1; gera problemas em muitas
- situações. Apesar dos desenvolvedores
- do &os; aceitarem patches, eles normalmente não
- estão dispostos a investigar este tipo de
- problema por uma simples falta de tempo e de
- voluntários, e ao invés disso podem
- responder apenas que isto não é
- suportado.</para>
+ <para>Inclua quais opções globais você especificou em seu <filename>make.conf</filename>. Nota: sabemos que especificar <literal>-O2</literal> e acima com o <citerefentry><refentrytitle>gcc</refentrytitle><manvolnum>1</manvolnum></citerefentry> gera bugs em muitas situações. Embora os desenvolvedores do FreeBSD aceitem patches, eles geralmente não estarão dispostos a investigar tais problemas devido a simples falta de tempo e de voluntários, ao invés disso podem apenas responder que isso simplesmente não é suportado.</para>
</listitem>
<listitem>
- <para>Se o problema pode ser reproduzido facilmente,
- inclua informações para possibilitar
- que ele seja reproduzido pelos desenvolvedores. Se
- o problema só pode ser
- demonstrado com a entrada de um conjunto de dados
- específico, você deverá incluir um
- exemplo destas informações, além
- de informar qual é resultado
- atual (errado) e qual era o resultado esperado
- (correto). Se o conjunto de dados for muito grande ou
- se o mesmo não puder ser tornado
- público, tente criar um arquivo com o
- mínimo
- de informações necessárias para
- replicar o problema, e que possa ser incluído
- no seu PR.</para>
+ <para>Se o problema puder ser reproduzido facilmente, inclua informações que irão ajudar um desenvolvedor a reproduzi-lo. Se um problema puder ser demonstrado com uma entrada especÃfica, então inclua um exemplo desta entrada se possÃvel, e inclua tanto a saÃda real quanto a esperada. Se esses dados forem grandes ou não puderem ser tornados públicos, então tente criar um arquivo pequeno que exiba o mesmo problema e que possa ser incluÃdo no PR.</para>
</listitem>
<listitem>
- <para>
- Se for um problema com o kernel, esteja preparado para
- fornecer as seguintes informações
- (Você não precisa fornecer estas
- informações por padrão, o que
- só tende a encher o banco de dados, mas
- você deve incluir os trechos acreditar que
- são relevantes):</para>
+ <para>Se este for um problema do kernel, esteja preparado para fornecer as seguintes informações. (Você não precisa incluÃ-las por padrão, o que apenas tende a preencher o banco de dados, mas você deve incluir os trechos que considera ser relevantes):</para>
+
<itemizedlist>
<listitem>
- <para>A configuração do seu kernel
- (incluindo quais dispositivos de hardware
- você tem instalados)</para>
+ <para>sua configuração do kernel (incluindo quais dispositivos de hardware você tem instalado)</para>
</listitem>
+
<listitem>
- <para>Se você tem ou não
- opções de depuração
- habilitadas (tais como
- <literal>WITNESS</literal>), e em caso afirmativo,
- se o problema continua ocorrendo quando
- você altera a lógica de
- configuração destas
- opções</para>
+ <para>independente de você ter ou não opções de debug habilitadas (como <literal>WITNESS</literal>), e se tiver, se o problema persiste quando você muda o sentido da opção</para>
</listitem>
+
<listitem>
- <para>O texto completo de qualquer
- <literal>backtrace</literal>,
- <literal>panic</literal> e outras
- mensagens no console, ou os registros do
- <filename>/var/log/messages</filename>, caso tenha
- sido gerado algum</para>
+ <para>o texto completo de qualquer backtrace, panic ou outra mensagens de console, ou registros em <filename>/var/log/messages</filename>, se houver sido gerado</para>
</listitem>
+
<listitem>
- <para>A saída do <command>pciconf
- -l</command> e as partes relevantes da
- saída do <command>dmesg</command> se o
- problema estiver relacionado a um componente de
- hardware</para>
+ <para>a saÃda de <command>pciconf -l</command> e partes relevantes da saÃda do comando <command>dmesg</command> se o seu problema estiver relacionado a uma peça especÃfica de hardware</para>
</listitem>
+
<listitem>
- <para>O fato de que você leu o
- <filename>src/UPDATING</filename> e que o seu
- problema não está listado ali
- (é certeza que alguém vai
- perguntar)</para>
+ <para>o fato de você ter lido <filename>src/UPDATING</filename> e o seu problema não estar listado lá (alguém pode perguntar)</para>
</listitem>
+
<listitem>
- <para>Se você consegue ou não executar
- outro kernel (Isto é para poder descartar a
- possibilidade de ser um problema de hardware tais
- como falha nos discos rígidos e
- superaquecimento dos processadores, cujos
- sintomas podem se confundir com problemas no
- kernel)</para>
+ <para>independente de você poder executar qualquer outro kernel como um fallback (isso é para descartar problemas relacionados a hardware, como discos com falhas e CPUs superaquecidas, que podem se passar por problemas de kernel)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
- <para>Se for um problema com um port, esteja preparado
- para fornecer as seguintes informações
- (Você não precisa fornecer estas
- informações por padrão, o que
- só tende a encher o banco de dados, mas
- você deve incluir os trechos acreditar que
- são relevantes):</para>
+ <para>Se este for um problema de algum port, esteja preparado para fornecer as seguintes informações. (Você não precisa incluÃ-las por padrão, o que apenas tende a preencher o banco de dados, mas você deve incluir trechos que você considera relevantes):</para>
<itemizedlist>
<listitem>
- <para>Quais ports você tem instalados</para>
+ <para>quais ports você instalou</para>
</listitem>
+
<listitem>
- <para>As variáveis de ambiente que substituem
- os padrões do
- <filename>bsd.port.mk</filename>, como por exemplo
- <varname>PORTSDIR</varname></para>
+ <para>quaisquer variáveis de ambiente que sobreescrevem as variáveis padrões em <filename>bsd.port.mk</filename>, assim como <varname>PORTSDIR</varname></para>
</listitem>
+
<listitem>
- <para>O fato de que você leu o
- <filename>ports/UPDATING</filename> e que o seu
- problema não está listado ali
- (é certeza que alguém vai
- perguntar)</para>
+ <para>o fato de você ter lido <filename>ports/UPDATING</filename> e o seu problema não estar listado lá (é garantido que alguém irá perguntar)</para>
</listitem>
</itemizedlist>
</listitem>
-
</itemizedlist>
-
</listitem>
<listitem>
- <para><emphasis>Evite pedidos vagos de novas
- funcionalidades.</emphasis> Os PRs no formato
- <quote>alguém realmente deveria implementar algo
- que faz isso e aquilo</quote> são menos
- prováveis de obterem uma resposta do
- que os que são mais específicos. Lembre-se,
- o código está disponível para todos,
- de forma que se você deseja uma nova funcionalidade,
- a melhor maneira de ter certeza de que ela
- será incluída é começar a
- trabalhar! Também considere o fato de que
- muitas destas sugestões fariam mais sentido
- como um tópico de discussão na
- <literal>freebsd-questions</literal> do que
- como uma entrada no banco de dados de PRs, como
- discutido acima.</para>
+ <para><emphasis>Evite requisições vagas de novas funcionalidades.</emphasis> Os PRs no formato <quote>alguém realmente deve implementar algo que faz isso e aquilo</quote> têm menor probabilidade de obter resultados do que requisições muito especÃficas. Lembre-se, o código fonte está disponÃvel para todos, então se você quiser uma nova funcionalidade, a melhor maneira de garantir que ela seja incluÃda é começar a trabalhar! Considere também o fato de que muitas coisas como essa seriam um tópico melhor para a discussão sobre <literal>freebsd-questions</literal> do que uma entrada no banco de dados de PR, como discutido acima.</para>
</listitem>
<listitem>
- <para><emphasis>Certifique-se de que ninguém tenha
- submetido um PR semelhante antes.</emphasis> Embora isso
- já tenha sido mencionado anteriormente, faz sentido
- repetir aqui. Esta verificação irá
- lhe tomar apenas 1 ou 2 minutos no uso do <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
- mecanismo de busca</link> do banco de dados de PRs.
- (é claro, todos são culpados de já
- terem esquecido de fazer isso de uma vez ou outra.)</para>
+ <para><emphasis>Certifique-se de que ninguém mais tenha submetido um PR similar.</emphasis> Embora isso já tenha sido mencionado acima, vale a pena repetir aqui. Leva apenas um ou dois minutos para usar o mecanismo de busca baseado na Web em <uri xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">https://bugs.freebsd.org/bugzilla/query.cgi</uri>. (Claro, todo mundo é culpado de esquecer de fazer isso de vez em quando.)</para>
</listitem>
<listitem>
- <para>
- <emphasis>Relate apenas um problema em cada
- relatório.</emphasis> Evite incluir dois ou mais
- problemas em um mesmo relatório caso eles
- não estejam relacionados. Quando
- você submeter um <literal>patch</literal>, evite
- adicionar várias funcionalidades ou corrigir
- vários bugs em um mesmo PR, a menos que eles
- sejam estritamente relacionados — Este tipo de
- PR muitas vezes demanda mais tempo para ser
- resolvido.</para>
+ <para><emphasis> Relate um problema apenas através do Relatório de Problemas.</emphasis> Evite incluir dois ou mais problemas dentro do mesmo relatório, a menos que estejam relacionados. Ao enviar patches, evite adicionar várias funcionalidades ou corrigir multiplos bugs no mesmo PR, a menos que eles estejam intimamente relacionados - esses PRs geralmente levam mais tempo para serem resolvidos.</para>
</listitem>
<listitem>
- <para> <emphasis>Evite solicitações
- polêmicas.</emphasis> Se o seu PR está
- relacionado a um tema que foi polêmico no passado,
- você deve estar preparado para não somente
- disponibilizar um <literal>patch</literal>, como
- também para defender porque o seu
- <literal>patch</literal> é <quote>a coisa certa a
- se fazer</quote>. Como mencionado acima, realizar uma
- busca cuidadosa no histórico das <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">listas
- de discussão</link> é sempre uma boa
- forma de se preparar.</para>
+ <para><emphasis>Evite requisições controversas.</emphasis> Se o seu PR aborda uma área que já foi controversa no passado, você provavelmente deverá estar preparado para não apenas oferecer patches, mas também justificar por que os patches são <quote>A Coisa Certa A Se Fazer </quote>. Como observado acima, uma busca cuidadosa nas listas de discussão usando os arquivos em <uri xlink:href="https://www.FreeBSD.org/search/search.html#mailinglists"> https://www.FreeBSD.org /search/search.html#mailinglists </uri> é sempre uma boa preparação.</para>
</listitem>
<listitem>
- <para><emphasis>Seja educado.</emphasis> Praticamente
- todas as pessoas que potencialmente podem trabalhar no
- seu PR são voluntários. Ninguém
- gosta de receber ordens para fazer algo que eles já
- estão fazendo por alguma outra
- motivação a qual não é a de
- ganho financeiro. Esta é uma boa coisa para ter
- sempre em mente num projeto de código
- aberto.</para>
+ <para><emphasis>Seja educado.</emphasis> Quase todo mundo que potencialmente irá trabalhar em seu PR é um voluntário. Ninguém gosta que digam o que eles tem que fazer quando já estão fazendo por alguma motivação que não seja o ganho monetário. É sempre bom ter isso em mente em projetos de código aberto.</para>
</listitem>
</itemizedlist>
</section>
- <section>
- <title>Antes de você iniciar</title>
+ <section xml:id="pr-writing-before-beginning">
+ <title>Antes de Começar</title>
- <para>Antes de executar o programa &man.send-pr.1;,
- certifique-se que a sua variável de ambiente
- <envar>VISUAL</envar> (ou a <envar>EDITOR</envar> se a
- <envar>VISUAL</envar> não estiver definida)
- está definida com seu editor preferido.</para>
-
- <para>Você também deve certificar-se de que o seu
- sistema de entrega de emails esta funcionando corretamente. O
- &man.send-pr.1; utiliza mensagens de email para enviar e
- rastrear um relatório de problema. Se você
- não pode enviar mensagens de email a partir da
- máquina na qual está executando o
- &man.send-pr.1;, os seus relatórios de problema
- não irão chegar até a base de dados
- GNATS. Para maiores detalhes de como configurar o sistema de
- email no &os;, consulte o capítulo sobre <quote>Correio
- Eletrônico</quote> no <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">Handbook
- do FreeBSD</link>.</para>
-
- <para>Certifique-se de que o seu sistema de email não
- irá alterar a formatação da mensagem ao
- encaminhá-la para o GNATS. Qualquer
- <literal>patch</literal> que você enviar será
- inutilizado, caso o seu sistema de email quebre
- automaticamente as linhas, troque
- tabulações por espaços em branco ou
- altere os caracteres de mudança para uma nova linha,
- etc. Entretanto, para as seções de texto
- nós pedimos que você quebre manualmente as linhas
- próximo dos 70 caracteres, desta forma a versão
- web do PR poderá ser lida melhor.</para>
-
- <para>Considerações similares se aplicam se
- você estiver utilizando o <link xlink:href="&url.base;/send-pr.html">formulário web de
- submissão de PR</link> ao invés de utilizar o
- &man.send-pr.1;. Observe que operações de
- copiar-e-colar possuem seus próprios efeitos colaterais
- na formatação do texto. Em certos casos, pode
- ser necessário usar o &man.uuencode.1; para garantir
- que os patches cheguem sem modificações.</para>
+ <para>Considerações semelhantes se aplicam ao uso do <link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">formulário de envio de PR web-based (com base em web)</link>. Cuidado com as operações de recortar e colar que podem alterar o espaços em branco ou outras formatações de texto.</para>
- <para>Finalmente, se a sua submissão será longa,
- você deve preparar o texto do seu
- relatório offline, desta forma nada será
- perdido no caso de você ter problemas quando for
- submetê-lo. Isto pode ser um problema, em especial,
- se você estiver utilizando o <link xlink:href="&url.base;/send-pr.html">formulário
- web</link>.</para>
+ <para>Finalmente, se o envio for demorado, prepare o trabalho off-line para que nada seja perdido se houver um problema ao enviá-lo.</para>
</section>
- <section>
- <title>Anexando <literal>patches</literal> ou arquivos</title>
+ <section xml:id="pr-writing-attaching-patches">
+ <title>Anexando Patches ou Arquivos</title>
- <para>As instruções abaixo se aplicam ao envio
- de PRs por email:</para>
+ <para>Ao anexar um patch, certifique-se de usar <option>-u</option> com <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> para criar ou unificar o diff e certificar-se de especificar os números de revisão exatos do SVN dos arquivos que você modificou para que os desenvolvedores que lerem seu relatório possam aplicá-los facilmente. Para problemas com o kernel ou com os utilitários de base, um patch para o FreeBSD-CURRENT (a branch HEAD do Subversion) é o preferido, já que todo código novo deve ser aplicado e testado lá primeiro. Após testes apropriados ou substanciais terem sido feitos, o código será mesclado/migrado para a branch FreeBSD-STABLE.</para>
- <para>O programa &man.send-pr.1; tem a capacidade de anexar
- arquivos em um relatório de problemas. Você
- pode anexar quantos arquivos desejar desde que os mesmos
- possuam nomes únicos (i.e. o nome próprio do
- arquivo, sem o caminho de diretório). Basta usar a
- opção <option>-a</option> na linha de comando
- para anexar os arquivos desejados:</para>
+ <para>Se você anexar um patch inline, em vez de um anexo, observe que o problema mais comum, de longe, é a tendência de alguns programas de email renderizar tabs como espaços, o que ira arruinar completamente qualquer coisa destinada a fazer parte de um Makefile.</para>
-<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen>
+ <para>Não envie correções como anexos usando <command>Content-Transfer-Encoding: quoted-printable</command>. Isso irá escapar os caracteres e todo o patch se tornará inútil.</para>
- <para>Não se preocupe com os arquivos binários,
- eles serão encodados automaticamente de forma a
- não perturbar o seu agente de correio.</para>
+ <para>Observe também que, embora a inclusão de pequenos patches em um PR geralmente esteja correto - particularmente quando eles corrigem o problema descrito no PR - patches grandes e especialmente códigos novos que podem exigir uma revisão substancial antes do commit, deveriam ser colocados em um servidor web ou FTP, e a URL deveria ser incluÃda no PR em vez do patch. Patches por e-mail tendem a ficar embaralhados, e quanto maior o patch, mais difÃcil será para as partes interessadas recuperá-lo. Além disso, postar um patch na web permite modificá-lo sem ter que reenviar todo o patch em um followup do PR original. Finalmente, os patches grandes simplesmente aumentam o tamanho do banco de dados, uma vez que os PRs fechados não são realmente excluÃdos, mas sim mantidos e simplesmente marcados como completos.</para>
- <para>Se você anexar um <literal>patch</literal>, tenha
- certeza de utilizar a opção <option>-c</option>
- ou <option>-u</option> no &man.diff.1; para criar um diff
- contextual ou um diff unificado (o formato unificado é
- preferido), e tenha certeza de especificar os números
- de revisão exatos dos arquivos que você
- modificou, desta forma o desenvolvedor que ler seu
- relatório terá condições de
- aplicá-los facilmente. Para problemas com o kernel ou
- com os aplicativos do sistema base, um
- <literal>patch</literal> para o &os.current; (o ramo HEAD do
- CVS) é preferido uma vez que todo novo código
- deve ser aplicado e testado primeiro nele. Depois que forem
- realizados os testes apropriados, o código será
- fundido ou migrado para o ramo &os.stable;.</para>
-
- <para>Se você juntar um <literal>patch</literal>
- no corpo do email, em vez de enviá-lo como um
- arquivo anexo, você estará sujeito a
- ocorrência de um problema bastante comum ocasionado
- pela tendência de alguns clientes de email de converter
- tabs em espaços, o que irá arruinar
- completamente qualquer coisa que você tenha enviado
- com intenção de que fosse parte de um
- Makefile.</para>
-
- <para>Não envie <literal>patches</literal> como anexos
- usando <command>Content-Transfer-Encoding: quoted-printable
- </command>. Isto irá realizar
- <literal>character escaping</literal> e o
- <literal>patch</literal> inteiro estará
- inutilizado.</para>
-
- <para>Observe também que incluir pequenos
- <literal>patches</literal> em um PR é normalmente a
- coisa certa a se fazer — particularmente quando ele
- corrige o problema descrito no PR — grandes
- <literal>patches</literal> e especialmente código novo,
- que normalmente requerem uma revisão substancial antes
- de serem incorporados, devem ser colocados em um servidor web
- ou de FTP, e a url deve ser incluída no PR ao
- invés do <literal>patch</literal> propriamente dito.
- Os <literal>patches</literal> dentro de um email tendem a se
- deformar, especialmente quando o GNATS está envolvido,
- e quanto maior o patch, maior é a dificuldade para
- ambas as partes em consertá-lo. Além de que, ao
- colocar o <literal>patch</literal> na web, você pode
- modificá-lo sem ter que reenviar o arquivo completo
- como um <literal>followup</literal> do PR original.
- Além disso, os grandes <literal>patches</literal>
- simplesmente aumentam o tamanho do banco de dados, uma vez que
- os relatórios de problema fechados não
- são deletados, continuando a existir marcados como
- <literal>closed</literal>.</para>
-
- <para>Você deve observar que a menos que
- especifique explicitamente no seu PR ou diretamente no seu
- patch, qualquer correção que você envie
- será considerada como estando licenciada sob os mesmos
- termos do arquivo original que você modificou.</para>
+ <para>Você também deve observar que, a menos que você especifique explicitamente o contrário em seu PR ou no próprio patch, quaisquer patches enviados por você serão considerados licenciados sob os mesmos termos do arquivo original que você modificou.</para>
</section>
- <section>
- <title>Preenchendo o template</title>
+ <section xml:id="pr-writing-filling-template">
+ <title>Preenchendo o Modelo</title>
- <para>As instruções abaixo se aplicam apenas ao
- envio de PRs por email:</para>
+ <para>Somente no modelo de e-mail, você encontrará os seguintes campos de uma única linha:</para>
- <para>Quando você executar o programa &man.send-pr.1;,
- você será apresentado a um template. O template
- consiste em uma lista de campos, alguns dos quais
- estarão pré-preenchidos, e alguns irão
- possuir comentários explicando o seu propósito
- ou então listando os valores aceitáveis.
- Não se preocupe com os comentários, eles
- serão removidos automaticamente se você
- não modificá-los ou então os remova
- você mesmo.</para>
-
- <para>Na parte superior do template, logo abaixo das linhas
- <literal>SEND-PR:</literal>, está o cabeçalho do
- email. Você normalmente não necessita
- modificá-lo, a menos que você esteja enviando o
- relatório de problema a partir de uma máquina ou
- de uma conta a qual pode enviar, mas não pode receber
- emails, neste caso você deve configurar manualmente os
- campos <literal>From:</literal> e <literal>Reply-To:</literal>
- para o seu endereço de email real. Você
- também pode querer enviar uma cópia do
- relatório para você mesmo (ou para alguma outra
- pessoa) através do uso de uma cópia carbono,
- adicionando um ou mais endereços de email na linha de
- cabeçalho <literal>Cc:</literal>.</para>
-
- <para>Os campos de linha única descritos abaixo,
- estão disponíveis apenas no template do
- email:</para>
-
<itemizedlist>
<listitem>
- <para><emphasis>Submitter-Id:</emphasis> Não altere
- este campo. O valor padrão é
- <literal>current-users</literal> e está correto,
- mesmo se você estiver executando o
- &os.stable;.</para>
+ <para><emphasis>Submeter-Id (ID do remetente):</emphasis> Não altere isso. O valor padrão de <literal>current-users</literal> está correto, mesmo se você estiver usando o FreeBSD-STABLE.</para>
</listitem>
<listitem>
- <para><emphasis>Confidential:</emphasis> Não altere
- este campo. O valor padrão é
- <literal>no</literal>. Não tem sentido
- alterá-lo já que não existem
- relatórios de problema confidenciais no &os;
- — o banco de dados de PR é
- distribuído mundialmente pelo
- <application>CVSup</application>.</para>
+ <para><emphasis>Confidential (Confidencial): </emphasis> Isto é pré-preenchido como <literal>no</literal>. Alterá-lo não faz sentido, já que não existe um relatório confidencial de problemas do FreeBSD - o banco de dados de PR é distribuÃdo para todo mundo.</para>
</listitem>
<listitem>
- <para><emphasis>Severity:</emphasis> Escolha uma
- opção entre <literal>non-critical</literal>,
- <literal>serious</literal> ou <literal>critical</literal>.
- Não faça escândalo; abstenha-se de
- rotular seu problema como <literal>critical</literal> a
- menos que ele realmente seja (por ex. questões de
- corrupção de dados, grave retrocesso de
- funcionalidade no -CURRENT em relação a
- versão anterior, etc)ou de
- <literal>serious</literal> a menos que seja algo que vai
- afetar muitos usuários (Kernel panic ou travamentos
- do sistema; Problemas com algum driver de dispositivo em
- particular ou com utilitários de sistema). Os
- desenvolvedores do &os; não irão
- necessariamente trabalhar no seu problema mais
- rápido se você inflar sua importância
- uma vez que existem muitas outras pessoas que fizeram
- exatamente isso — na verdade, alguns desenvolvedores
- prestam pouca atenção a este campo por causa
- disso.</para>
+ <para><emphasis>Severety (Gravidade):</emphasis> Um dos <literal>non-critical (não crÃticos)</literal>, <literal>serious (sério)</literal> ou <literal>critical (crÃtico)</literal>. Não exagere; abstenha-se de rotular seu problema como <literal>critical</literal> a menos que realmente seja (por exemplo, problemas de corrupção de dados, séria regressão da funcionalidade anterior no -CURRENT) ou <literal>serious</literal> a menos que seja algo que afetará muitos usuários (kernel entra em pane ou congela; problemas com determinados drivers de dispositivo ou utilitários do sistema). Os desenvolvedores do FreeBSD não irão necessariamente trabalhar no seu problema mais rapido se você inflar sua importância, já que há tantas outras pessoas que fizeram exatamente isso - na verdade, alguns desenvolvedores dão pouca atenção a esse campo por causa disso.</para>
+ </listitem>
- <note>
- <para>Problemas de segurança
- <emphasis>não</emphasis> devem ser submetidos
- para o GNATS, pois todas as informações
- no GNATS são de conhecimento público.
- Por favor, envie estes problemas seguindo as nossas
- <link xlink:href="http://security.freebsd.org/#how">diretrizes
- sobre relatórios de segurança</link>.
- </para>
-
-
- </note>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list