# Escrevendo Relatórios de Problema no FreeBSD

### Dag-Erling Smø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 “™” or the “®” symbol.

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

[ Split HTML / Single HTML ]

## 1. Introdução

Uma das experiências mais frustrantes que alguém pode ter como um usuário de um software é submeter um relatório sobre um problema que está enfrentando apenas para vê-lo ser sumariamente fechado com uma informação curta e pouco útil do tipo “isto não é um bug” ou ainda “este relatório de problema não procede”. Da mesma forma, uma das experiências mais frustrantes para um desenvolvedor de software é ser inundado com relatórios de problemas que na verdade não são realmente relatórios de problemas, mas sim solicitações de suporte, ou então que contenham pouca ou nenhuma informação sobre como o problema ocorre e sobre como proceder para reproduzi-lo.

Este documento tem por objetivo descrever como escrever bons relatórios de problema. Mas o que vem a ser um bom relatório de problema? Bem, indo direto ao ponto, um bom relatório de problema é aquele que se pode analisar e tratar rapidamente, para a satisfação mútua do usuário e do desenvolvedor.

Embora o foco primário deste artigo seja a elaboração de relatórios de problemas no FreeBSD, a maior parte das recomendações deve aplicar-se muito bem a outros projetos de software.

Observe que este artigo esta organizado de forma temática, e não de forma cronológica, desta forma você deve ler o documento inteiro antes de enviar um relatório de problema, ao invés de tratá-lo como um tutorial passo-a-passo.

## 2. Quando enviar um relatório de problema

Existem muitos tipos de problemas, e nem todos eles devem gerar um relatório de problema. É claro, ninguém é perfeito e em algumas ocasiões você terá certeza de que encontrou um bug em um determinado software quando na verdade você compreendeu errado a sintaxe de um comando ou mesmo cometeu um erro de digitação em um arquivo de configuração (o que por sua vez pode indicar uma documentação pouco detalhada ou então um tratamento inadequado do erro por parte da aplicação). Existem ainda muitas outras situações nas quais enviar um relatório de problema claramente não é a melhor ação a ser tomada, e só vai servir para frustrar a você e aos desenvolvedores. Em contrapartida, existem situações nas quais é recomendado que você nos envie um relatório de problema sobre outras coisas que não um bug, como por exemplo para nos enviar uma sugestão de melhoria ou um pedido de uma nova funcionalidade.

Então como você irá diferenciar o que é e o que não é um bug? Existe uma regra de ouro que diz que o seu problema não é um bug se ele pode ser expresso como uma pergunta (normalmente na forma “Como eu faço X” ou “Onde eu posso encontrar Y”). Na maior parte das vezes não será sempre tão claro desta forma, mas a regra acima cobre a grande maioria dos casos. Se você estiver procurando por uma resposta, considere enviar a sua pergunta para lista de discussão para perguntas gerais sobre o FreeBSD.

Veja alguns casos nos quais pode ser apropriado enviar um relatório de problema sobre algo que não é um bug:

- Pedidos de melhorias nas funcionalidades. Geralmente é uma boa idéia debater estas propostas nas listas de discussão antes de enviá-las em um relatório de problemas.

- Notificações sobre atualizações de softwares mantidos externamente (principalmente do ports, mas também de componentes do sistema base como, por exemplo, o BIND e vários outros utilitários GNU).

  Para os ports sem manutenção (aqueles nos quais a variável `MAINTAINER` contém `ports@FreeBSD.org`), essas notificações de atualização podem ser capturadas por um `committer` interessado, ou você pode ser solicitado a fornecer um `patch` para atualizar o port; disponibilizar este `patch` antecipadamente irá melhorar de forma significativa as suas chances de ter o port atualizado rapidamente.

  Se o port possui um mantenedor, o envio de um relatório de problema comunicando sobre o lançamento de uma nova versão geralmente não é muito útil uma vez que eles geram trabalho adicional para os `committers`, e o mantenedor provavelmente já tem conhecimento de que existe uma nova versão, ele provavelmente já trabalhou com os desenvolvedores para atualizá-lo e está provavelmente executando testes para verificar se não existem problemas, etc.

  Em ambos os casos, você irá obter melhores resultados se seguir o processo descrito no Porter's Handbook. (Talvez você também queira ler o artigo Contribuindo para a Coleção de Ports do FreeBSD.)

Um bug que não pode ser reproduzido, raramente será corrigido. Se o bug ocorreu uma única vez e você não consegue reproduzi-lo, e se aparentemente ele não ocorre com mais ninguém, as chances são de que nenhum dos desenvolvedores será capaz de reproduzir ou de saber o que está errado. Isso não significa que não seja possível, mas significa que a probabilidade do seu relatório de problema resultar na correção do bug é muito pequena. Para piorar a situação, muitas vezes este tipo de erro é, na realidade, causado por falhas nos discos rígidos ou por superaquecimento do processador — sempre que possível você deve tentar excluir estas causas antes de enviar um relatório de problema.

Em seguida, para decidir a quem você deve apresentar o seu relatório de problema, você precisa entender que o FreeBSD é composto de vários elementos de software diferentes:

