              Escrevendo Relatorios de Problema no FreeBSD

  Dag-Erling Smo/rgrav

  Mark Linimon

   $FreeBSD:
   release/8.4.0/pt_BR.ISO8859-1/articles/problem-reports/article.xml
   39632 2012-10-01 11:56:00Z gabor $

   $FreeBSD:
   release/8.4.0/pt_BR.ISO8859-1/articles/problem-reports/article.xml
   39632 2012-10-01 11:56:00Z gabor $

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   CVSup is a registered trademark of John D. Polstra.

   IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390, and
   ThinkPad are trademarks of International Business Machines
   Corporation in the United States, other countries, or both.

   Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium, and
   Xeon are trademarks or registered trademarks of Intel Corporation
   or its subsidiaries in the United States and other countries.

   SPARC, SPARC64, SPARCengine, and UltraSPARC are trademarks of
   SPARC International, Inc in the United States and other countries.
   SPARC International, Inc owns all of the SPARC trademarks and
   under licensing agreements allows the proper use of these
   trademarks by its members.

   Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer
   Pages, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice,
   Sun Blade, Sun Enterprise, Sun Fire, SunOS, Ultra and VirtualBox
   are trademarks or registered trademarks of Sun Microsystems, Inc.
   in the United States and other countries.

   Many of the designations used by manufacturers and sellers to
   distinguish their products are claimed as trademarks. Where those
   designations appear in this document, and the FreeBSD Project was
   aware of the trademark claim, the designations have been followed
   by the "(TM)" or the "(R)" symbol.

   Este artigo descreve qual a melhor forma de formular e de submeter
   um relatorio de problema para Projeto FreeBSD.

     --------------------------------------------------------------

     --------------------------------------------------------------

1. Introduc,ao

   Uma das experiencias mais frustrantes que alguem pode ter como um
   usuario de um software e submeter um relatorio sobre um problema
   que esta enfrentando apenas para ve-lo ser sumariamente fechado
   com uma informac,ao curta e pouco util do tipo "isto nao e um bug"
   ou ainda "este relatorio de problema nao procede". Da mesma forma,
   uma das experiencias mais frustrantes para um desenvolvedor de
   software e ser inundado com relatorios de problemas que na verdade
   nao sao realmente relatorios de problemas, mas sim solicitac,oes
   de suporte, ou entao que contenham pouca ou nenhuma informac,ao
   sobre como o problema ocorre e sobre como proceder para
   reproduzi-lo.

   Este documento tem por objetivo descrever como escrever bons
   relatorios de problema. Mas o que vem a ser um bom relatorio de
   problema? Bem, indo direto ao ponto, um bom relatorio de problema
   e aquele que se pode analisar e tratar rapidamente, para a
   satisfac,ao mutua do usuario e do desenvolvedor.

   Embora o foco primario deste artigo seja a elaborac,ao de
   relatorios de problemas no FreeBSD, a maior parte das
   recomendac,oes deve aplicar-se muito bem a outros projetos de
   software.

   Observe que este artigo esta organizado de forma tematica, e nao
   de forma cronologica, desta forma voce deve ler o documento
   inteiro antes de enviar um relatorio de problema, ao inves de
   trata-lo como um tutorial passo-a-passo.

     --------------------------------------------------------------

