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, 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 “™” or the “®” symbol.
Este artigo descreve qual a melhor forma de formular e de submeter um relatório de problema para Projeto FreeBSD.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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>.
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.
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.
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.
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.
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.