- Código na base do sistema que é escrito e mantido por colaboradores do FreeBSD, tais como o Kernel, a biblioteca C, os drivers de dispositivos (categorizados como `kern`); os utilitários binários (`bin`); as páginas de manual e a documentação (`docs`); e as páginas web (`www`). Todos os bugs nestas áreas devem ser reportados para os desenvolvedores do FreeBSD

- Código na base do sistema que é 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 áreas devem ser reportados para os desenvolvedores do FreeBSD; mas em alguns casos pode ser necessário reportá-los aos autores originais, caso o problema não seja especifico do FreeBSD. Normalmente estes bugs irão ficar sob as categorias `bin` ou `gnu`.

- Os aplicativos individuais que não estão na base do sistema, mas que fazem parte da coleção de Ports do FreeBSD (Categoria `ports`). A maioria destes aplicativos não são escritos por desenvolvedores do FreeBSD; o que o FreeBSD oferece é apenas um sistema para facilitar a instalação do aplicativo. Portanto, você deve relatar um problema para os desenvolvedores do FreeBSD apenas quando você acreditar que o problema é específico do FreeBSD, caso contrário, você deve reportá-lo aos autores do software.

A seguir você deve verificar se o problema é ou não atual. Existem poucas coisas que aborrecem um desenvolvedor mais do que receber um relatório de problema a respeito de um bug que ele já corrigiu.

Se o problema está na base do sistema, você deverá primeiro ler a seção do FAQ sobre Versões do FreeBSD, se você não estiver familiarizado com o tema. Não é possível para o FreeBSD corrigir problemas em versões muito antigas do sistema base, desta forma enviar um relatório de problema sobre um bug em uma versão muito antiga vai provavelmente resultar apenas em um desenvolvedor aconselhando que você atualize o seu sistema para uma versão suportada para ver se o problema ainda ocorre. A equipe de `Security Officer` mantém a lista de versões suportadas.

Se o problema está em um port, observe que você deverá primeiro atualizar seu sistema para a versão mais atual da coleção de ports e ver se o problema ainda se aplica. Devido ao ritmo acelerado de mudanças nestas aplicações, é inviável para o FreeBSD suportar qualquer coisa que não seja obrigatoriamente a versão mais recente, e problemas com uma versão antiga do aplicativo simplesmente não podem ser corrigidos.

## 3. Preparação

Uma boa regra a ser seguida sempre é realizar uma busca a respeito do assunto antes de enviar um relatório de problema. Pode ser que o seu problema já tenha sido reportado anteriormente; pode ser que esteja sendo debatido nas listas de discussão ou que tenha sido recentemente; pode até ser que o problema já tenha sido corrigido em uma versão mais recente do que a que você está utilizando. Você deve portanto verificar em todos os lugares óbvios antes de enviar o relatório de problema. Para o 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, aplicações do usuário, Configuração do kernel, etc.

- As listas de discussão — se você não está inscrito, utilize a busca do histórico no web site do FreeBSD. Se o seu problema não tiver sido discutido nas listas, você pode tentar enviar uma mensagem sobre ele e aguardar alguns dias para ver se alguém consegue perceber algo que você tenha deixado passar desapercebido.

- Opcionalmente, na internet inteira — utilize seu mecanismo de busca preferido para localizar referências sobre o seu problema. Você pode encontrar referências a ele em mensagens de listas de discussão ou de grupos de noticias dos quais você nunca ouviu falar ou nos quais sequer pensou em procurar.

- Na sequência, verifique o banco de dados com os relatórios de problema do FreeBSD (GNATS). A menos que o seu problema seja recente ou muito obscuro, existe uma boa chance dele já ter sido reportado.

- E o mais importante, você deve verificar se a documentação existente no código base não endereça o seu problema.

  Para o código base do FreeBSD você deve estudar cuidadosamente o conteúdo do arquivo `/usr/src/UPDATING` disponível no seu sistema de arquivos ou a sua versão mais recente no Repositório Subversion. (Esta informação é vital se você estiver atualizando de uma versão para outra — especialmente se estiver atualizando para o FreeBSD-CURRENT).

  No entanto, se o problema é com algo que foi instalado como uma parte da coleção de ports do FreeBSD você deve consultar o `/usr/ports/UPDATING` (para os ports individuais) ou o `/usr/ports/CHANGES` (para mudanças que afetam a Coleção de Ports inteira). Estes arquivos também estão disponíveis no SVNWeb, nos urls http://svnweb.freebsd.org/ports/head/UPDATING e http://svnweb.freebsd.org/ports/head/CHANGES respectivamente.

## 4. Escrevendo o Relatório de Problema

Agora que você decidiu que o seu assunto merece um relatório de problema (PR), e que ele é um problema do FreeBSD, é hora de escrever o relatório em si. Mas antes de entrarmos na mecânica do programa utilizado para gerar e enviar os PRs, aqui estão algumas dicas e truques para ajudá-lo a garantir que o seu PR será o mais efetivo possível.

### 4.1. Dicas e truques para escrever um bom relatório de problema.