2. Quando enviar um relatorio de problema

   Existem muitos tipos de problemas, e nem todos eles devem gerar um
   relatorio de problema. E claro, ninguem e perfeito e em algumas
   ocasioes voce tera certeza de que encontrou um bug em um
   determinado software quando na verdade voce compreendeu errado a
   sintaxe de um comando ou mesmo cometeu um erro de digitac,ao em um
   arquivo de configurac,ao (o que por sua vez pode indicar uma
   documentac,ao pouco detalhada ou entao um tratamento inadequado do
   erro por parte da aplicac,ao). Existem ainda muitas outras
   situac,oes nas quais enviar um relatorio de problema claramente
   nao e a melhor ac,ao a ser tomada, e so vai servir para frustrar a
   voce e aos desenvolvedores. Em contrapartida, existem situac,oes
   nas quais e recomendado que voce nos envie um relatorio de
   problema sobre outras coisas que nao um bug, como por exemplo para
   nos enviar uma sugestao de melhoria ou um pedido de uma nova
   funcionalidade.

   Entao como voce ira diferenciar o que e e o que nao e um bug?
   Existe uma regra de ouro que diz que o seu problema nao e um bug
   se ele pode ser expresso como uma pergunta (normalmente na forma
   "Como eu fac,o X" ou "Onde eu posso encontrar Y"). Na maior parte
   das vezes nao sera sempre tao claro desta forma, mas a regra acima
   cobre a grande maioria dos casos. Se voce estiver procurando por
   uma resposta, considere enviar a sua pergunta para lista de
   discussao para perguntas gerais sobre o FreeBSD.

   Veja alguns casos nos quais pode ser apropriado enviar um
   relatorio de problema sobre algo que nao e um bug:

     * Pedidos de melhorias nas funcionalidades. Geralmente e uma boa
       ideia debater estas propostas nas listas de discussao antes de
       envia-las em um relatorio de problemas.

     * Notificac,oes sobre atualizac,oes de softwares mantidos
       externamente (principalmente do ports, mas tambem de
       componentes do sistema base como, por exemplo, o BIND e varios
       outros utilitarios GNU).

       Para os ports sem manutenc,ao (aqueles nos quais a variavel
       MAINTAINER contem ports@FreeBSD.org), essas notificac,oes de
       atualizac,ao podem ser capturadas por um committer
       interessado, ou voce pode ser solicitado a fornecer um patch
       para atualizar o port; disponibilizar este patch
       antecipadamente ira melhorar de forma significativa as suas
       chances de ter o port atualizado rapidamente.

       Se o port possui um mantenedor, o envio de um relatorio de
       problema comunicando sobre o lanc,amento de uma nova versao
       geralmente nao e muito util uma vez que eles geram trabalho
       adicional para os committers, e o mantenedor provavelmente ja
       tem conhecimento de que existe uma nova versao, ele
       provavelmente ja trabalhou com os desenvolvedores para
       atualiza-lo e esta provavelmente executando testes para
       verificar se nao existem problemas, etc.

       Em ambos os casos, voce ira obter melhores resultados se
       seguir o processo descrito no Porter's Handbook. (Talvez voce
       tambem queira ler o artigo   Contribuindo para a Colec,ao de
       Ports do FreeBSD.)

   Um bug que nao pode ser reproduzido, raramente sera corrigido. Se
   o bug ocorreu uma unica vez e voce nao consegue reproduzi-lo, e se
   aparentemente ele nao ocorre com mais ninguem, as chances sao de
   que nenhum dos desenvolvedores sera capaz de reproduzir ou de
   saber o que esta errado. Isso nao significa que nao seja possivel,
   mas significa que a probabilidade do seu relatorio de problema
   resultar na correc,ao do bug e muito pequena. Para piorar a
   situac,ao, muitas vezes este tipo de erro e, na realidade, causado
   por falhas nos discos rigidos ou por superaquecimento do
   processador - sempre que possivel voce deve tentar excluir estas
   causas antes de enviar um relatorio de problema.

   Em seguida, para decidir a quem voce deve apresentar o seu
   relatorio de problema, voce precisa entender que o FreeBSD e
   composto de varios elementos de software diferentes:

     * Codigo na base do sistema que e escrito e mantido por
       colaboradores do FreeBSD, tais como o Kernel, a biblioteca C,
       os drivers de dispositivos (categorizados como kern); os
       utilitarios binarios (bin); as paginas de manual e a
       documentac,ao (docs); e as paginas web (www). Todos os bugs
       nestas areas devem ser reportados para os desenvolvedores do
       FreeBSD

     * Codigo na base do sistema que e escrito e mantido por outros,
       e que foram adaptados e importados no FreeBSD. Exemplos
       incluen bind, gcc(1), e sendmail(8). A maioria dos bugs nestas
       areas devem ser reportados para os desenvolvedores do FreeBSD;
       mas em alguns casos pode ser necessario reporta-los aos
       autores originais, caso o problema nao seja especifico do
       FreeBSD. Normalmente estes bugs irao ficar sob as categorias
       bin ou gnu.

     * Os aplicativos individuais que nao estao na base do sistema,
       mas que fazem parte da colec,ao de Ports do FreeBSD (Categoria
       ports). A maioria destes aplicativos nao sao escritos por
       desenvolvedores do FreeBSD; o que o FreeBSD oferece e apenas
       um sistema para facilitar a instalac,ao do aplicativo.
       Portanto, voce deve relatar um problema para os
       desenvolvedores do FreeBSD apenas quando voce acreditar que o
       problema e especifico do FreeBSD, caso contrario, voce deve
       reporta-lo aos autores do software.

   A seguir voce deve verificar se o problema e ou nao atual. Existem
   poucas coisas que aborrecem um desenvolvedor mais do que receber
   um relatorio de problema a respeito de um bug que ele ja corrigiu.

   Se o problema esta na base do sistema, voce devera primeiro ler a
   sec,ao do FAQ sobre   Versoes do FreeBSD, se voce nao estiver
   familiarizado com o tema. Nao e possivel para o FreeBSD corrigir
   problemas em versoes muito antigas do sistema base, desta forma
   enviar um relatorio de problema sobre um bug em uma versao muito
   antiga vai provavelmente resultar apenas em um desenvolvedor
   aconselhando que voce atualize o seu sistema para uma versao
   suportada para ver se o problema ainda ocorre. A equipe de
   Security Officer mantem a lista de versoes suportadas.

   Se o problema esta em um port, observe que voce devera primeiro
   atualizar seu sistema para a versao mais atual da colec,ao de
   ports e ver se o problema ainda se aplica. Devido ao ritmo
   acelerado de mudanc,as nestas aplicac,oes, e inviavel para o
   FreeBSD suportar qualquer coisa que nao seja obrigatoriamente a
   versao mais recente, e problemas com uma versao antiga do
   aplicativo simplesmente nao podem ser corrigidos.

     --------------------------------------------------------------

3. Preparac,ao

   Uma boa regra a ser seguida sempre e realizar uma busca a respeito
   do assunto antes de enviar um relatorio de problema. Pode ser que
   o seu problema ja tenha sido reportado anteriormente; pode ser que
   esteja sendo debatido nas listas de discussao ou que tenha sido
   recentemente; pode ate ser que o problema ja tenha sido corrigido
   em uma versao mais recente do que a que voce esta utilizando. Voce
   deve portanto verificar em todos os lugares obvios antes de enviar
   o relatorio de problema. Para o FreeBSD, isto significa:

     * A lista de Perguntas e Respostas mais Frequentes sobre o
       FreeBSD (FAQ). A FAQ tem por objetivo fornecer respostas para
       uma grande variedade de perguntas, tais como as que dizem
       respeito a compatibilidade de hardware, aplicac,oes do
       usuario, Configurac,ao do kernel, etc.

     * As   listas de discussao - se voce nao esta inscrito, utilize
       a   busca do historico no web site do FreeBSD. Se o seu
       problema nao tiver sido discutido nas listas, voce pode tentar
       enviar uma mensagem sobre ele e aguardar alguns dias para ver
       se alguem consegue perceber algo que voce tenha deixado passar
       desapercebido.

     * Opcionalmente, na internet inteira - utilize seu mecanismo de
       busca preferido para localizar referencias sobre o seu
       problema. Voce pode encontrar referencias a ele em mensagens
       de listas de discussao ou de grupos de noticias dos quais voce
       nunca ouviu falar ou nos quais sequer pensou em procurar.

     * Na sequencia, verifique o   banco de dados com os relatorios
       de problema do FreeBSD (GNATS). A menos que o seu problema
       seja recente ou muito obscuro, existe uma boa chance dele ja
       ter sido reportado.

     * E o mais importante, voce deve verificar se a documentac,ao
       existente no codigo base nao enderec,a o seu problema.

       Para o codigo base do FreeBSD voce deve estudar cuidadosamente
       o conteudo do arquivo /usr/src/UPDATING disponivel no seu
       sistema de arquivos ou a sua versao mais recente no  
       Repositorio Subversion. (Esta informac,ao e vital se voce
       estiver atualizando de uma versao para outra - especialmente
       se estiver atualizando para o FreeBSD-CURRENT).

       No entanto, se o problema e com algo que foi instalado como
       uma parte da colec,ao de ports do FreeBSD voce deve consultar
       o /usr/ports/UPDATING (para os ports individuais) ou o
       /usr/ports/CHANGES (para mudanc,as que afetam a Colec,ao de
       Ports inteira). Estes arquivos tambem estao disponiveis no
       SVNWeb, nos urls http://svnweb.freebsd.org/ports/head/UPDATING
       e http://svnweb.freebsd.org/ports/head/CHANGES
       respectivamente.

     --------------------------------------------------------------

