                  Escrevendo Relatorios de Problema no FreeBSD

  Dag-Erling Smo/rgrav

   Contribuido por 

  Mark Linimon

   Revisao: 43184

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   CVSup is a registered trademark of John D. Polstra.

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

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

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

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

   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.

   2013-11-13 07:52:45 por hrs.
   Resumo

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

   [ Documento HTML em partes / Documento HTML completo ]

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

   Indice

   1. Introduc,ao

   2. Quando enviar um relatorio de problema

   3. Preparac,ao

   4. Escrevendo o Relatorio de Problema

   5. Acompanhamento

   6. Se voce esta tendo problemas

   7. Leituras complementares

   Indice Remissivo

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(TM) 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(TM).

          * 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.

Indice Remissivo

  R

   relatorio de problema, Escrevendo Relatorios de Problema no FreeBSD