- Não deixe a linha de “Synopsis” (sinopse) em branco. Os PRs são enviados para listas de discussão no mundo todo (nas quais a “Synopsis” é utilizada como linha de `Subject:`), além de serem armazenados em um banco de dados. Qualquer pessoa que vier a navegar no banco de dados pelas sinopses, e encontrar um PR com a linha de assunto em branco, tende a pulá-lo. Lembre-se que os PRs permanecem na base de dados até que sejam fechados por alguém; os anônimos normalmente irão desaparecer em meio ao ruído.

- Evite utilizar uma “Synopsis” (sinopse) fraca. Você não pode assumir que alguém que esteja lendo o seu PR conheça todo o contexto que motivou o seu envio, desta forma quanto mais informação você fornecer, melhor. Por exemplo, a que parte do sistema o problema se aplica? O problema ocorre durante a instalação ou durante a execução do sistema? Para ilustrar, ao invés de utilizar `Synopsis: o portupgrade está quebrado`, veja o quão mais claro e mais eficiente seria utilizar `Synopsis: port sysutils/portupgrade gerando coredumps no -current`. (No caso de um port, é especialmente útil ter a categoria e o nome do port na linha de sinopse.)

- Se você possui um patch, mencione-o. Um PR que inclui um `patch` é muito mais provável de ser analisado do que um sem. Se você estiver incluindo um, coloque a palavra `[patch]` no inicio da linha de sinopse. (Embora não seja obrigatório utilizar exatamente esta palavra, por convenção, é ela que é utilizada.)

- Se você é um `maintainer` (mantenedor), diga-o. Se você está mantendo uma parte do código fonte (por exemplo, um port), você deve considerar a possibilidade de incluir as palavras `[maintainer update]` (incluindo os colchetes) no inicio da linha de sinópse e deve definir a “`class`” (classe) do seu PR para maintainer-update. Desta forma qualquer `committer` que manusear o seu PR não terá de verificar o `Makefile` do port, para certificar-se de que a atualização foi enviada pelo maintainer.

- Seja específico. Quanto mais informações você fornecer sobre o problema que você está tendo, melhores serão as suas chances de obter uma resposta.

  - Inclua a versão do FreeBSD que você está utilizando (existe um lugar para colocar esta informação, veja abaixo) e em qual arquitetura. Você incluir a informação se está executando a partir de um Release (e.g. de um CDROM ou Download), ou a partir de um sistema mantido com o cvsup(1) (e neste caso, quando foi atualizado pela ultima vez). Se você estiver utilizando o FreeBSD-CURRENT, esta vai ser a primeira coisa que alguém irá lhe perguntar, porque as correções (especialmente para os problemas de alto nível) tendem a serem realizadas muito rapidamente, e espera-se que os usuários do FreeBSD-CURRENT mantenham-se atualizados.

  - Inclua quais opções globais você especificou no seu `make.conf`. Observação: É conhecido que utilizar `-O2` (e acima disso) com o gcc(1) gera problemas em muitas situações. Apesar dos desenvolvedores do FreeBSD aceitarem patches, eles normalmente não estão dispostos a investigar este tipo de problema por uma simples falta de tempo e de voluntários, e ao invés disso podem responder apenas que isto não é suportado.

  - Se o problema pode ser reproduzido facilmente, inclua informações para possibilitar que ele seja reproduzido pelos desenvolvedores. Se o problema só pode ser demonstrado com a entrada de um conjunto de dados específico, você deverá incluir um exemplo destas informações, além de informar qual é resultado atual (errado) e qual era o resultado esperado (correto). Se o conjunto de dados for muito grande ou se o mesmo não puder ser tornado público, tente criar um arquivo com o mínimo de informações necessárias para replicar o problema, e que possa ser incluído no seu PR.

  - Se for um problema com o kernel, esteja preparado para fornecer as seguintes informações (Você não precisa fornecer estas informações por padrão, o que só tende a encher o banco de dados, mas você deve incluir os trechos acreditar que são relevantes):

    - A configuração do seu kernel (incluindo quais dispositivos de hardware você tem instalados)

    - Se você tem ou não opções de depuração habilitadas (tais como `WITNESS`), e em caso afirmativo, se o problema continua ocorrendo quando você altera a lógica de configuração destas opções

    - 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 saída do `pciconf -l` e as partes relevantes da saída do `dmesg` se o problema estiver relacionado a um componente de hardware

    - O fato de que você leu o `src/UPDATING` e que o seu problema não está listado ali (é certeza que alguém vai perguntar)

    - Se você consegue ou não executar outro kernel (Isto é para poder descartar a possibilidade de ser um problema de hardware tais como falha nos discos rígidos e superaquecimento dos processadores, cujos sintomas podem se confundir com problemas no kernel)

  - Se for um problema com um port, esteja preparado para fornecer as seguintes informações (Você não precisa fornecer estas informações por padrão, o que só tende a encher o banco de dados, mas você deve incluir os trechos acreditar que são relevantes):

    - Quais ports você tem instalados

    - As variáveis de ambiente que substituem os padrões do `bsd.port.mk`, como por exemplo `PORTSDIR`

    - O fato de que você leu o `ports/UPDATING` e que o seu problema não está listado ali (é certeza que alguém vai perguntar)