4. Escrevendo o Relatorio de Problema

   Agora que voce decidiu que o seu assunto merece um relatorio de
   problema (PR), e que ele e um problema do FreeBSD, e hora de
   escrever o relatorio em si. Mas antes de entrarmos na mecanica do
   programa utilizado para gerar e enviar os PRs, aqui estao algumas
   dicas e truques para ajuda-lo a garantir que o seu PR sera o mais
   efetivo possivel.

     --------------------------------------------------------------

  4.1. Dicas e truques para escrever um bom relatorio de problema.

     * Nao deixe a linha de "Synopsis" (sinopse) em branco. Os PRs
       sao enviados para listas de discussao no mundo todo (nas quais
       a "Synopsis" e utilizada como linha de Subject:), alem 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 pula-lo.
       Lembre-se que os PRs permanecem na base de dados ate que sejam
       fechados por alguem; os anonimos normalmente irao desaparecer
       em meio ao ruido.

     * Evite utilizar uma "Synopsis" (sinopse) fraca. Voce nao pode
       assumir que alguem que esteja lendo o seu PR conhec,a todo o
       contexto que motivou o seu envio, desta forma quanto mais
       informac,ao voce fornecer, melhor. Por exemplo, a que parte do
       sistema o problema se aplica? O problema ocorre durante a
       instalac,ao ou durante a execuc,ao do sistema? Para ilustrar,
       ao inves de utilizar Synopsis: o portupgrade esta quebrado,
       veja o quao mais claro e mais eficiente seria utilizar
       Synopsis: port sysutils/portupgrade gerando coredumps no
       -current. (No caso de um port, e especialmente util ter a
       categoria e o nome do port na linha de sinopse.)

     * Se voce possui um patch, mencione-o. Um PR que inclui um patch
       e muito mais provavel de ser analisado do que um sem. Se voce
       estiver incluindo um, coloque a palavra [patch] no inicio da
       linha de sinopse. (Embora nao seja obrigatorio utilizar
       exatamente esta palavra, por convenc,ao, e ela que e
       utilizada.)

     * Se voce e um maintainer (mantenedor), diga-o. Se voce esta
       mantendo uma parte do codigo fonte (por exemplo, um port),
       voce deve considerar a possibilidade de incluir as palavras
       [maintainer update] (incluindo os colchetes) no inicio da
       linha de sinopse e deve definir a "class" (classe) do seu PR
       para maintainer-update. Desta forma qualquer committer que
       manusear o seu PR nao tera de verificar o Makefile do port,
       para certificar-se de que a atualizac,ao foi enviada pelo
       maintainer.

     * Seja especifico. Quanto mais informac,oes voce fornecer sobre
       o problema que voce esta tendo, melhores serao as suas chances
       de obter uma resposta.

          * Inclua a versao do FreeBSD que voce esta utilizando
            (existe um lugar para colocar esta informac,ao, veja
            abaixo) e em qual arquitetura. Voce incluir a informac,ao
            se esta executando a partir de um Release (e.g. de um
            CDROM ou Download), ou a partir de um sistema mantido com
            o cvsup(1) (e neste caso, quando foi atualizado pela
            ultima vez). Se voce estiver utilizando o
            FreeBSD-CURRENT, esta vai ser a primeira coisa que alguem
            ira lhe perguntar, porque as correc,oes (especialmente
            para os problemas de alto nivel) tendem a serem
            realizadas muito rapidamente, e espera-se que os usuarios
            do FreeBSD-CURRENT mantenham-se atualizados.

          * Inclua quais opc,oes globais voce especificou no seu
            make.conf. Observac,ao: E conhecido que utilizar -O2 (e
            acima disso) com o gcc(1) gera problemas em muitas
            situac,oes. Apesar dos desenvolvedores do FreeBSD
            aceitarem patches, eles normalmente nao estao dispostos a
            investigar este tipo de problema por uma simples falta de
            tempo e de voluntarios, e ao inves disso podem responder
            apenas que isto nao e suportado.

          * Se o problema pode ser reproduzido facilmente, inclua
            informac,oes para possibilitar que ele seja reproduzido
            pelos desenvolvedores. Se o problema so pode ser
            demonstrado com a entrada de um conjunto de dados
            especifico, voce devera incluir um exemplo destas
            informac,oes, alem de informar qual e resultado atual
            (errado) e qual era o resultado esperado (correto). Se o
            conjunto de dados for muito grande ou se o mesmo nao
            puder ser tornado publico, tente criar um arquivo com o
            minimo de informac,oes necessarias para replicar o
            problema, e que possa ser incluido no seu PR.

          * Se for um problema com o kernel, esteja preparado para
            fornecer as seguintes informac,oes (Voce nao precisa
            fornecer estas informac,oes por padrao, o que so tende a
            encher o banco de dados, mas voce deve incluir os trechos
            acreditar que sao relevantes):

               * A configurac,ao do seu kernel (incluindo quais
                 dispositivos de hardware voce tem instalados)

               * Se voce tem ou nao opc,oes de depurac,ao habilitadas
                 (tais como WITNESS), e em caso afirmativo, se o
                 problema continua ocorrendo quando voce altera a
                 logica de configurac,ao destas opc,oes

               * O texto completo de qualquer backtrace, panic e
                 outras mensagens no console, ou os registros do
                 /var/log/messages, caso tenha sido gerado algum

               * A saida do pciconf -l e as partes relevantes da
                 saida do dmesg se o problema estiver relacionado a
                 um componente de hardware

               * O fato de que voce leu o src/UPDATING e que o seu
                 problema nao esta listado ali (e certeza que alguem
                 vai perguntar)

               * Se voce consegue ou nao executar outro kernel (Isto
                 e para poder descartar a possibilidade de ser um
                 problema de hardware tais como falha nos discos
                 rigidos e superaquecimento dos processadores, cujos
                 sintomas podem se confundir com problemas no kernel)

          * Se for um problema com um port, esteja preparado para
            fornecer as seguintes informac,oes (Voce nao precisa
            fornecer estas informac,oes por padrao, o que so tende a
            encher o banco de dados, mas voce deve incluir os trechos
            acreditar que sao relevantes):

               * Quais ports voce tem instalados

               * As variaveis de ambiente que substituem os padroes
                 do bsd.port.mk, como por exemplo PORTSDIR

               * O fato de que voce leu o ports/UPDATING e que o seu
                 problema nao esta listado ali (e certeza que alguem
                 vai perguntar)

     * Evite pedidos vagos de novas funcionalidades. Os PRs no
       formato "alguem realmente deveria implementar algo que faz
       isso e aquilo" sao menos provaveis de obterem uma resposta do
       que os que sao mais especificos. Lembre-se, o codigo esta
       disponivel para todos, de forma que se voce deseja uma nova
       funcionalidade, a melhor maneira de ter certeza de que ela
       sera incluida e comec,ar a trabalhar! Tambem considere o fato
       de que muitas destas sugestoes fariam mais sentido como um
       topico de discussao na freebsd-questions do que como uma
       entrada no banco de dados de PRs, como discutido acima.

     * Certifique-se de que ninguem tenha submetido um PR semelhante
       antes. Embora isso ja tenha sido mencionado anteriormente, faz
       sentido repetir aqui. Esta verificac,ao ira lhe tomar apenas 1
       ou 2 minutos no uso do   mecanismo de busca do banco de dados
       de PRs. (e claro, todos sao culpados de ja terem esquecido de
       fazer isso de uma vez ou outra.)

     * Relate apenas um problema em cada relatorio. Evite incluir
       dois ou mais problemas em um mesmo relatorio caso eles nao
       estejam relacionados. Quando voce submeter um patch, evite
       adicionar varias funcionalidades ou corrigir varios bugs em um
       mesmo PR, a menos que eles sejam estritamente relacionados -
       Este tipo de PR muitas vezes demanda mais tempo para ser
       resolvido.

     * Evite solicitac,oes polemicas. Se o seu PR esta relacionado a
       um tema que foi polemico no passado, voce deve estar preparado
       para nao somente disponibilizar um patch, como tambem para
       defender porque o seu patch e "a coisa certa a se fazer". Como
       mencionado acima, realizar uma busca cuidadosa no historico
       das listas de discussao e sempre uma boa forma de se preparar.

     * Seja educado. Praticamente todas as pessoas que potencialmente
       podem trabalhar no seu PR sao voluntarios. Ninguem gosta de
       receber ordens para fazer algo que eles ja estao fazendo por
       alguma outra motivac,ao a qual nao e a de ganho financeiro.
       Esta e uma boa coisa para ter sempre em mente num projeto de
       codigo aberto.

     --------------------------------------------------------------

  4.2. Antes de voce iniciar

   Antes de executar o programa send-pr(1), certifique-se que a sua
   variavel de ambiente VISUAL (ou a EDITOR se a VISUAL nao estiver
   definida) esta definida com seu editor preferido.

   Voce tambem deve certificar-se de que o seu sistema de entrega de
   emails esta funcionando corretamente. O send-pr(1) utiliza
   mensagens de email para enviar e rastrear um relatorio de
   problema. Se voce nao pode enviar mensagens de email a partir da
   maquina na qual esta executando o send-pr(1), os seus relatorios
   de problema nao irao chegar ate a base de dados GNATS. Para
   maiores detalhes de como configurar o sistema de email no FreeBSD,
   consulte o capitulo sobre "Correio Eletronico" no Handbook do
   FreeBSD.

   Certifique-se de que o seu sistema de email nao ira alterar a
   formatac,ao da mensagem ao encaminha-la para o GNATS. Qualquer
   patch que voce enviar sera inutilizado, caso o seu sistema de
   email quebre automaticamente as linhas, troque tabulac,oes por
   espac,os em branco ou altere os caracteres de mudanc,a para uma
   nova linha, etc. Entretanto, para as sec,oes de texto nos pedimos
   que voce quebre manualmente as linhas proximo dos 70 caracteres,
   desta forma a versao web do PR podera ser lida melhor.

   Considerac,oes similares se aplicam se voce estiver utilizando o
   formulario web de submissao de PR ao inves de utilizar o
   send-pr(1). Observe que operac,oes de copiar-e-colar possuem seus
   proprios efeitos colaterais na formatac,ao do texto. Em certos
   casos, pode ser necessario usar o uuencode(1) para garantir que os
   patches cheguem sem modificac,oes.

   Finalmente, se a sua submissao sera longa, voce deve preparar o
   texto do seu relatorio offline, desta forma nada sera perdido no
   caso de voce ter problemas quando for submete-lo. Isto pode ser um
   problema, em especial, se voce estiver utilizando o formulario
   web.

     --------------------------------------------------------------

  4.3. Anexando patches ou arquivos

   As instruc,oes abaixo se aplicam ao envio de PRs por email:

   O programa send-pr(1) tem a capacidade de anexar arquivos em um
   relatorio de problemas. Voce pode anexar quantos arquivos desejar
   desde que os mesmos possuam nomes unicos (i.e. o nome proprio do
   arquivo, sem o caminho de diretorio). Basta usar a opc,ao -a na
   linha de comando para anexar os arquivos desejados:

 % send-pr -a /var/run/dmesg -a /tmp/errors

   Nao se preocupe com os arquivos binarios, eles serao encodados
   automaticamente de forma a nao perturbar o seu agente de correio.

   Se voce anexar um patch, tenha certeza de utilizar a opc,ao -c ou
   -u no diff(1) para criar um diff contextual ou um diff unificado
   (o formato unificado e preferido), e tenha certeza de especificar
   os numeros de revisao exatos dos arquivos que voce modificou,
   desta forma o desenvolvedor que ler seu relatorio tera condic,oes
   de aplica-los facilmente. Para problemas com o kernel ou com os
   aplicativos do sistema base, um patch para o FreeBSD-CURRENT (o
   ramo HEAD do CVS) e preferido uma vez que todo novo codigo deve
   ser aplicado e testado primeiro nele. Depois que forem realizados
   os testes apropriados, o codigo sera fundido ou migrado para o
   ramo FreeBSD-STABLE.

   Se voce juntar um patch no corpo do email, em vez de envia-lo como
   um arquivo anexo, voce estara sujeito a ocorrencia de um problema
   bastante comum ocasionado pela tendencia de alguns clientes de
   email de converter tabs em espac,os, o que ira arruinar
   completamente qualquer coisa que voce tenha enviado com intenc,ao
   de que fosse parte de um Makefile.

   Nao envie patches como anexos usando Content-Transfer-Encoding:
   quoted-printable . Isto ira realizar character escaping e o patch
   inteiro estara inutilizado.

   Observe tambem que incluir pequenos patches em um PR e normalmente
   a coisa certa a se fazer - particularmente quando ele corrige o
   problema descrito no PR - grandes patches e especialmente codigo
   novo, que normalmente requerem uma revisao substancial antes de
   serem incorporados, devem ser colocados em um servidor web ou de
   FTP, e a url deve ser incluida no PR ao inves do patch
   propriamente dito. Os patches dentro de um email tendem a se
   deformar, especialmente quando o GNATS esta envolvido, e quanto
   maior o patch, maior e a dificuldade para ambas as partes em
   conserta-lo. Alem de que, ao colocar o patch na web, voce pode
   modifica-lo sem ter que reenviar o arquivo completo como um
   followup do PR original. Alem disso, os grandes patches
   simplesmente aumentam o tamanho do banco de dados, uma vez que os
   relatorios de problema fechados nao sao deletados, continuando a
   existir marcados como closed.

   Voce deve observar que a menos que especifique explicitamente no
   seu PR ou diretamente no seu patch, qualquer correc,ao que voce
   envie sera considerada como estando licenciada sob os mesmos
   termos do arquivo original que voce modificou.

     --------------------------------------------------------------

  4.4. Preenchendo o template

   As instruc,oes abaixo se aplicam apenas ao envio de PRs por email:

   Quando voce executar o programa send-pr(1), voce sera apresentado
   a um template. O template consiste em uma lista de campos, alguns
   dos quais estarao pre-preenchidos, e alguns irao possuir
   comentarios explicando o seu proposito ou entao listando os
   valores aceitaveis. Nao se preocupe com os comentarios, eles serao
   removidos automaticamente se voce nao modifica-los ou entao os
   remova voce mesmo.

   Na parte superior do template, logo abaixo das linhas SEND-PR:,
   esta o cabec,alho do email. Voce normalmente nao necessita
   modifica-lo, a menos que voce esteja enviando o relatorio de
   problema a partir de uma maquina ou de uma conta a qual pode
   enviar, mas nao pode receber emails, neste caso voce deve
   configurar manualmente os campos From: e Reply-To: para o seu
   enderec,o de email real. Voce tambem pode querer enviar uma copia
   do relatorio para voce mesmo (ou para alguma outra pessoa) atraves
   do uso de uma copia carbono, adicionando um ou mais enderec,os de
   email na linha de cabec,alho Cc:.

   Os campos de linha unica descritos abaixo, estao disponiveis
   apenas no template do email:

     * Submitter-Id: Nao altere este campo. O valor padrao e
       current-users e esta correto, mesmo se voce estiver executando
       o FreeBSD-STABLE.

     * Confidential: Nao altere este campo. O valor padrao e no. Nao
       tem sentido altera-lo ja que nao existem relatorios de
       problema confidenciais no FreeBSD - o banco de dados de PR e
       distribuido mundialmente pelo CVSup.

     * Severity: Escolha uma opc,ao entre non-critical, serious ou
       critical. Nao fac,a escandalo; abstenha-se de rotular seu
       problema como critical a menos que ele realmente seja (por ex.
       questoes de corrupc,ao de dados, grave retrocesso de
       funcionalidade no -CURRENT em relac,ao a versao anterior,
       etc)ou de serious a menos que seja algo que vai afetar muitos
       usuarios (Kernel panic ou travamentos do sistema; Problemas
       com algum driver de dispositivo em particular ou com
       utilitarios de sistema). Os desenvolvedores do FreeBSD nao
       irao necessariamente trabalhar no seu problema mais rapido se
       voce inflar sua importancia uma vez que existem muitas outras
       pessoas que fizeram exatamente isso - na verdade, alguns
       desenvolvedores prestam pouca atenc,ao a este campo por causa
       disso.

         Nota: Problemas de seguranc,a nao devem ser submetidos para
         o GNATS, pois todas as informac,oes no GNATS sao de
         conhecimento publico. Por favor, envie estes problemas
         seguindo as nossas diretrizes sobre relatorios de
         seguranc,a.

     * Priority: Escolha uma opc,ao entre low, medium ou high. high
       deve ser reservada para os problemas que afetam praticamente
       todos os usuarios do FreeBSD e medium para os problemas que
       vao afetar muitos usuarios.

         Nota: Este campo tornou-se tao amplamente abusado que perdeu
         quase que completamente seu objetivo.

   A proxima sec,ao descreve os campos que sao comuns entre a
   interface por email e a interface web:

     * Originator: Por favor informe seu nome completo, seguido
       opcionalmente pelo seu enderec,o de email entre colchetes. Na
       interface de email, este campo e normalmente pre-preenchido
       com o campo gecos do usuario com o qual voce esta atualmente
       logado.

         Nota: O enderec,o de email que voce utilizar ira se tornar
         uma informac,ao publica e pode vir a se tornar disponivel
         para spammers. Voce devera ter um sistema antispam funcional
         ou entao devera utilizar uma conta temporaria de email.
         Contudo, por favor, lembre-se que se voce nao utilizar uma
         conta de email valida, nos nao seremos capazes de entrar em
         contato com voce para fazer perguntas sobre o seu PR.

     * Organization: Campo livre para o que voce quiser colocar. Este
       campo nao e utilizado para nada significativo.

     * Synopsis: Preencha este campo com uma descric,ao curta e
       precisa sobre o seu problema. A synopsis e utilizada como o
       assunto do email do relatorio de problema, e tambem e
       utilizada na listagem de relatorio de problemas e resumos;
       relatorios de problema com synopses obscuras tendem a serem
       ignorados.

       Como mencionado acima, se o seu relatorio de problema inclui
       um patch, por favor, inicie sua synopsis com [patch]
       (incluindo os colchetes); se voce for um maintainer considere
       adicionar [maintainer update] (incluindo os colchetes) ao
       inicio da sua synopsis e defina a "classe" do seu PR para
       maintainer-update.

     * Category: Escolha uma categoria adequada.

       A primeira coisa que voce precisa fazer e decidir em qual
       parte do sistema o seu problema esta. Lembre-se, o FreeBSD e
       um sistema operacional completo, o qual instala um kernel, as
       bibliotecas padrao, muitos drivers de dispositivos e um grande
       numero de utilitarios (este conjunto recebe o nome de "sistema
       base"). No entanto, existem milhares de aplicativos adicionais
       na Colec,ao de Ports. Voce primeiro precisa decidir se o
       problema esta no sistema base ou se esta em algo que foi
       instalado atraves da Colec,ao de Ports.

       Aqui esta uma descric,ao das principais categorias:

          * Se o problema e com o Kernel, com as bibliotecas (tal
            como a biblioteca C padrao, libc), ou com um driver de
            dispositivo do sistema base, em geral voce vai usar a
            categoria kern. (Existem algumas excec,oes; veja abaixo).
            Em geral, estas sao coisas que estao descritas nas
            sec,oes 2, 3 ou 4 das paginas de manual.

          * Se o problema e com um programa binario, tal como o sh(1)
            ou o mount(8), primeiro voce precisa determinar se estes
            programas pertencem ao sistema base ou se foram
            adicionados atraves da colec,ao de ports. Se voce estiver
            na duvida, voce pode executar um whereis  
            nomedoprograma, no FreeBSD por convenc,ao todos os
            aplicativos da colec,ao de ports sao instalados sob
            /usr/local, embora isso possa ser alterado por um
            administrador de sistemas. Para estes, voce ira utilizar
            a categoria ports (sim, mesmo que a categoria do port
            seja www; veja abaixo). Se a localizac,ao do aplicativo
            for /bin, /usr/bin, /sbin, ou /usr/sbin, ele faz parte do
            sistema base, e voce devera utilizar a categoria bin.
            (Alguns programas, como o gcc(1), na pratica utilizam a
            categoria gnu, mas nao se preocupe com isso por agora.)
            Todos estes aplicativos estao descritos nas sec,oes 1 ou
            8 das paginas de manual.

          * Se voce acredita que o erro esta no script de
            inicializac,ao (rc), ou em algum outro tipo de arquivo de
            configurac,ao nao executavel, entao a categoria indicada
            sera a conf (configurac,ao). Estas sao coisas descritas
            na sec,ao 5 das paginas de manual.

          * Se voce encontrou um problema na documentac,ao (artigos,
            livros, paginas de manual, etc.), a escolha correta para
            a categoria e a opc,ao docs.

          * Se voce esta tendo problemas com as paginas web do
            FreeBSD, a escolha apropriada e www.

              Nota: Independentemente se voce esta tendo algum
              problema com um port chamado www/nomedoport, a
              categoria correta para o mesmo sera ports.

       Existem algumas categorias mais especializadas.

          * Se o problema pode ser classificado na categoria kern, e
            esta relacionado ao subsistema USB, a categoria correta
            sera usb.

          * Se o problema pode ser classificado na categoria kern, e
            esta relacionado com as bibliotecas de threads, a
            categoria correta sera threads.

          * Se o problema esta localizado no sistema base, mas esta
            relacionado a nossa aderencia a padroes tais como o
            POSIX(R), a categoria correta sera standards.

          * Se o problema esta relacionado a erros internos de uma
            Java Virtual Machine(TM) (JVM(TM)), mesmo que o Java(TM)
            tenha sido instalado a partir da colec,ao de ports, voce
            deve selecionar a categoria java. Problemas genericos com
            o port do Java devem continuar sendo enviados na
            categoria ports.

       Isto deixa tudo mais.

          * Se voce esta convencido de que o problema ira ocorrer
            apenas na arquitetura do processador que voce esta
            utilizando, selecione uma categoria especifica para a sua
            arquitetura: geralmente i386 para maquinas compativeis
            com a arquitetura Intel de 32 bits, amd64 para maquinas
            AMD executando em modo 64 bits (o que tambem inclui
            maquinas compativeis com a arquitetura Intel executando
            em modo EMT64); e menos comumente ia64, powerpc, e
            sparc64.

              Nota: Estas categorias sao muitas vezes utilizadas de
              forma indevida para problemas do tipo "Eu nao sei". Em
              vez de tentar adivinhar, por favor, apenas utilize a
              categoria misc.

            Exemplo 1. Uso correto da categoria especifica de
            arquitetura.

            Voce tem um computador comum (PC), e acredita que
            encontrou um problema especifico com um chipset em
            particular ou com uma placa mae especifica: A categoria
            correta e i386.

            Exemplo 2. Uso incorreto da categoria especifica de
            arquitetura.

            Voce esta tendo problemas com uma placa de expansao
            instalada em um barramento bastante comum, ou um problema
            com um tipo especifico de disco rigido: neste caso, e
            provavel que o problema ocorra em mais de uma
            arquitetura, e a categoria correta seria kern.

          * Se voce realmente nao sabe onde esta o problema (ou o
            mesmo nao parece se encaixar nas categorias acima),
            utilize a categoria misc. Mas antes de fazer isto, pode
            ser uma boa ideia primeiro pedir ajuda na lista de
            discussao para perguntas gerais sobre o FreeBSD. Voce
            podera ser orientado `a utilizar uma das outras
            categorias para obter um melhor resultado.

       Aqui esta a lista atual de categorias (retirada do url
       http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories):

          * advocacy: problemas relacionados a imagem publica do
            FreeBSD. Obsoleta.

          * alpha: problemas especificos da plataforma Alpha.

          * amd64: problemas especificos da plataforma AMD64.

          * arm: problemas especificos da plataforma ARM.

          * bin: problemas com os programas de nivel de usuario na
            base do sistema.

          * conf: problemas com os arquivos de configurac,ao, valores
            padroes, etc.

          * docs: problemas com as paginas de manuais ou com a
            documentac,ao online.

          * gnu: problemas com softwares GNU, tais como gcc(1) ou
            grep(1).

          * i386: problemas especificos da plataforma i386(TM).

          * ia64: problemas especificos da plataforma ia64.

          * java: problemas relacionados com a Maquina Virtual Java.

          * kern: problemas com o kernel, drivers de dispositivo (nao
            especificos `a uma plataforma), ou bibliotecas do sistema
            base.

          * misc: Tudo aquilo que nao se encaixa numa das outras
            categorias. (observe que nao existe nada que pertenc,a
            verdadeiramente a esta categoria, exceto os problemas com
            a infra estrutura de build e de release. As falhas
            temporarias de compilac,ao do HEAD nao pertencem a esta
            categoria. Tambem observe que e facil para as coisas se
            perderem nesta categoria).

          * ports: problemas relacionados com a Colec,ao de Ports.

          * powerpc: problemas especificos da plataforma PowerPC(R).

          * sparc64: problemas especificos da plataforma SPARC64(R).

          * standards: problemas relacionados a conformidade com os
            padroes.

          * threads: problemas relacionados a implementac,ao de
            threads no FreeBSD (especialmente no FreeBSD-CURRENT).

          * usb: problemas relacionados a implementac,ao do USB no
            FreeBSD.

          * www: mudanc,as e melhorias no web site do FreeBSD.

     * Class: Escolha uma das seguintes opc,oes:

          * sw-bug: bugs de software.

          * doc-bug: erros na documentac,ao.

          * change-request: solicitac,ao de novas funcionalidades ou
            de alterac,oes em funcionalidades existentes.

          * update: atualizac,oes para o ports ou para outros
            softwares de terceiros.

          * maintainer-update: atualizac,oes de ports pelos quais
            voce e o responsavel.

     * Release: E a versao do FreeBSD que voce esta utilizando. Este
       campo e preenchido automaticamente pelo send-pr(1) e so
       necessita ser alterado se voce estiver enviando o relatorio de
       problema de um sistema diferente do que apresenta o problema.

   Finalmente, ha uma serie de campos de varias linhas:

     * Environment: Este campo deve descrever, da forma mais precisa
       possivel, o ambiente no qual o problema foi observado. Isto
       inclui a versao do sistema operacional, a versao do programa
       ou do arquivo especifico que contem o problema, e qualquer
       outro item relevante tal como a configurac,ao do sistema,
       outros softwares instalados que tenham influencia no problema,
       etc. - ou seja, simplesmente tudo o que um desenvolvedor
       precisar saber para reconstruir o ambiente no qual o problema
       ocorreu.

     * Description: Uma descric,ao precisa e completa do problema que
       voce esta experimentando. Tente evitar especular sobre as
       causas do problema a menos que voce tenha certeza de que esta
       no caminho certo, do contrario voce pode induzir o
       desenvolvedor a fazer suposic,oes incorretas sobre o problema.

     * How-To-Repeat: Um resumo com as ac,oes que voce precisa
       executar para reproduzir o problema.

     * Fix: Preferencialmente um patch, ou no minimo um workaround (o
       que nao so ajuda as outras pessoas que estao com o mesmo
       problema, como tambem auxilia o desenvolvedor a entender
       melhor a causa do problema), mas se voce nao tem nenhuma ideia
       consistente, e melhor deixar este campo em branco do que
       especular.

     --------------------------------------------------------------

  4.5. Enviando o relatorio de problemas

   Se voce esta utilizando o send-pr(1):

   Uma vez que voce tenha terminado de preencher o template, salve-o,
   e saia do editor de texto, ao fazer isto o send-pr(1) ira lhe
   perguntar se voce deseja s)end, e)dit or a)bort?. Para ir em
   frente e enviar o relatorio de problema pressione s, caso voce
   queira voltar ao editor para realizar alguma alterac,ao pressione
   e, ou entao pressione a para cancelar o envio. Se voce optar por
   abortar, o seu relatorio de problema ira permanecer no seu disco
   rigido (o send-pr(1) ira lhe informar o nome do arquivo antes de
   finalizar), assim voce podera edita-lo quando for mais
   conveniente, ou podera transferi-lo para um sistema com uma melhor
   conectividade, no qual podera envia-lo usando a opc,ao -f com o
   send-pr(1):

 % send-pr -f ~/my-problem-report

   Este comando ira ler o arquivo especificado, validar o seu
   conteudo, remover os comentarios e enviar o seu PR.

   Se voce esta utilizando o formulario web:

   Antes de pressionar o botao submit para enviar o seu relatorio,
   voce tera que preencher um campo com o texto exibido na imagem de
   captcha exibida no final do formulario. Infelizmente esta medida
   teve de ser adotada devido ao mau uso do mesmo por sistemas
   automatizados e por alguns individuos mal intencionados. E um mal
   necessario do qual ninguem gosta. Por favor, nao pec,a para
   remove-lo.

   Recomendamos fortemente que voce salve o seu trabalho em algum
   outro lugar antes de pressionar o botao submit. Um problema comum
   e que ocorre com muitos usuarios e a visualizac,ao de uma imagem
   de captcha velha exibida a partir do cache do navegador. Se isso
   acontecer com voce o seu envio sera rejeitado e voce podera perder
   o seu trabalho.

   Se voce, por qualquer motivo, nao conseguir visualizar as imagens,
   e tambem estiver impossibilitado de utilizar o send-pr(1), por
   favor, aceite nossas desculpas por esta inconveniencia e envie seu
   relatorio de problema por e-mail para a equipe de bugbusters do
   FreeBSD, no enderec,o <freebsd-bugbusters@FreeBSD.org>.

     --------------------------------------------------------------

