Date: Wed, 5 Sep 2012 05:38:11 +0000 (UTC) From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39503 - in head/pt_BR.ISO8859-1/articles: . problem-reports Message-ID: <201209050538.q855cB61081757@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gabor Date: Wed Sep 5 05:38:11 2012 New Revision: 39503 URL: http://svn.freebsd.org/changeset/doc/39503 Log: - Add new Brazilian Portuguese translation of the problem-reports article PR: docs/170672 Submitted by: Edson Brandi <ebrandi@fugspbr.org> Obtained from: The FreeBSD Brazilian Portuguese Documentation Project (http://doc.fug.com.br) Added: head/pt_BR.ISO8859-1/articles/problem-reports/ head/pt_BR.ISO8859-1/articles/problem-reports/Makefile (contents, props changed) head/pt_BR.ISO8859-1/articles/problem-reports/article.sgml (contents, props changed) Modified: head/pt_BR.ISO8859-1/articles/Makefile Modified: head/pt_BR.ISO8859-1/articles/Makefile ============================================================================== --- head/pt_BR.ISO8859-1/articles/Makefile Wed Sep 5 05:32:52 2012 (r39502) +++ head/pt_BR.ISO8859-1/articles/Makefile Wed Sep 5 05:38:11 2012 (r39503) @@ -11,6 +11,7 @@ SUBDIR = SUBDIR+= contributing SUBDIR+= linux-users +SUBDIR+= problem-reports DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/pt_BR.ISO8859-1/articles/problem-reports/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/pt_BR.ISO8859-1/articles/problem-reports/Makefile Wed Sep 5 05:38:11 2012 (r39503) @@ -0,0 +1,24 @@ +# +# The FreeBSD Documentation Project +# The FreeBSD Brazilian Portuguese Documentation Project +# +# $FreeBSD$ +# +# Original revision: r38826 +# +# Article: Writing FreeBSD Problem Reports + +DOC?= article + +FORMATS?= html html-split +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?=gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" Added: head/pt_BR.ISO8859-1/articles/problem-reports/article.sgml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/pt_BR.ISO8859-1/articles/problem-reports/article.sgml Wed Sep 5 05:38:11 2012 (r39503) @@ -0,0 +1,1644 @@ +<!-- + The FreeBSD Documentation Project + The FreeBSD Brazilian Portuguese Documentation Project + + Original revision: r38826 +--> + +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//PTBR"> +%articles.ent; +]> + +<article> + <articleinfo> + <title>Escrevendo Relatórios de Problema no &os;</title> + + <pubdate>$FreeBSD$</pubdate> + + <legalnotice 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; + </legalnotice> + + <abstract> + <para>Este artigo descreve qual a melhor forma de formular e + de submeter um relatório de problema para Projeto + &os;.</para> + </abstract> + + <authorgroup> + <author> + <firstname>Dag-Erling</firstname> + <surname>Smørgrav</surname> + <contrib>Contribuido por</contrib> + </author> + + <author> + <firstname>Mark</firstname> + <surname>Linimon</surname> + </author> + </authorgroup> + </articleinfo> + + <indexterm><primary>relatório de problema</primary> + </indexterm> + + <section id="pr-intro"> + <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> + </section> + + <section id="pr-when"> + <title>Quando enviar um relatório de problema</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> + + <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> + </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 os ports sem manutenção + (aqueles nos quais a variável + <makevar>MAINTAINER</makevar> contém + <literal>ports@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 <ulink + url="&url.books.porters-handbook;/port-upgrading.html">Porter's Handbook</ulink>. + (Talvez você também queira ler o artigo <ulink + url="&url.articles.contributing-ports;/article.html"> + Contribuindo para a Coleção de Ports + do &os;</ulink>.)</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>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> + + <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> + </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> + </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> + </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 + <ulink url="&url.books.faq;/introduction.html#LATEST-VERSION"> + Versões do &os;</ulink>, 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 + <ulink url="&url.base;/security/">lista de versões + suportadas</ulink>.</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> + </section> + + <section id="pr-prep"> + <title>Preparação</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> + + <itemizedlist> + <listitem> + <para>A lista de <ulink + url="&url.books.faq;/index.html">Perguntas e Respostas mais + Frequentes</ulink> sobre o &os; (FAQ). A FAQ tem por + objetivo fornecer respostas para uma grande variedade de + perguntas, tais como as que dizem respeito a <ulink + url="&url.books.faq;/hardware.html">compatibilidade de + hardware</ulink>, <ulink + url="&url.books.faq;/applications.html">aplicações + do usuário</ulink>, <ulink + url="&url.books.faq;/kernelconfig.html">Configuração + do kernel</ulink>, etc.</para> + </listitem> + + <listitem> + <para>As <ulink + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL"> + listas de discussão</ulink> — se você + não está inscrito, utilize a <ulink + url="http://www.FreeBSD.org/search/search.html#mailinglists">; + busca do histórico</ulink> 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> + </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> + </listitem> + + <listitem> + <para>Na sequência, verifique o <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">; + banco de dados com os relatórios de problema do + &os;</ulink> (GNATS). A menos que o seu problema seja + recente ou muito obscuro, existe uma boa chance dele + já ter sido reportado.<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 <ulink + url="http://svnweb.freebsd.org/base/head/UPDATING">; + Repositório Subversion</ulink>. (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 <ulink + url="http://svnweb.freebsd.org/ports/head/UPDATING"></ulink>; + e <ulink + url="http://svnweb.freebsd.org/ports/head/CHANGES"></ulink>; + respectivamente.</para> + </listitem> + </itemizedlist> + </section> + + <section id="pr-writing"> + <title>Escrevendo o Relatório de 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> + + <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> + </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> + </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> + </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> + </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> + + <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> + </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> + </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> + </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> + <itemizedlist> + <listitem> + <para>A configuração do seu kernel + (incluindo quais dispositivos de hardware + você tem instalados)</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> + </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> + </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> + </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> + </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> + </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> + + <itemizedlist> + <listitem> + <para>Quais ports você tem instalados</para> + </listitem> + <listitem> + <para>As variáveis de ambiente que substituem + os padrões do + <filename>bsd.port.mk</filename>, como por exemplo + <makevar>PORTSDIR</makevar></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> + </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> + </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 <ulink + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">; + mecanismo de busca</ulink> do banco de dados de PRs. + (é claro, todos são culpados de já + terem esquecido de fazer isso de uma vez ou outra.)</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> + </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 <ulink + url="http://www.FreeBSD.org/search/search.html#mailinglists">listas + de discussão</ulink> é sempre uma boa + forma de se preparar.</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> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Antes de você iniciar</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 <ulink + url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">Handbook + do FreeBSD</ulink>.</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 <ulink + url="&url.base;/send-pr.html">formulário web de + submissão de PR</ulink> 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>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 <ulink + url="&url.base;/send-pr.html">formulário + web</ulink>.</para> + </section> + + <section> + <title>Anexando <literal>patches</literal> ou arquivos</title> + + <para>As instruções abaixo se aplicam ao envio + de PRs por email:</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> + +<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen> + + <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>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> + </section> + + <section> + <title>Preenchendo o template</title> + + <para>As instruções abaixo se aplicam apenas ao + envio de PRs por email:</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>No template do email você irá encontrar os + dois seguintes campos de linha única:</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> + </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> + </listitem> + + </itemizedlist> + + <para>A próxima seção descreve os campos + que são comuns entre a interface por email e a + <ulink url="&url.base;/send-pr.html">interface web</ulink>:</para> + + <itemizedlist> + + <listitem> + <para><emphasis>Originator:</emphasis> + Por favor informe seu nome completo, seguido opcionalmente + pelo seu endereço de email entre colchetes. + Na interface de email, este campo é normalmente + pré-preenchido com o campo + <literal>gecos</literal> do usuário com o qual + você está atualmente logado.</para> + + <note> + <para>O endereço de email que você utilizar + irá se tornar uma informação + pública e pode vir a se tornar disponível + para spammers. Você deverá ter um sistema + antispam funcional ou então deverá + utilizar uma conta temporária de email. + Contudo, por favor, lembre-se que se você + não utilizar uma conta de email válida, + nós não seremos capazes de entrar em + contato com você para fazer perguntas sobre o + seu PR.</para> + </note> + + </listitem> + + <listitem> + <para><emphasis>Organization:</emphasis> Campo livre para + o que você quiser colocar. Este campo não + é utilizado para nada significativo.</para> + </listitem> + + <listitem> + <para><emphasis>Synopsis:</emphasis> Preencha este campo com + uma descrição curta e precisa sobre o seu + problema. A <literal>synopsis</literal> é + utilizada como o assunto do email do relatório de + problema, e também é utilizada na listagem + de relatório de problemas e resumos; + relatórios de problema com + <literal>synopses</literal> obscuras tendem a serem + ignorados.</para> + + <para>Como mencionado acima, se o seu relatório de + problema inclui um <literal>patch</literal>, por favor, + inicie sua <literal>synopsis</literal> com + <literal>[patch]</literal> (incluindo os colchetes); se + você for um <literal>maintainer</literal> considere + adicionar <literal>[maintainer update]</literal> + (incluindo os colchetes) ao início da sua + <literal>synopsis</literal> e defina a + <quote>classe</quote> do seu PR para + <literal>maintainer-update</literal>.</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> + + <note> + <para>Os grandes problemas de segurança *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201209050538.q855cB61081757>