- Evite pedidos vagos de novas funcionalidades. Os PRs no formato “alguém realmente deveria implementar algo que faz isso e aquilo” são menos prováveis de obterem uma resposta do que os que são mais específicos. Lembre-se, o código está disponível para todos, de forma que se você deseja uma nova funcionalidade, a melhor maneira de ter certeza de que ela será incluída é começar a trabalhar! Também considere o fato de que muitas destas sugestões fariam mais sentido como um tópico de discussão na `freebsd-questions` do que como uma entrada no banco de dados de PRs, como discutido acima.

- Certifique-se de que ninguém tenha submetido um PR semelhante antes. Embora isso já tenha sido mencionado anteriormente, faz sentido repetir aqui. Esta verificação irá lhe tomar apenas 1 ou 2 minutos no uso do mecanismo de busca do banco de dados de PRs. (é claro, todos são culpados de já terem esquecido de fazer isso de uma vez ou outra.)

- Relate apenas um problema em cada relatório. Evite incluir dois ou mais problemas em um mesmo relatório caso eles não estejam relacionados. Quando você submeter um `patch`, evite adicionar várias funcionalidades ou corrigir vários bugs em um mesmo PR, a menos que eles sejam estritamente relacionados — Este tipo de PR muitas vezes demanda mais tempo para ser resolvido.

- Evite solicitações polêmicas. Se o seu PR está relacionado a um tema que foi polêmico no passado, você deve estar preparado para não somente disponibilizar um `patch`, como também para defender porque o seu `patch` é “a coisa certa a se fazer”. Como mencionado acima, realizar uma busca cuidadosa no histórico das listas de discussão é sempre uma boa forma de se preparar.

- Seja educado. Praticamente todas as pessoas que potencialmente podem trabalhar no seu PR são voluntários. Ninguém gosta de receber ordens para fazer algo que eles já estão fazendo por alguma outra motivação a qual não é a de ganho financeiro. Esta é uma boa coisa para ter sempre em mente num projeto de código aberto.

### 4.2. Antes de você iniciar

Antes de executar o programa send-pr(1), certifique-se que a sua variável de ambiente `VISUAL` (ou a `EDITOR` se a `VISUAL` não estiver definida) está definida com seu editor preferido.

Você também 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 relatório de problema. Se você não pode enviar mensagens de email a partir da máquina na qual está executando o send-pr(1), os seus relatórios de problema não irão chegar até a base de dados GNATS. Para maiores detalhes de como configurar o sistema de email no FreeBSD, consulte o capítulo sobre “Correio Eletrônico” no Handbook do FreeBSD.

Certifique-se de que o seu sistema de email não irá alterar a formatação da mensagem ao encaminhá-la para o GNATS. Qualquer `patch` que você enviar será inutilizado, caso o seu sistema de email quebre automaticamente as linhas, troque tabulações por espaços em branco ou altere os caracteres de mudança para uma nova linha, etc. Entretanto, para as seções de texto nós pedimos que você quebre manualmente as linhas próximo dos 70 caracteres, desta forma a versão web do PR poderá ser lida melhor.

Considerações similares se aplicam se você estiver utilizando o formulário web de submissão de PR ao invés de utilizar o send-pr(1). Observe que operações de copiar-e-colar possuem seus próprios efeitos colaterais na formatação do texto. Em certos casos, pode ser necessário usar o uuencode(1) para garantir que os patches cheguem sem modificações.

Finalmente, se a sua submissão será longa, você deve preparar o texto do seu relatório offline, desta forma nada será perdido no caso de você ter problemas quando for submetê-lo. Isto pode ser um problema, em especial, se você estiver utilizando o formulário web.

### 4.3. Anexando `patches` ou arquivos

As instruções abaixo se aplicam ao envio de PRs por email:

O programa send-pr(1) tem a capacidade de anexar arquivos em um relatório de problemas. Você pode anexar quantos arquivos desejar desde que os mesmos possuam nomes únicos (i.e. o nome próprio do arquivo, sem o caminho de diretório). Basta usar a opção `-a` na linha de comando para anexar os arquivos desejados:

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

Não se preocupe com os arquivos binários, eles serão encodados automaticamente de forma a não perturbar o seu agente de correio.

Se você anexar um `patch`, tenha certeza de utilizar a opção `-c` ou `-u` no diff(1) para criar um diff contextual ou um diff unificado (o formato unificado é preferido), e tenha certeza de especificar os números de revisão exatos dos arquivos que você modificou, desta forma o desenvolvedor que ler seu relatório terá condições de aplicá-los facilmente. Para problemas com o kernel ou com os aplicativos do sistema base, um `patch` para o FreeBSD-CURRENT (o ramo HEAD do CVS) é preferido uma vez que todo novo código deve ser aplicado e testado primeiro nele. Depois que forem realizados os testes apropriados, o código será fundido ou migrado para o ramo FreeBSD-STABLE.

Se você juntar um `patch` no corpo do email, em vez de enviá-lo como um arquivo anexo, você estará sujeito a ocorrência de um problema bastante comum ocasionado pela tendência de alguns clientes de email de converter tabs em espaços, o que irá arruinar completamente qualquer coisa que você tenha enviado com intenção de que fosse parte de um Makefile.

