svn commit: r39503 - in head/pt_BR.ISO8859-1/articles: .
problem-reports
Gabor Kovesdan
gabor at FreeBSD.org
Wed Sep 5 05:38:12 UTC 2012
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 at 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 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 <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 ***
More information about the svn-doc-all
mailing list