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.

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:

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

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

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 .

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 <[email protected]>.
Para perguntas sobre esta documentação, envie e-mail para <[email protected]>.