Não envie `patches` como anexos usando `Content-Transfer-Encoding: quoted-printable` . Isto irá realizar `character escaping` e o `patch` inteiro estará inutilizado.

Observe também que incluir pequenos `patches` em um PR é normalmente a coisa certa a se fazer — particularmente quando ele corrige o problema descrito no PR — grandes `patches` e especialmente código novo, que normalmente requerem uma revisão substancial antes de serem incorporados, devem ser colocados em um servidor web ou de FTP, e a url deve ser incluída no PR ao invés do `patch` propriamente dito. Os `patches` dentro de um email tendem a se deformar, especialmente quando o GNATS está envolvido, e quanto maior o patch, maior é a dificuldade para ambas as partes em consertá-lo. Além de que, ao colocar o `patch` na web, você pode modificá-lo sem ter que reenviar o arquivo completo como um `followup` do PR original. Além disso, os grandes `patches` simplesmente aumentam o tamanho do banco de dados, uma vez que os relatórios de problema fechados não são deletados, continuando a existir marcados como `closed`.

Você deve observar que a menos que especifique explicitamente no seu PR ou diretamente no seu patch, qualquer correção que você envie será considerada como estando licenciada sob os mesmos termos do arquivo original que você modificou.

### 4.4. Preenchendo o template

As instruções abaixo se aplicam apenas ao envio de PRs por email:

Quando você executar o programa send-pr(1), você será apresentado a um template. O template consiste em uma lista de campos, alguns dos quais estarão pré-preenchidos, e alguns irão possuir comentários explicando o seu propósito ou então listando os valores aceitáveis. Não se preocupe com os comentários, eles serão removidos automaticamente se você não modificá-los ou então os remova você mesmo.

Na parte superior do template, logo abaixo das linhas `SEND-PR:`, está o cabeçalho do email. Você normalmente não necessita modificá-lo, a menos que você esteja enviando o relatório de problema a partir de uma máquina ou de uma conta a qual pode enviar, mas não pode receber emails, neste caso você deve configurar manualmente os campos `From:` e `Reply-To:` para o seu endereço de email real. Você também pode querer enviar uma cópia do relatório para você mesmo (ou para alguma outra pessoa) através do uso de uma cópia carbono, adicionando um ou mais endereços de email na linha de cabeçalho `Cc:`.

Os campos de linha única descritos abaixo, estão disponíveis apenas no template do email:

- Submitter-Id: Não altere este campo. O valor padrão é `current-users` e está correto, mesmo se você estiver executando o FreeBSD-STABLE.

- Confidential: Não altere este campo. O valor padrão é `no`. Não tem sentido alterá-lo já que não existem relatórios de problema confidenciais no FreeBSD — o banco de dados de PR é distribuído mundialmente pelo CVSup.

- Severity: Escolha uma opção entre `non-critical`, `serious` ou `critical`. Não faça escândalo; abstenha-se de rotular seu problema como `critical` a menos que ele realmente seja (por ex. questões de corrupção de dados, grave retrocesso de funcionalidade no -CURRENT em relação a versão anterior, etc)ou de `serious` a menos que seja algo que vai afetar muitos usuários (Kernel panic ou travamentos do sistema; Problemas com algum driver de dispositivo em particular ou com utilitários de sistema). Os desenvolvedores do FreeBSD não irão necessariamente trabalhar no seu problema mais rápido se você inflar sua importância uma vez que existem muitas outras pessoas que fizeram exatamente isso — na verdade, alguns desenvolvedores prestam pouca atenção a este campo por causa disso.

  > Nota: Problemas de segurança não devem ser submetidos para o GNATS, pois todas as informações no GNATS são de conhecimento público. Por favor, envie estes problemas seguindo as nossas diretrizes sobre relatórios de segurança.

- Priority: Escolha uma opção entre `low`, `medium` ou `high`. `high` deve ser reservada para os problemas que afetam praticamente todos os usuários do FreeBSD e `medium` para os problemas que vão afetar muitos usuários.

  > Nota: Este campo tornou-se tão amplamente abusado que perdeu quase que completamente seu objetivo.

A próxima seção descreve os campos que são comuns entre a interface por email e a interface web:

- Originator: Por favor informe seu nome completo, seguido opcionalmente pelo seu endereço de email entre colchetes. Na interface de email, este campo é normalmente pré-preenchido com o campo `gecos` do usuário com o qual você está atualmente logado.

  > Nota: O endereço de email que você utilizar irá se tornar uma informação pública e pode vir a se tornar disponível para spammers. Você deverá ter um sistema antispam funcional ou então deverá utilizar uma conta temporária de email. Contudo, por favor, lembre-se que se você não utilizar uma conta de email válida, nós não seremos capazes de entrar em contato com você para fazer perguntas sobre o seu PR.

- Organization: Campo livre para o que você quiser colocar. Este campo não é utilizado para nada significativo.

