1650 lines
59 KiB
XML
1650 lines
59 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
|
|
"../../../share/sgml/freebsd42.dtd" [
|
|
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//PT" "../../share/sgml/entities.ent">
|
|
%entities;
|
|
]>
|
|
|
|
<!--
|
|
The FreeBSD Documentation Project
|
|
The FreeBSD Brazilian Portuguese Documentation Project
|
|
|
|
Original revision: r39487
|
|
-->
|
|
|
|
<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>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>
|
|
</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>
|
|
|
|
<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>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
|
|
<ulink url="http://security.freebsd.org/#how">diretrizes
|
|
sobre relatórios de segurança</ulink>.
|
|
</para>
|
|
|
|
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Priority:</emphasis> Escolha uma
|
|
opção entre <literal>low</literal>,
|
|
<literal>medium</literal> ou <literal>high</literal>.
|
|
<literal>high</literal> deve ser reservada para os
|
|
problemas que afetam praticamente todos os
|
|
usuários do &os; e <literal>medium</literal> para
|
|
os problemas que vão afetar muitos
|
|
usuários.</para>
|
|
|
|
<note>
|
|
<para>Este campo tornou-se tão amplamente abusado que
|
|
perdeu quase que completamente seu objetivo.</para>
|
|
</note>
|
|
</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>Category:</emphasis> Escolha uma categoria
|
|
adequada.</para>
|
|
|
|
<para>
|
|
A primeira coisa que você precisa fazer é
|
|
decidir em qual parte do sistema o seu problema
|
|
está. Lembre-se, o &os; é um sistema
|
|
operacional completo, o qual instala um kernel, as
|
|
bibliotecas padrão, muitos
|
|
<literal>drivers</literal> de dispositivos e um grande
|
|
número de utilitários (este conjunto
|
|
recebe o nome de <quote>sistema base</quote>). No
|
|
entanto, existem milhares de aplicativos adicionais na
|
|
Coleção de Ports. Você primeiro
|
|
precisa decidir se o problema está no sistema base
|
|
ou se está em algo que foi instalado através
|
|
da Coleção de Ports.</para>
|
|
|
|
<para>Aqui está uma descrição das
|
|
principais categorias:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Se o problema é com o Kernel, com as
|
|
bibliotecas (tal como a biblioteca C padrão,
|
|
libc), ou com um <literal>driver</literal> de
|
|
dispositivo do sistema base, em geral você vai
|
|
usar a categoria kern. (Existem algumas
|
|
exceções; veja abaixo). Em geral, estas
|
|
são coisas que estão descritas nas
|
|
seções 2, 3 ou 4 das páginas de
|
|
manual.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Se o problema é com um programa binário,
|
|
tal como o &man.sh.1; ou o &man.mount.8;, primeiro
|
|
você precisa determinar se estes programas
|
|
pertencem ao sistema base ou se foram adicionados
|
|
através da coleção de ports. Se
|
|
você estiver na dúvida, você pode
|
|
executar um <command>whereis <replaceable>
|
|
nomedoprograma</replaceable></command>, no
|
|
&os; por convenção todos os aplicativos
|
|
da coleção de ports são
|
|
instalados sob <filename
|
|
class="directory">/usr/local</filename>, embora isso
|
|
possa ser alterado por um administrador de sistemas.
|
|
Para estes, você irá utilizar a categoria
|
|
<literal>ports</literal> (sim, mesmo que a categoria
|
|
do port seja <literal>www</literal>; veja abaixo). Se
|
|
a localização do aplicativo for
|
|
<filename class="directory">/bin</filename>, <filename
|
|
class="directory">/usr/bin</filename>, <filename
|
|
class="directory">/sbin</filename>, ou <filename
|
|
class="directory">/usr/sbin</filename>, ele
|
|
faz parte do sistema base, e você
|
|
deverá utilizar a categoria
|
|
<literal>bin</literal>. (Alguns programas, como o
|
|
&man.gcc.1;, na prática utilizam a categoria
|
|
<literal>gnu</literal>, mas não se preocupe
|
|
com isso por agora.) Todos estes aplicativos
|
|
estão descritos nas seções 1 ou 8
|
|
das páginas de manual.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se você acredita que o erro está no
|
|
script de inicialização
|
|
<literal>(rc)</literal>, ou em algum outro tipo de
|
|
arquivo de configuração não
|
|
executável, então a categoria indicada
|
|
será a <literal>conf</literal>
|
|
(configuração). Estas são coisas
|
|
descritas na seção 5 das páginas
|
|
de manual.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se você encontrou um problema na
|
|
documentação (artigos, livros,
|
|
páginas de manual, etc.), a escolha
|
|
correta para a categoria é a
|
|
opção <literal>docs</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se você está tendo problemas com as
|
|
<ulink url="http://www.FreeBSD.org">páginas web
|
|
do &os;</ulink>, a escolha apropriada é
|
|
<literal>www</literal>.</para>
|
|
|
|
<note>
|
|
<para>Independentemente se você está
|
|
tendo algum problema com um port chamado
|
|
<literal>www/<replaceable>nomedoport</replaceable></literal>,
|
|
a categoria correta para o mesmo será
|
|
<literal>ports</literal>.</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Existem algumas categorias mais especializadas.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Se o problema pode ser classificado na
|
|
categoria <literal>kern</literal>, e está
|
|
relacionado ao subsistema USB, a categoria correta
|
|
será <literal>usb</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se o problema pode ser classificado na categoria
|
|
<literal>kern</literal>, e está relacionado com
|
|
as bibliotecas de threads, a categoria correta
|
|
será <literal>threads</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se o problema está localizado no sistema
|
|
base, mas está relacionado a nossa
|
|
aderência a padrões tais como o
|
|
&posix;, a categoria correta será
|
|
<literal>standards</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Se o problema está relacionado a erros internos
|
|
de uma &java.virtual.machine; (&jvm;), mesmo que o
|
|
&java; tenha sido instalado a partir da
|
|
coleção de ports, você deve
|
|
selecionar a categoria <literal>java</literal>.
|
|
Problemas genéricos com o port do &java; devem
|
|
continuar sendo enviados na categoria
|
|
<literal>ports</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Isto deixa tudo mais.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Se você está convencido de que o
|
|
problema irá ocorrer apenas na arquitetura do
|
|
processador que você está utilizando,
|
|
selecione uma categoria específica para a sua
|
|
arquitetura: geralmente <literal>i386</literal> para
|
|
máquinas compatíveis com a arquitetura
|
|
Intel de 32 bits, <literal>amd64</literal> para
|
|
máquinas AMD executando em modo 64 bits (o que
|
|
também inclui máquinas
|
|
compatíveis com a arquitetura Intel executando
|
|
em modo EMT64); e menos comumente
|
|
<literal>ia64</literal>, <literal>powerpc</literal>, e
|
|
<literal>sparc64</literal>.</para>
|
|
|
|
<note>
|
|
<para>Estas categorias são muitas vezes
|
|
utilizadas de forma indevida para problemas do
|
|
tipo <quote>Eu não sei</quote>. Em vez de
|
|
tentar adivinhar, por favor, apenas utilize a
|
|
categoria <literal>misc</literal>.</para>
|
|
</note>
|
|
|
|
<example>
|
|
<title>Uso correto da categoria específica de
|
|
arquitetura.</title>
|
|
|
|
<para>Você tem um computador comum (PC), e
|
|
acredita que encontrou um problema específico
|
|
com um chipset em particular ou com uma placa
|
|
mãe específica: A categoria correta
|
|
é <literal>i386</literal>.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Uso incorreto da categoria específica de
|
|
arquitetura.</title>
|
|
|
|
<para>Você está tendo problemas com uma
|
|
placa de expansão instalada em um barramento
|
|
bastante comum, ou um problema com um tipo
|
|
específico de disco rígido: neste
|
|
caso, é provável que o problema
|
|
ocorra em mais de uma arquitetura, e a categoria
|
|
correta seria <literal>kern</literal>.</para>
|
|
</example>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Se você realmente não sabe onde
|
|
está o problema (ou o mesmo não parece
|
|
se encaixar nas categorias acima), utilize a categoria
|
|
<literal>misc</literal>. Mas antes de fazer isto,
|
|
pode ser uma boa idéia primeiro pedir ajuda na
|
|
&a.questions;. Você poderá ser orientado
|
|
à utilizar uma das outras categorias para
|
|
obter um melhor resultado.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Aqui está a lista atual de categorias
|
|
(retirada do url <ulink
|
|
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories"></ulink>):</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>advocacy:</literal> problemas
|
|
relacionados a imagem pública do &os;.
|
|
Obsoleta.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>alpha:</literal> problemas
|
|
específicos da plataforma Alpha.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>amd64:</literal> problemas
|
|
específicos da plataforma AMD64.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>arm:</literal> problemas
|
|
específicos da plataforma ARM.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>bin:</literal> problemas com os programas
|
|
de nível de usuário na base do
|
|
sistema.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>conf:</literal> problemas com os arquivos
|
|
de configuração, valores padrões,
|
|
etc.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>docs:</literal> problemas com as
|
|
páginas de manuais ou com a
|
|
documentação online.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>gnu:</literal> problemas com softwares
|
|
GNU, tais como &man.gcc.1; ou &man.grep.1;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>i386:</literal> problemas
|
|
específicos da plataforma &i386;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>ia64:</literal> problemas
|
|
específicos da plataforma ia64.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>java:</literal> problemas relacionados
|
|
com a Maquina Virtual &java;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>kern:</literal> problemas com o kernel,
|
|
drivers de dispositivo (não específicos
|
|
à uma plataforma), ou bibliotecas do sistema
|
|
base.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>misc:</literal> Tudo aquilo que
|
|
não se encaixa numa das outras
|
|
categorias. (observe que não existe nada que
|
|
pertença verdadeiramente a esta categoria,
|
|
exceto os problemas com a infra estrutura de build e
|
|
de release. As falhas temporárias de
|
|
compilação do <literal>HEAD</literal>
|
|
não pertencem a esta categoria. Também
|
|
observe que é fácil para as coisas se
|
|
perderem nesta categoria).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>ports:</literal> problemas relacionados
|
|
com a Coleção de Ports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>powerpc:</literal> problemas
|
|
específicos da plataforma &powerpc;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>sparc64:</literal> problemas
|
|
específicos da plataforma &sparc64;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>standards:</literal> problemas
|
|
relacionados a conformidade com os
|
|
padrões.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>threads:</literal> problemas relacionados
|
|
a implementação de threads no &os;
|
|
(especialmente no &os.current;).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>usb:</literal> problemas relacionados a
|
|
implementação do USB no &os;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>www:</literal> mudanças e
|
|
melhorias no web site do &os;.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Class:</emphasis> Escolha uma das seguintes
|
|
opções:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>sw-bug:</literal> bugs de
|
|
software.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>doc-bug:</literal> erros na
|
|
documentação.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>change-request:</literal>
|
|
solicitação de novas funcionalidades
|
|
ou de alterações em funcionalidades
|
|
existentes.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>update:</literal>
|
|
atualizações para o ports ou para
|
|
outros softwares de terceiros.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>maintainer-update:</literal>
|
|
atualizações de ports pelos quais
|
|
você é o responsável.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Release:</emphasis> É a versão
|
|
do &os; que você está utilizando. Este campo
|
|
é preenchido automaticamente pelo &man.send-pr.1; e
|
|
só necessita ser alterado se você estiver
|
|
enviando o relatório de problema de um sistema
|
|
diferente do que apresenta o problema.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Finalmente, há uma série de campos de
|
|
várias linhas:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>Environment:</emphasis> Este campo
|
|
deve descrever, da forma mais precisa
|
|
possível, o ambiente no qual o problema foi
|
|
observado. Isto inclui a versão do sistema
|
|
operacional, a versão do programa ou do arquivo
|
|
específico que contém o problema, e qualquer
|
|
outro item relevante tal como a configuração
|
|
do sistema, outros softwares instalados que tenham
|
|
influência no problema, etc. — ou seja,
|
|
simplesmente tudo o que um desenvolvedor precisar saber
|
|
para reconstruir o ambiente no qual o problema
|
|
ocorreu.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Description:</emphasis> Uma
|
|
descrição precisa e completa do problema
|
|
que você esta experimentando. Tente evitar
|
|
especular sobre as causas do problema a menos que
|
|
você tenha certeza de que está no caminho
|
|
certo, do contrário você pode induzir o
|
|
desenvolvedor a fazer suposições incorretas
|
|
sobre o problema.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>How-To-Repeat:</emphasis> Um resumo com as
|
|
ações que você precisa executar para
|
|
reproduzir o problema.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Fix:</emphasis> Preferencialmente um
|
|
<literal>patch</literal>, ou no
|
|
mínimo um <literal>workaround</literal> (o que
|
|
não só ajuda as outras pessoas que
|
|
estão com o mesmo problema, como também
|
|
auxilia o desenvolvedor a entender melhor a causa do
|
|
problema), mas se você não tem nenhuma
|
|
idéia consistente, é melhor deixar este
|
|
campo em branco do que especular.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Enviando o relatório de problemas</title>
|
|
|
|
<para>Se você está utilizando o
|
|
&man.send-pr.1;:</para>
|
|
|
|
<para>Uma vez que você tenha terminado de preencher o
|
|
template, salve-o, e saia do editor de texto, ao fazer isto o
|
|
&man.send-pr.1; irá lhe perguntar se você deseja
|
|
<prompt>s)end, e)dit or a)bort?</prompt>. Para ir em frente e
|
|
enviar o relatório de problema pressione
|
|
<userinput>s</userinput>, caso você queira voltar ao
|
|
editor para realizar alguma alteração pressione
|
|
<userinput>e</userinput>, ou então pressione
|
|
<userinput>a</userinput> para cancelar o envio. Se você
|
|
optar por abortar, o seu relatório de problema
|
|
irá permanecer no seu disco rígido (o
|
|
&man.send-pr.1; irá lhe informar o nome do arquivo
|
|
antes de finalizar), assim você poderá
|
|
editá-lo quando for mais conveniente, ou poderá
|
|
transferi-lo para um sistema com uma melhor
|
|
conectividade, no qual poderá enviá-lo usando a
|
|
opção <option>-f</option> com o
|
|
&man.send-pr.1;:</para>
|
|
|
|
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
|
|
|
|
<para>Este comando irá ler o arquivo especificado,
|
|
validar o seu conteúdo, remover os comentários
|
|
e enviar o seu PR.</para>
|
|
|
|
<para>Se você está utilizando o <ulink
|
|
url="&url.base;/send-pr.html">formulário
|
|
web</ulink>:</para>
|
|
|
|
<para>Antes de pressionar o botão
|
|
<literal>submit</literal> para enviar o seu relatório,
|
|
você terá que preencher um campo com o texto
|
|
exibido na imagem de captcha exibida no final do
|
|
formulário. Infelizmente esta medida teve de ser
|
|
adotada devido ao mau uso do mesmo por sistemas automatizados
|
|
e por alguns indivíduos mal intencionados. É um
|
|
mal necessário do qual ninguém gosta.
|
|
Por favor, não peça para
|
|
removê-lo.</para>
|
|
|
|
<para>
|
|
Recomendamos <emphasis>fortemente</emphasis> que você
|
|
salve o seu trabalho em algum outro lugar antes de
|
|
pressionar o botão <literal>submit</literal>. Um
|
|
problema comum e que ocorre com muitos usuários
|
|
é a visualização de uma imagem de
|
|
captcha velha exibida a partir do cache do navegador. Se
|
|
isso acontecer com você o seu envio será
|
|
rejeitado e você poderá perder o seu
|
|
trabalho.</para>
|
|
|
|
<para>Se você, por qualquer motivo, não conseguir
|
|
visualizar as imagens, e também estiver impossibilitado
|
|
de utilizar o &man.send-pr.1;, por favor, aceite nossas
|
|
desculpas por está inconveniência e envie seu
|
|
relatório de problema por e-mail para a equipe de
|
|
bugbusters do &os;, no endereço
|
|
<email>freebsd-bugbusters@FreeBSD.org</email>.</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="pr-followup">
|
|
<title>Acompanhamento</title>
|
|
|
|
<para>
|
|
Depois que seu relatório de problema tiver sido entregue,
|
|
você receberá uma confirmação por
|
|
e-mail com o número de rastreamento que foi
|
|
atribuído ao mesmo e uma URL a
|
|
qual você poderá utilizar para consultar o status
|
|
do seu PR. Com um pouco de sorte, alguém irá se
|
|
interessar pelo seu problema e tentará resolvê-lo,
|
|
ou, conforme o caso explicar porque não se trata de um
|
|
problema. Você será notificado automaticamente de
|
|
qualquer mudança de status, e irá
|
|
receber uma cópia de qualquer comentário ou
|
|
correção que alguém venha a anexar à
|
|
trilha de auditoria do seu relatório de problema.</para>
|
|
|
|
<para>Se alguém lhe requisitar alguma
|
|
informação adicional, ou se você
|
|
lembrar de algo ou descobrir algo que você não
|
|
tenha mencionado no seu relatório inicial, por favor
|
|
utilize um dos dois métodos abaixo para enviar uma
|
|
atualização:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A forma mais fácil é utilizar o link e
|
|
<literal>followup</literal> existente na página web
|
|
individual de cada PR, a qual pode ser encontrada a partir
|
|
da <ulink
|
|
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
|
página de busca de relatórios</ulink>. Ao
|
|
clicar no link será aberta uma janela do seu
|
|
cliente de e-mail com os campos <literal>To:</literal> e
|
|
<literal>Subject:</literal> já corretamente
|
|
preenchidos (se o seu navegador estiver configurado
|
|
corretamente para fazer isto).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Alternativamente, você pode apenas enviá-lo
|
|
para &a.bugfollowup;, certificando-se de que o número
|
|
de rastreamento está incluso no
|
|
<literal>Subject:</literal> de forma que o sistema de
|
|
acompanhamento de bugs tenha como saber em qual
|
|
relatório de problema ele deve anexar o material
|
|
recebido.</para>
|
|
|
|
<note>
|
|
<para>Se você <emphasis>não</emphasis> incluir
|
|
o número de rastreamento, o GNATS irá se
|
|
confundir e criará um relatório de problema
|
|
completamente novo, o qual será atribuído ao
|
|
administrador do GNATS, e então o seu
|
|
<literal>followup</literal> irá ficar perdido
|
|
até que alguém tenha tempo de arrumar a
|
|
bagunça, o que pode levar dias e até mesmo
|
|
semanas para ocorrer.</para>
|
|
|
|
<para>Forma errada:</para>
|
|
|
|
<programlisting>Subject: Sobre o PR que eu enviei</programlisting>
|
|
|
|
<para>Forma correta:</para>
|
|
|
|
<programlisting>Subject: Re: ports/12345: problemas de compilação do foo/bar</programlisting>
|
|
</note>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<para>Se o relatório de problema permanecer aberto depois
|
|
que o problema já tiver sido resolvido, basta enviar um
|
|
follow-up (da forma descrita acima) informando que o PR pode
|
|
ser fechado, e se possível, explicando como e quando o
|
|
problema foi corrigido.</para>
|
|
</section>
|
|
|
|
<section id="pr-problems">
|
|
<title>Se você está tendo problemas</title>
|
|
|
|
<para>A maioria dos PRs que chegam ao sistema é processada
|
|
rapidamente; entretanto em alguns momentos o GNATS fica lento e
|
|
você pode não receber o seu email de
|
|
confirmação de imediato, levando 10 minutos ou
|
|
mesmo um pouco mais para recebê-lo. Por favor, tente ser
|
|
paciente.</para>
|
|
|
|
<para>Além disso, uma vez que o GNATS recebe tudo por
|
|
email, é absolutamente vital que o &os; processe todas as
|
|
mensagens que chegam utilizando filtros antispam. Se você
|
|
não receber o email de confirmação em
|
|
até duas horas, você pode ter sido barrado por este
|
|
sistema; Neste caso, por favor, entre em contato com o
|
|
adminisrador do GNATS no endereço
|
|
<email>bugmeister@FreeBSD.org</email> e peça
|
|
ajuda.</para>
|
|
|
|
<note>
|
|
<para>
|
|
Dentre as medidas antispam que utilizamos existe uma a qual
|
|
verifica a aderência da sua mensagem em
|
|
relação a uma série de abusos comums em
|
|
emails baseados em HTML (embora o sistema não
|
|
necessariamente invalide uma mensagem devido a mera
|
|
inclusão de código HTML no PR).
|
|
Recomendamos fortemente que você evite utilizar
|
|
emails no formato HTML quando estiver enviando um PR:
|
|
Não apenas é provável que a sua
|
|
mensagem seja bloqueada pelos filtros, como ela
|
|
também irá prejudicar o banco
|
|
de dados. O bom e velho email em texto puro é
|
|
fortemente preferido.</para>
|
|
</note>
|
|
|
|
<para>Em raras ocasiões você irá se deparar
|
|
com um bug do GNATS pelo qual um PR será aceito,
|
|
receberá um número de rastreamento, mas
|
|
não irá aparecer na lista de PRs em nenhuma
|
|
consulta realizada no web site.
|
|
O que pode ter ocorrido é que o índice do banco de
|
|
dados ficou fora de sincronia com o próprio banco de
|
|
dados. Uma forma de testar se é isto que esta
|
|
acontecendo com você é acessar um PR individual
|
|
qualquer listado a partir do <ulink
|
|
url="http://www.FreeBSD.org/cgi/query-pr.cgi">formulário
|
|
de busca</ulink>, e substituir o numero do PR na URL pelo seu e
|
|
verificar se ele carrega normalmente. Se ele carregar, por
|
|
favor, notifique os administradores do GNATS no endereço
|
|
<email>bugmeister@FreeBSD.org</email>. Observe que existe uma
|
|
tarefa agendada no <literal>cron</literal> que reconstrói
|
|
periodicamente o banco de dados, de forma que a menos que
|
|
você esteja com pressa, nenhuma ação
|
|
será necessária.</para>
|
|
</section>
|
|
|
|
<section id="pr-further">
|
|
<title>Leituras complementares</title>
|
|
|
|
<para>Esta é uma lista com material de referência
|
|
recomendado sobre boas práticas para se escrever e
|
|
processar um relatório de problema. Esta lista
|
|
não tem por objetivo ser uma lista completa.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><ulink
|
|
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
|
|
Como reportar bugs de forma efetiva</ulink>— Um
|
|
excelente ensaio por Simon G. Tatham sobre a
|
|
elaboração de relatórios de problemas
|
|
eficientes (não é especifico sobre o
|
|
&os;).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><ulink
|
|
url="&url.articles.pr-guidelines;/article.html">Guia de como
|
|
lidar com relatórios de problemas</ulink> —
|
|
Uma percepção valiosa sobre como os
|
|
desenvolvedores do FreeBSD devem lidar com os
|
|
relatórios de problemas.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</article>
|