Escrevendo relatórios de problema no FreeBSD

---

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

• Não deixe a linha de sinópse em branco. Os PRs são enviados para listas de discussão no mundo todo (nas quais a Sinópse é 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 sinópses, e encontrar um PR com a linha de assunto em branco, tende a pulá-lo. Lembre-se que os PRs permanencem na base de dados até que sejam fechados por alguém; os anônimos normalmente irão desaparecer em meio ao ruido.

• Evite utilizar uma sinópse fraca. Você não pode assumir que alguém que esteja lendo o seu PR conheça todo o contexto que que gerou o seu envio, assim quanto mais você fornecer, melhor. Por exemplo, a que parte do sistema o problema se aplica? Você vê o problema apenas ao instalar ou ao executar? Para ilustrar, ao invés de Synopsis: o portupgrade está quebrado, veja o quão mais informativo é este outro exemplo: 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 sinópse.)

• Se você possui um patch, mencione-o. Um PR que inclui um patch é muito mais provável de ser olhado do que um sem. Se você estiver incluindo um, coloque a palavra [patch] no inicio da linha de sinópse. (Embora não seja obrigátorio utilizar esta palavra exata, por convenção, é ela que é utilizada.)

• Se você é um maintainer, 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] no inicio da linha de sinópse e/ou definir a classe do seu PR para maintainer-update. Desta forma qualquer committer que manusear o seu PR não terá de verificar com o Makefile do PR cada vez que um PR for visto, para ter certeza que a atualização foi enviada pelo maintainer do port.

• Seja específico. Quanto mais informações você enviar sobre o problema que você está tendo, melhor é a sua chance de obter uma resposta. Você deve incluir items tais como a versão você está executando (Existe um lugar para colocar isso, veja abaixo); qual a arquitetura que você está utilizando; se você está utilizando uma versão release obtida apartir de um CDROM, ou se está utilizando um sistema mantido pelo cvsup(1) (e, se for o caso, o quão recentemente ele foi atualizado); e, se se for um problema de kernel, se você leu o arquivo src/UPDATING (com certeza alguém iria perguntar). Você não tem que necessariamente fornecer a sua configuração do kernel, que ports você tem instalado, e um arquivo de coredump (inclui-los por padrão, apenas iria encher o banco de dados), mas você deve ficar preparado para disponibilizá-lo, de forma privada ou pública, se ele for solicitado.

• Evite pedidos vagos de novas funcionalidades. Os PRs no formato alguém deve realmente implementar algo que faça isso ou aquilo  são menos prováveis de obeterem uma resposta que os que são mais especificos. Lembre-se, o código está disponivel para todos, de forma que se você deseja uma nova funcionalidade, a melhor maneira de ter certeza de que ela será incluida é começar a trabalhar! Também considere o fato de que muitas coisas estariam melhores como um tópico melhor de discussão na freebsd-questions do que como uma entrada no banco de dados de PRs, como discutido acima.

• Tenha certeza que que ninguém já tenha enviando um PR semelhante. Embora isso já tenha sido mencionado anteriormente, cabe repetir aqui. Isto irá tomar apenas 1 ou 2 minutos no uso do mecanismo de busca da interface web do banco de dados de PRs. (é claro, todos são culpados de esquecerem de fazer isso de vez em quando.)

• Evite solicitações controversas. Se o seu PR se relaciona a uma area que foi controversa no passado, você deve estar preparado para oferecer não só apenas os patches, mas também a justificativa de porque os patches são a coisa certa a se fazer. Como mencionado acima, uma busca cuidadosa nos arquivos das listas de discussão é sempre um bom preparativo.

• Seja educado. Quase todas as pessoas que potencialmente podem trabalhar no seu PR são voluntários. Ninguém gosta que seja dito que eles devem 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), tenha certeza que a sua variável de ambiente VISUAL (ou a EDITOR se a VISUAL não estiver definida) está setada para alguma coisa sensivel.

Você também deve se certificar de que o sistema de entrega de emails esteja funcionando corretamente. O send-pr(1) utiliza mensagens de email para enviar e rastrear um relatório de problemas. Se você não pode enviar mensagens de email apartir da máquina onde está executando o send-pr(1), os seus relatórios de problemas 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  Correio Eletrônico no Handbook do FreeBSD.

---

4.3. Anexando pachs ou arquivos

O programa send-pr(1) tem a capacidade de anexar arquivos a um relatório de problema. Você pode anexar tantos arquivos quantos você desejar, desde que cada um possua um nome único. (por ex. por exemplo o nome próprio do arquivo, sem o caminho de diretório). Basta utilizar a opção de linha de comando -a para especificar os nomes dos arquivos que você deseja anexar:

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

Não se preocupe com os arquivos binários, eles serão automaticamente codificados de forma a não interferir com 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, de forma que o desenvolvedor que ler o seu relatório tenha condições de aplica-las facilmente. Um patch para o ramo CURRENT ou HEAD do cvs é preferido uma vez que todo código novo deve ser aplicado e testado ali primeiro. Após a realização de testes apropriados e significativos, o código será combinado/migrado para ao ramo STABLE.