- Synopsis: Preencha este campo com uma descrição curta e precisa sobre o seu problema. A `synopsis` é utilizada como o assunto do email do relatório de problema, e também é utilizada na listagem de relatório de problemas e resumos; relatórios de problema com `synopses` obscuras tendem a serem ignorados.

  Como mencionado acima, se o seu relatório de problema inclui um `patch`, por favor, inicie sua `synopsis` com `[patch]` (incluindo os colchetes); se você for um `maintainer` considere adicionar `[maintainer update]` (incluindo os colchetes) ao início da sua `synopsis` e defina a “classe” do seu PR para `maintainer-update`.

- Category: Escolha uma categoria adequada.

  A primeira coisa que você precisa fazer é decidir em qual parte do sistema o seu problema está. Lembre-se, o FreeBSD é um sistema operacional completo, o qual instala um kernel, as bibliotecas padrão, muitos `drivers` de dispositivos e um grande número de utilitários (este conjunto recebe o nome de “sistema base”). No entanto, existem milhares de aplicativos adicionais na Coleção de Ports. Você primeiro precisa decidir se o problema está no sistema base ou se está em algo que foi instalado através da Coleção de Ports.

  Aqui está uma descrição das principais categorias:

  - Se o problema é com o Kernel, com as bibliotecas (tal como a biblioteca C padrão, libc), ou com um `driver` de dispositivo do sistema base, em geral você vai usar a categoria kern. (Existem algumas exceções; veja abaixo). Em geral, estas são coisas que estão descritas nas seções 2, 3 ou 4 das páginas de manual.

  - Se o problema é com um programa binário, tal como o sh(1) ou o mount(8), primeiro você precisa determinar se estes programas pertencem ao sistema base ou se foram adicionados através da coleção de ports. Se você estiver na dúvida, você pode executar um `whereis `nomedoprograma``, no FreeBSD por convenção todos os aplicativos da coleção de ports são instalados sob `/usr/local`, embora isso possa ser alterado por um administrador de sistemas. Para estes, você irá utilizar a categoria `ports` (sim, mesmo que a categoria do port seja `www`; veja abaixo). Se a localização do aplicativo for `/bin`, `/usr/bin`, `/sbin`, ou `/usr/sbin`, ele faz parte do sistema base, e você deverá utilizar a categoria `bin`. (Alguns programas, como o gcc(1), na prática utilizam a categoria `gnu`, mas não se preocupe com isso por agora.) Todos estes aplicativos estão descritos nas seções 1 ou 8 das páginas de manual.

  - Se você acredita que o erro está no script de inicialização `(rc)`, ou em algum outro tipo de arquivo de configuração não executável, então a categoria indicada será a `conf` (configuração). Estas são coisas descritas na seção 5 das páginas de manual.

  - Se você encontrou um problema na documentação (artigos, livros, páginas de manual, etc.), a escolha correta para a categoria é a opção `docs`.

  - Se você está tendo problemas com as páginas web do FreeBSD, a escolha apropriada é `www`.

    > Nota: Independentemente se você está tendo algum problema com um port chamado `www/`nomedoport``, a categoria correta para o mesmo será `ports`.

  Existem algumas categorias mais especializadas.

  - Se o problema pode ser classificado na categoria `kern`, e está relacionado ao subsistema USB, a categoria correta será `usb`.

  - Se o problema pode ser classificado na categoria `kern`, e está relacionado com as bibliotecas de threads, a categoria correta será `threads`.

  - Se o problema está localizado no sistema base, mas está relacionado a nossa aderência a padrões tais como o POSIX®, a categoria correta será `standards`.

  - Se o problema está relacionado a erros internos de uma Java Virtual Machine™ (JVM™), mesmo que o Java™ tenha sido instalado a partir da coleção de ports, você deve selecionar a categoria `java`. Problemas genéricos com o port do Java devem continuar sendo enviados na categoria `ports`.

  Isto deixa tudo mais.

  - Se você está convencido de que o problema irá ocorrer apenas na arquitetura do processador que você está utilizando, selecione uma categoria específica para a sua arquitetura: geralmente `i386` para máquinas compatíveis com a arquitetura Intel de 32 bits, `amd64` para máquinas AMD executando em modo 64 bits (o que também inclui máquinas compatíveis com a arquitetura Intel executando em modo EMT64); e menos comumente `ia64`, `powerpc`, e `sparc64`.

    > Nota: Estas categorias são muitas vezes utilizadas de forma indevida para problemas do tipo “Eu não sei”. Em vez de tentar adivinhar, por favor, apenas utilize a categoria `misc`.

    Exemplo 1. Uso correto da categoria específica de arquitetura.

    Você tem um computador comum (PC), e acredita que encontrou um problema específico com um chipset em particular ou com uma placa mãe específica: A categoria correta é `i386`.

    Exemplo 2. Uso incorreto da categoria específica de arquitetura.

    Você está tendo problemas com uma placa de expansão instalada em um barramento bastante comum, ou um problema com um tipo específico de disco rígido: neste caso, é provável que o problema ocorra em mais de uma arquitetura, e a categoria correta seria `kern`.

  - Se você realmente não sabe onde está o problema (ou o mesmo não parece se encaixar nas categorias acima), utilize a categoria `misc`. Mas antes de fazer isto, pode ser uma boa idéia primeiro pedir ajuda na lista de discussão para perguntas gerais sobre o FreeBSD. Você poderá ser orientado à utilizar uma das outras categorias para obter um melhor resultado.

  Aqui está 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 pública do FreeBSD. Obsoleta.

  - `alpha:` problemas específicos da plataforma Alpha.

  - `amd64:` problemas específicos da plataforma AMD64.

  - `arm:` problemas específicos da plataforma ARM.

  - `bin:` problemas com os programas de nível de usuário na base do sistema.

  - `conf:` problemas com os arquivos de configuração, valores padrões, etc.

  - `docs:` problemas com as páginas de manuais ou com a documentação online.

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

  - `i386:` problemas específicos da plataforma i386™.

  - `ia64:` problemas específicos da plataforma ia64.

  - `java:` problemas relacionados com a Maquina Virtual Java.

  - `kern:` problemas com o kernel, drivers de dispositivo (não específicos à uma plataforma), ou bibliotecas do sistema base.

  - `misc:` Tudo aquilo que não se encaixa numa das outras categorias. (observe que não existe nada que pertença verdadeiramente a esta categoria, exceto os problemas com a infra estrutura de build e de release. As falhas temporárias de compilação do `HEAD` não pertencem a esta categoria. Também observe que é fácil para as coisas se perderem nesta categoria).

  - `ports:` problemas relacionados com a Coleção de Ports.

  - `powerpc:` problemas específicos da plataforma PowerPC®.

  - `sparc64:` problemas específicos da plataforma SPARC64®.

  - `standards:` problemas relacionados a conformidade com os padrões.

  - `threads:` problemas relacionados a implementação de threads no FreeBSD (especialmente no FreeBSD-CURRENT).

  - `usb:` problemas relacionados a implementação do USB no FreeBSD.

  - `www:` mudanças e melhorias no web site do FreeBSD.