5. Acompanhamento

   Depois que seu relatorio de problema tiver sido entregue, voce
   recebera uma confirmac,ao por e-mail com o numero de rastreamento
   que foi atribuido ao mesmo e uma URL a qual voce podera utilizar
   para consultar o status do seu PR. Com um pouco de sorte, alguem
   ira se interessar pelo seu problema e tentara resolve-lo, ou,
   conforme o caso explicar porque nao se trata de um problema. Voce
   sera notificado automaticamente de qualquer mudanc,a de status, e
   ira receber uma copia de qualquer comentario ou correc,ao que
   alguem venha a anexar `a trilha de auditoria do seu relatorio de
   problema.

   Se alguem lhe requisitar alguma informac,ao adicional, ou se voce
   lembrar de algo ou descobrir algo que voce nao tenha mencionado no
   seu relatorio inicial, por favor utilize um dos dois metodos
   abaixo para enviar uma atualizac,ao:

     * A forma mais facil e utilizar o link e followup existente na
       pagina web individual de cada PR, a qual pode ser encontrada a
       partir da   pagina de busca de relatorios. Ao clicar no link
       sera aberta uma janela do seu cliente de e-mail com os campos
       To: e Subject: ja corretamente preenchidos (se o seu navegador
       estiver configurado corretamente para fazer isto).

     * Alternativamente, voce pode apenas envia-lo para
       <bug-followup@FreeBSD.org>, certificando-se de que o numero de
       rastreamento esta incluso no Subject: de forma que o sistema
       de acompanhamento de bugs tenha como saber em qual relatorio
       de problema ele deve anexar o material recebido.

         Nota: Se voce nao incluir o numero de rastreamento, o GNATS
         ira se confundir e criara um relatorio de problema
         completamente novo, o qual sera atribuido ao administrador
         do GNATS, e entao o seu followup ira ficar perdido ate que
         alguem tenha tempo de arrumar a bagunc,a, o que pode levar
         dias e ate mesmo semanas para ocorrer.

         Forma errada:

 Subject: Sobre o PR que eu enviei

         Forma correta:

 Subject: Re: ports/12345: problemas de compilac,ao do foo/bar

   Se o relatorio de problema permanecer aberto depois que o problema
   ja tiver sido resolvido, basta enviar um follow-up (da forma
   descrita acima) informando que o PR pode ser fechado, e se
   possivel, explicando como e quando o problema foi corrigido.

     --------------------------------------------------------------

6. Se voce esta tendo problemas

   A maioria dos PRs que chegam ao sistema e processada rapidamente;
   entretanto em alguns momentos o GNATS fica lento e voce pode nao
   receber o seu email de confirmac,ao de imediato, levando 10
   minutos ou mesmo um pouco mais para recebe-lo. Por favor, tente
   ser paciente.

   Alem disso, uma vez que o GNATS recebe tudo por email, e
   absolutamente vital que o FreeBSD processe todas as mensagens que
   chegam utilizando filtros antispam. Se voce nao receber o email de
   confirmac,ao em ate duas horas, voce pode ter sido barrado por
   este sistema; Neste caso, por favor, entre em contato com o
   adminisrador do GNATS no enderec,o <bugmeister@FreeBSD.org> e
   pec,a ajuda.

     Nota: Dentre as medidas antispam que utilizamos existe uma a
     qual verifica a aderencia da sua mensagem em relac,ao a uma
     serie de abusos comums em emails baseados em HTML (embora o
     sistema nao necessariamente invalide uma mensagem devido a mera
     inclusao de codigo HTML no PR). Recomendamos fortemente que voce
     evite utilizar emails no formato HTML quando estiver enviando um
     PR: Nao apenas e provavel que a sua mensagem seja bloqueada
     pelos filtros, como ela tambem ira prejudicar o banco de dados.
     O bom e velho email em texto puro e fortemente preferido.

   Em raras ocasioes voce ira se deparar com um bug do GNATS pelo
   qual um PR sera aceito, recebera um numero de rastreamento, mas
   nao ira aparecer na lista de PRs em nenhuma consulta realizada no
   web site. O que pode ter ocorrido e que o indice do banco de dados
   ficou fora de sincronia com o proprio banco de dados. Uma forma de
   testar se e isto que esta acontecendo com voce e acessar um PR
   individual qualquer listado a partir do formulario de busca, 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 enderec,o <bugmeister@FreeBSD.org>.
   Observe que existe uma tarefa agendada no cron que reconstroi
   periodicamente o banco de dados, de forma que a menos que voce
   esteja com pressa, nenhuma ac,ao sera necessaria.

     --------------------------------------------------------------

7. Leituras complementares

   Esta e uma lista com material de referencia recomendado sobre boas
   praticas para se escrever e processar um relatorio de problema.
   Esta lista nao tem por objetivo ser uma lista completa.

     * Como reportar bugs de forma efetiva- Um excelente ensaio por
       Simon G. Tatham sobre a elaborac,ao de relatorios de problemas
       eficientes (nao e especifico sobre o FreeBSD).

     * Guia de como lidar com relatorios de problemas - Uma
       percepc,ao valiosa sobre como os desenvolvedores do FreeBSD
       devem lidar com os relatorios de problemas.

     --------------------------------------------------------------

            Este, e outros documentos, podem ser obtidos em
                ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

  Para perguntas sobre FreeBSD, leia a documentac,ao antes de contatar
                        <questions@FreeBSD.org>.
       Para perguntas sobre esta documentac,ao, envie e-mail para
                           <doc@FreeBSD.org>.