Se você juntar um patch no corpo do email, em vez envia-lo como um arquivo anexo, você pode ficar sujeito a ocorrência de um problema bastante comum ocasionado pela tendência de alguns programas de email de converter tabs em espaços, o qual irá arruinar completamente qualquer coisa cuja intenção é a de ser parte de um Makefile.

Observe também que incluir pequenos patchs em um PR é normalmente a coisa certa -- 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 ser incorporado, devem ser colocados em um servidor web ou de FTP, e a url deve ser incluida no PR ao invés do pacth propriamente dito. Os patches dentro de um email tendem a se deformar, especialmente quando GNATS está envolvido, e em um grande patch, maior será a dificulade dos interessados em consertá-lo. Além de que, ao colocar o patch na web você pode modificá-lo sem ter a necessidade de reenviar o patch completo em uma continuação do PR original.

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

---

4.4. Preenchendo o template

Quando você executa 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 moficicá-los ou retirá-los 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 apartir 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: .

Em seguida vem uma série de campos de uma unica linha:

• Submitter-Id: Não mude isto. O valor default current-users está correto, inclusive se você estiver utilizando o FreeBSD-STABLE.

• Originator: Este campo normalmente é preenchido automaticamente com as informações do campo gecos com as informações do usuário que está atualmente executando o comando. Por favor especifique o seu nome e opcionalemente o seu endereço de email entre símbolo de maior-menor.

• Organization: Coloque qualquer coisa que desejar. Este campo não é utilizado para nada relevante.

• Confidential: Este campo é pré preenchido com a opção no (não). Alterar está opção não faz muito sentido uma vez que não existem relatorios de problema confidenciais no FreeBSD; o banco de dados de PRs é replicado pelo mundo todo através do CVSup.

• Synopsis: Preenha este campo com uma descrição curta e precisa do problema. A sinópse é utilizada como assunto no email do relatório de problema, e é utilizada na lista de relatórios de problemas e nos sumários; relatórios de problema com sinópse obscuras tendem a ser ignorados.

  Como mencionado acima, se o seu relatório de problema inclui um patch, por favor inicie sua sinópse com [patch]; se você for um maintainer considere adicionar [maintainer update] ao início da sua sinópse e/ou definir a Classe do seu PR para maintainer-update.

• Severity: Escolha uma opção entre non-critical, serious ou critical. Não reaja de forma exagerada; controle-se para não classificar seu problema como critical a menos que ele realmente seja (por ex. root exploit, panic facilmente reproduzivel, etc). Os desenvolvedores tendem a ignorar este e o próximo campo, justamente porque os usuários tendem a exagerar na prioridade dos seus problemas.

• Priority: Escolha uma opção entre low, medium ou high. Considere os comentários do campo anterior.

• Category: Escolha uma entre as seguintes:

  • advocacy: problemas relacionados a imagem pública do FreeBSD. Raramente é utilizado.

  • alpha: problemas específicos da plataforma Alpha.

  • amd64: problemas específicos da plataforma AMD64.

  • 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) or grep(1).

  • i386: problemas específicos da plataforma i386".

  • ia64: problemas específicos da plataforma ia64.

  • java: problemas relacionados com a tecnologia Java".

  • kern: problemas com o kernel.

  • misc: Tudo aquilo que não se encaixou numa das outras categorias. (Observe que é facil para as coisas se perderem nesta categoria).

  • ports: problemas relacionados a árvore de ports.

  • powerpc: problemas específicos da plataforma PowerPC®.

  • sparc64: problemas específicos da plataforma Sparc64®.

  • standards: assuntos relacionados com a conformidade com os padrões.

  • www: alterações ou melhorias ao website do FreeBSD.

• Class: Escolha uma opção entre as seguintes:

  • 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ção de um port para o qual você é o maintainer.

• 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 apartir de um sistema , que não o que apresenta o problema.

Finalmente, existe uma série de campos com multiplas linhas:

• Environment: Este campo deve descrever, da forma mais precisa possivel, o ambiente no qual o problema foi observado. Isto inclui a versão do sistema operacional, a versão do programa ou do arquivo especifico que contém o problema, e qualquer outro item relevante para 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 seguir na direção errada.

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

• Fix: Preferencialmente um patch, ou no minimo um contorno (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 sólida, é melhor deixar este campo em branco do que especular.

---

4.5. Enviando o relatório de problemas

Uma vez que você tenha preenchido o template, salve-o, e saia do editor de texto, ao fazer isso o send-pr(1) irá perguntar de você deseja s)end, e)dit or a)bort?. Você pode pressionar s para continuar e enviar o relatório de problema, e para voltar ao editor de forma que possa efetuar alguma alteração, ou então a para cancelar o envio. Se você escolher a opção later (mais tarde), o seu relatório de problema irá permanecer no seu disco (o send-pr(1) irá lhe dizer o nome do arquivo antes de terminar), assim você pode editá-lo quando tiver mais tempo, ou pode transferi-lo para um sistema com uma melhor conectividade, antes de enviá-lo com a opção -f do 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 enviá-lo.