- Class: Escolha uma das seguintes opções:

  - `sw-bug:` bugs de software.

  - `doc-bug:` erros na documentação.

  - `change-request:` solicitação de novas funcionalidades ou de alterações em funcionalidades existentes.

  - `update:` atualizações para o ports ou para outros softwares de terceiros.

  - `maintainer-update:` atualizações de ports pelos quais você é o responsável.

- Release: É a versão do FreeBSD que você está utilizando. Este campo é preenchido automaticamente pelo send-pr(1) e só necessita ser alterado se você estiver enviando o relatório de problema de um sistema diferente do que apresenta o problema.

Finalmente, há uma série de campos de várias linhas:

- Environment: Este campo deve descrever, da forma mais precisa possível, o ambiente no qual o problema foi observado. Isto inclui a versão do sistema operacional, a versão do programa ou do arquivo específico que contém o problema, e qualquer outro item relevante tal como a configuração do sistema, outros softwares instalados que tenham influência no problema, etc. — ou seja, simplesmente tudo o que um desenvolvedor precisar saber para reconstruir o ambiente no qual o problema ocorreu.

- Description: Uma descrição precisa e completa do problema que você esta experimentando. Tente evitar especular sobre as causas do problema a menos que você tenha certeza de que está no caminho certo, do contrário você pode induzir o desenvolvedor a fazer suposições incorretas sobre o problema.

- How-To-Repeat: Um resumo com as ações que você precisa executar para reproduzir o problema.

- Fix: Preferencialmente um `patch`, ou no mínimo um `workaround` (o que não só ajuda as outras pessoas que estão com o mesmo problema, como também auxilia o desenvolvedor a entender melhor a causa do problema), mas se você não tem nenhuma idéia consistente, é melhor deixar este campo em branco do que especular.

### 4.5. Enviando o relatório de problemas

Se você está utilizando o send-pr(1):

Uma vez que você tenha terminado de preencher o template, salve-o, e saia do editor de texto, ao fazer isto o send-pr(1) irá lhe perguntar se você deseja `s)end, e)dit or a)bort?`. Para ir em frente e enviar o relatório de problema pressione `s`, caso você queira voltar ao editor para realizar alguma alteração pressione `e`, ou então pressione `a` para cancelar o envio. Se você optar por abortar, o seu relatório de problema irá permanecer no seu disco rígido (o send-pr(1) irá lhe informar o nome do arquivo antes de finalizar), assim você poderá editá-lo quando for mais conveniente, ou poderá transferi-lo para um sistema com uma melhor conectividade, no qual poderá enviá-lo usando a opção `-f` com o send-pr(1):

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

Este comando irá ler o arquivo especificado, validar o seu conteúdo, remover os comentários e enviar o seu PR.

Se você está utilizando o formulário web:

Antes de pressionar o botão `submit` para enviar o seu relatório, você terá que preencher um campo com o texto exibido na imagem de captcha exibida no final do formulário. Infelizmente esta medida teve de ser adotada devido ao mau uso do mesmo por sistemas automatizados e por alguns indivíduos mal intencionados. É um mal necessário do qual ninguém gosta. Por favor, não peça para removê-lo.

Recomendamos fortemente que você salve o seu trabalho em algum outro lugar antes de pressionar o botão `submit`. Um problema comum e que ocorre com muitos usuários é a visualização de uma imagem de captcha velha exibida a partir do cache do navegador. Se isso acontecer com você o seu envio será rejeitado e você poderá perder o seu trabalho.

Se você, por qualquer motivo, não conseguir visualizar as imagens, e também estiver impossibilitado de utilizar o send-pr(1), por favor, aceite nossas desculpas por está inconveniência e envie seu relatório de problema por e-mail para a equipe de bugbusters do FreeBSD, no endereço `<freebsd-bugbusters@FreeBSD.org>`.

## 5. Acompanhamento

Depois que seu relatório de problema tiver sido entregue, você receberá uma confirmação por e-mail com o número de rastreamento que foi atribuído ao mesmo e uma URL a qual você poderá utilizar para consultar o status do seu PR. Com um pouco de sorte, alguém irá se interessar pelo seu problema e tentará resolvê-lo, ou, conforme o caso explicar porque não se trata de um problema. Você será notificado automaticamente de qualquer mudança de status, e irá receber uma cópia de qualquer comentário ou correção que alguém venha a anexar à trilha de auditoria do seu relatório de problema.

Se alguém lhe requisitar alguma informação adicional, ou se você lembrar de algo ou descobrir algo que você não tenha mencionado no seu relatório inicial, por favor utilize um dos dois métodos abaixo para enviar uma atualização:

- A forma mais fácil é utilizar o link e `followup` existente na página web individual de cada PR, a qual pode ser encontrada a partir da página de busca de relatórios. Ao clicar no link será aberta uma janela do seu cliente de e-mail com os campos `To:` e `Subject:` já corretamente preenchidos (se o seu navegador estiver configurado corretamente para fazer isto).

- Alternativamente, você pode apenas enviá-lo para `<bug-followup@FreeBSD.org>`, certificando-se de que o número de rastreamento está incluso no `Subject:` de forma que o sistema de acompanhamento de bugs tenha como saber em qual relatório de problema ele deve anexar o material recebido.

  > Nota: Se você não incluir o número de rastreamento, o GNATS irá se confundir e criará um relatório de problema completamente novo, o qual será atribuído ao administrador do GNATS, e então o seu `followup` irá ficar perdido até que alguém tenha tempo de arrumar a bagunça, o que pode levar dias e até mesmo semanas para ocorrer.

  > Forma errada:

  >     Subject: Sobre o PR que eu enviei

  > Forma correta:

  >     Subject: Re: ports/12345: problemas de compilação do foo/bar

Se o relatório de problema permanecer aberto depois que o problema já tiver sido resolvido, basta enviar um follow-up (da forma descrita acima) informando que o PR pode ser fechado, e se possível, explicando como e quando o problema foi corrigido.

## 6. Se você está tendo problemas

A maioria dos PRs que chegam ao sistema é processada rapidamente; entretanto em alguns momentos o GNATS fica lento e você pode não receber o seu email de confirmação de imediato, levando 10 minutos ou mesmo um pouco mais para recebê-lo. Por favor, tente ser paciente.

Além disso, uma vez que o GNATS recebe tudo por email, é absolutamente vital que o FreeBSD processe todas as mensagens que chegam utilizando filtros antispam. Se você não receber o email de confirmação em até duas horas, você pode ter sido barrado por este sistema; Neste caso, por favor, entre em contato com o adminisrador do GNATS no endereço `<bugmeister@FreeBSD.org>` e peça ajuda.

> Nota: Dentre as medidas antispam que utilizamos existe uma a qual verifica a aderência da sua mensagem em relação a uma série de abusos comums em emails baseados em HTML (embora o sistema não necessariamente invalide uma mensagem devido a mera inclusão de código HTML no PR). Recomendamos fortemente que você evite utilizar emails no formato HTML quando estiver enviando um PR: Não apenas é provável que a sua mensagem seja bloqueada pelos filtros, como ela também irá prejudicar o banco de dados. O bom e velho email em texto puro é fortemente preferido.

Em raras ocasiões você irá se deparar com um bug do GNATS pelo qual um PR será aceito, receberá um número de rastreamento, mas não irá aparecer na lista de PRs em nenhuma consulta realizada no web site. O que pode ter ocorrido é que o índice do banco de dados ficou fora de sincronia com o próprio banco de dados. Uma forma de testar se é isto que esta acontecendo com você é acessar um PR individual qualquer listado a partir do formulário 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 endereço `<bugmeister@FreeBSD.org>`. Observe que existe uma tarefa agendada no `cron` que reconstrói periodicamente o banco de dados, de forma que a menos que você esteja com pressa, nenhuma ação será necessária.

## 7. Leituras complementares

Esta é uma lista com material de referência recomendado sobre boas práticas para se escrever e processar um relatório de problema. Esta lista não tem por objetivo ser uma lista completa.

- Como reportar bugs de forma efetiva— Um excelente ensaio por Simon G. Tatham sobre a elaboração de relatórios de problemas eficientes (não é especifico sobre o FreeBSD).

- Guia de como lidar com relatórios de problemas — Uma percepção valiosa sobre como os desenvolvedores do FreeBSD devem lidar com os relatórios de problemas.

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

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.
Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.