---
authors:
  - 
    author: 'Dag-Erling Smørgrav'
  - 
    author: 'Mark Linimon'
description: 'Como melhor formular e enviar um relatório de problema para o Projeto FreeBSD'
tags: ["formulate", "submit", "FreeBSD", "PR"]
title: 'Escrevendo Relatórios de Problemas para o FreeBSD'
trademarks: ["freebsd", "ibm", "intel", "sun", "general"]
---

= Escrevendo Relatórios de Problemas para o FreeBSD
:doctype: article
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:images-path: articles/problem-reports/

ifdef::env-beastie[]
ifdef::backend-html5[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
:imagesdir: ../../../images/{images-path}
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[.abstract-title]
Resumo

Este artigo descreve como redigir e submeter um bom relatório de problemas ao Projeto FreeBSD.

'''

toc::[]

[[pr-intro]]
== Introdução

Uma das experiências mais frustrantes que alguém pode ter como usuário de um software é submeter um relatório de problema apenas para vê-lo ser encerrado sumariamente com uma explicação curta e inútil tal como "não é um bug" ou "PR Falso". Da mesma forma, uma das experiências mais frustrantes como desenvolvedor de software é ser inundado com relatórios de problemas que não são realmente relatórios de problemas mas sim pedidos de suporte, ou então por relatórios que contêm pouca ou nenhuma informação sobre o que é o problema e sobre como reproduzi-lo.

Este documento tenta descrever como escrever bons relatórios de problemas. O que, alguém pergunta, é um bom relatório de problemas? Bem, para ir diretamente para ao ponto, um bom relatório de problema é aquele que pode ser analisado e tratado rapidamente, para a satisfação mútua do usuário e do desenvolvedor.

Embora o foco principal deste artigo esteja nos relatórios de problemas do FreeBSD, a maioria das recomendações deve se aplicar muito bem a outros projetos de software.

Observe que este artigo é organizado por temas, não de uma forma cronológica. Leia todo o documento antes de enviar um relatório de problemas, em vez de tratá-lo como um tutorial passo a passo.

[[pr-when]]
== Quando Enviar um Relatório de Problemas

Existem muitos tipos de problemas, e nem todos devem gerar um relatório de problemas. Naturalmente, ninguém é perfeito, e haverá momentos em que o que parece ser um bug em um programa é, na verdade, um equívoco na sintaxe de um comando ou um erro tipográfico em um arquivo de configuração (embora isto por si só possa ser um indicativo de uma documentação deficiente ou de deficiências no manuseio de erros pelo aplicativo). Existem ainda muitos casos em que submeter um relatório de problema claramente _não_ é o curso de ação correto, e só servirá para frustrar tanto o usuário e quanto o desenvolvedor. Por outro lado, existem casos em que pode ser apropriado enviar um relatório de problema sobre algo diferente de um bug - tal como um aprimoramento ou um novo recurso, por exemplo.

Então, como se determina o que é um bug e o que não é? Como uma regra simples, o problema _não_ é um bug se ele puder ser expresso como uma pergunta (geralmente na forma "Como faço X?" ou "Onde posso encontrar Y?"). Nem sempre é tão preto e branco, mas a regra da pergunta cobre a grande maioria dos casos. Ao procurar por uma resposta, considere colocar a questão na {freebsd-questions}.

Considere estes fatores ao enviar PRs sobre ports ou outros softwares que não fazem parte do próprio FreeBSD:

* Por favor, não envie relatórios de problemas que simplesmente afirmam que uma versão mais nova de um aplicativo está disponível. Os mantenedores de ports são notificados automaticamente pelo portscout quando uma nova versão de um aplicativo fica disponível. Patches para atualizar um port para uma versão mais recente do software são sempre bem-vindos.
* Para ports não mantidos (O seu `MAINTAINER` é `ports@FreeBSD.org`), é improvável que um PR que não tenha um patch incluído seja escolhido para ser trabalhado por um committer. Para se tornar o mantenedor de um port não mantido, envie um PR com o pedido (será ótimo se o pedido vier com um patch, mas isso não é obrigatório).
* Em ambos os casos, seguir o processo descrito no extref:{porters-handbook}upgrading/[Porter's Handbook] produzirá os melhores resultados. (Você também pode desejar ler a seção extref:{contributing}[Contribuindo para a Coleção de Ports do FreeBSD, ports-contributing].)

Um bug que não pode ser reproduzido raramente pode ser corrigido. Se o bug ocorreu apenas uma vez e você não pode reproduzi-lo, e não parece acontecer com mais ninguém, é muito provável que nenhum dos desenvolvedores consiga reproduzi-lo ou descobrir o que está errado. Isso não significa que isso não tenha acontecido, mas significa que as chances do seu relatório de problema levar à correção do bug são muito pequenas. Para piorar, muitas vezes esses tipos de bugs são causados por discos rígidos com defeito ou por processadores superaquecidos - sempre que possível você deve tentar descartar essas causas antes de enviar um PR.

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

* Código no sistema base que é escrito e mantido por contribuidores do FreeBSD, como o kernel, a biblioteca C e os drivers de dispositivo (categorizados como `kern`); os utilitários binários (`bin`); as páginas de manual e documentação (`docs`); e as páginas web (`www`). Todos os erros nestas áreas devem ser reportados aos desenvolvedores do FreeBSD.
* Código no sistema base que é escrito e mantido por outras pessoas, o qual é importado e adaptado para o FreeBSD. Exemplos incluem o man:clang[1] e o man:sendmail[8]. A maioria dos bugs nessas áreas deve ser reportada aos desenvolvedores do FreeBSD; mas em alguns casos eles podem precisar ser relatados aos autores originais se os problemas não forem específicos do FreeBSD.
* Aplicativos individuais que não estão no sistema base, mas que são parte da coleção de ports do FreeBSD (categoria `ports`). A maioria desses aplicativos não são escritos por desenvolvedores do FreeBSD; o que o FreeBSD fornece é meramente um framework para instalar o aplicativo. Portanto, apenas relate um problema para os desenvolvedores do FreeBSD quando o problema for considerado específico do FreeBSD; caso contrário, informe aos autores do software.

Em seguida, verifique se o problema é oportuno. Há poucas coisas que incomodarão mais um desenvolvedor do que receber um relatório de problemas sobre um bug que ele já corrigiu.

Se o problema estiver no sistema base, primeiro leia a seção extref:{faq}[Versões do FreeBSD, latest-version] do FAQ, se você ainda não estiver familiarizado com o tópico. Não é possível para o FreeBSD consertar problemas em nada além de certas branches recentes do sistema base, de forma que enviar um relatório de bug sobre uma versão mais antiga provavelmente resultará em um desenvolvedor aconselhando você a atualizar para uma versão suportada para ver se o problema ainda continua ocorrendo. A equipe Security Officer mantém a link:https://www.FreeBSD.org/security/[lista das versões suportadas].

Se o problema estiver em um port, considere submeter o bug para o upstream. O Projeto FreeBSD não pode corrigir todos os erros em todos os softwares.

[[pr-prep]]
== Preparativos

Uma boa regra a seguir é sempre fazer uma pesquisa sobre o tema antes de enviar um relatório de problemas. Talvez o problema já tenha sido relatado anteriormente; talvez esteja sendo discutido nas listas de discussão, ou foi discutido recentemente; pode até mesmo já estar corrigido em uma versão mais recente da que você está executando. Portanto, você deve verificar todos os lugares óbvios antes de enviar seu relatório de problemas. Para o FreeBSD, isso significa:

* A lista das extref:{faq}[Perguntas Mais Frequentes] (FAQ) sobre o FreeBSD. A FAQ tenta fornecer respostas para uma ampla variedade de perguntas, como aquelas relacionadas à extref:{faq}[compatibilidade de hardware, hardware], extref:{faq}[aplicativos de usuário, applications], e extref:{faq}[configuração do kernel, kernelconfig].
* As extref:{handbook}[listas de discussões, eresources-mail] - se você não está inscrito, faça uma pesquisa nos arquivos https://www.FreeBSD.org/search/#mailinglists[históricos das listas] no site do FreeBSD. Se o problema não tiver sido discutido nas listas, você pode tentar postar uma mensagem sobre ele e aguardar alguns dias para ver se alguém consegue detectar algo que foi esquecido.
* Opcionalmente, na web toda - use seu mecanismo de pesquisa favorito para localizar qualquer referência ao problema. Você pode até receber hits de listas de discussão arquivadas ou grupos de notícias que você não conhecia ou que não pensou em pesquisar.
* Em seguida, faça uma pesquisa no https://bugs.freebsd.org/bugzilla/query.cgi[banco de dados de Relatórios de Problemas do FreeBSD] (Bugzilla). A menos que o problema seja recente ou obscuro, há uma boa chance de que ele já tenha sido relatado.
* Mais importante ainda, tente verificar se a documentação existente não endereça o seu problema.
+
Para o código fonte do FreeBSD, você deve estudar cuidadosamente o conteúdo do [.filename]#/usr/src/UPDATING# em seu sistema ou a última versão disponível em https://cgit.freebsd.org/src/tree/UPDATING[https://cgit.freebsd.org/src/tree/UPDATING]. (Esta é uma informação vital se você estiver atualizando de uma versão para outra - especialmente se você estiver atualizando para a branch FreeBSD-CURRENT).
+
No entanto, se o problema estiver em algo que foi instalado como parte da coleção de ports do FreeBSD, você deve consultar [.filename]#/usr/ports/UPDATING# (para ports individuais) ou [.filename]#/usr/ports/CHANGES# (para alterações que afetam toda a Coleção de Ports).O https://cgit.freebsd.org/ports/tree/UPDATING[https://cgit.freebsd.org/ports/tree/UPDATING] e o https://cgit.freebsd.org/ports/tree/CHANGES[https://cgit.freebsd.org/ports/tree/CHANGES] também estão disponíveis via cgit.

[[pr-writing]]
== Escrevendo o Relatório do Problema

Agora que você decidiu que seu problema merece um relatório de problema e que ele é um problema especifico do FreeBSD, é hora de escrever o relatório de problema. Antes de entrarmos na mecânica do sistema utilizado para gerar e enviar os PRs, aqui estão algumas dicas e truques para ajudar a garantir que seu o PR seja mais eficaz.

[[pr-writing-tips]]
== Dicas e Truques para Escrever um Bom Relatório de Problemas

* _Não deixe a linha "Summary" vazia._ Os PRs são enviados para listas de discussão no mundo todo (onde o "Summary" é usado para a linha de `Subject:`), além de serem armazenadas 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 usar um "Summary" (Sumário) fraco._ Você não deve presumir que alguém que esteja lendo seu PR conheça o contexto que motivou o seu envio, desta forma, quanto mais informação você fornecer, melhor. Por exemplo, em qual parte do sistema o problema se aplica? O problema ocorre durante a instalação ou durante a execução do sistema? Para ilustrar, em vez de usar `Summary: o portupgrade está quebrado`, veja o quanto mais informativo isso parece: ` Summary: port ports-mgmt/portupgrade gerando coredumps no -current`. (No caso de um port, é especialmente útil ter tanto o nome da categoria quanto o nome do port na linha "Summary".)
* _Se você tem um patch, mencione-o._ Um PR com um patch incluído é muito mais provável de ser analisado do que um sem. Por favor, inclua a palavra-chave `patch` no Bugzilla.
* _Se você é um mantenedor, informe._ Se você está mantendo uma parte do código fonte (por exemplo, um port existente), você deve definir o campo "Class" do seu PR para `maintainer-update`. Desta forma, qualquer committer que veja o seu PR não terá que verificar.
* _Seja específico._ Quanto mais informações você fornecer sobre o problema que está tendo, maiores serão suas chances de obter uma resposta.

** Inclua a versão do FreeBSD que você está utilizando (há um lugar para colocar essa informação, veja abaixo) e em qual arquitetura. Você deve incluir se você está executando a partir de uma release (por exemplo, de um CD-ROM ou feito um download), ou de um sistema mantido pelo Git (e, caso seja afirmativo, em que hash e branch você está). Se você estiver utilizando a branch FreeBSD-CURRENT, essa é a primeira coisa que alguém vai perguntar, porque as correções (especialmente para problemas de alto nível) tendem a ser realizadas muito rapidamente, e é esperado que usuários do FreeBSD-CURRENT se mantenham atualizados.
** Inclua quais opções globais você especificou em seu [.filename]#make.conf#, [.filename]#src.conf# e [.filename]#src-env.conf#. Dado o número infinito de opções, nem todas as combinações podem ser totalmente suportadas.
** Se o problema puder ser reproduzido facilmente, inclua informações que irão ajudar um desenvolvedor a reproduzi-lo. Se um problema puder ser demonstrado com uma entrada específica, então inclua um exemplo desta entrada se possível, e inclua tanto a saída real quanto a esperada. Se esses dados forem grandes ou não puderem ser tornados públicos, então tente criar um arquivo pequeno que exiba o mesmo problema e que possa ser incluído no PR.
** Se este for um problema do kernel, esteja preparado para fornecer as seguintes informações. (Você não precisa incluí-las por padrão, o que apenas tende a preencher o banco de dados, mas você deve incluir os trechos que considera ser relevantes):

*** sua configuração do kernel (incluindo quais dispositivos de hardware você tem instalado)
*** independente de você ter ou não opções de debug habilitadas (como `WITNESS`), e se tiver, se o problema persiste quando você muda o sentido da opção
*** o texto completo de qualquer backtrace, panic ou outra mensagens de console, ou registros em [.filename]#/var/log/messages#, se houver sido gerado
*** a saída de `pciconf -l` e partes relevantes da saída do comando `dmesg` se o seu problema estiver relacionado a uma peça específica de hardware
*** o fato de você ter lido [.filename]#src/UPDATING# e o seu problema não estar listado lá (alguém pode perguntar)
*** independente de você poder executar qualquer outro kernel como um fallback (isso é para descartar problemas relacionados a hardware, como discos com falhas e CPUs superaquecidas, que podem se passar por problemas de kernel)

** Se este for um problema de algum port, esteja preparado para fornecer as seguintes informações. (Você não precisa incluí-las por padrão, o que apenas tende a preencher o banco de dados, mas você deve incluir trechos que você considera relevantes):

*** quais ports você instalou
*** quaisquer variáveis de ambiente que sobreescrevem as variáveis padrões em [.filename]#bsd.port.mk#, assim como `PORTSDIR`
*** o fato de você ter lido [.filename]#ports/UPDATING# e o seu problema não estar listado lá (é garantido que alguém irá perguntar)

* _Evite requisições vagas de novas funcionalidades._ Os PRs no formato "alguém realmente deve implementar algo que faz isso e aquilo" têm menor probabilidade de obter resultados do que requisições muito específicas. Lembre-se, o código fonte está disponível para todos, então se você quiser uma nova funcionalidade, a melhor maneira de garantir que ela seja incluída é começar a trabalhar! Considere também o fato de que muitas coisas como essa seriam um tópico melhor para a discussão sobre `freebsd-questions` do que uma entrada no banco de dados de PR, como discutido acima.
* _Certifique-se de que ninguém mais tenha submetido um PR similar._ Embora isso já tenha sido mencionado acima, vale a pena repetir aqui. Leva apenas um ou dois minutos para usar o mecanismo de busca baseado na Web em https://bugs.freebsd.org/bugzilla/query.cgi[https://bugs.freebsd.org/bugzilla/query.cgi]. (Claro, todo mundo é culpado de esquecer de fazer isso de vez em quando.)
* _ Relate um problema apenas através do Relatório de Problemas._ Evite incluir dois ou mais problemas dentro do mesmo relatório, a menos que estejam relacionados. Ao enviar patches, evite adicionar várias funcionalidades ou corrigir múltiplos bugs no mesmo PR, a menos que eles estejam intimamente relacionados - esses PRs geralmente levam mais tempo para serem resolvidos.
* _Evite requisições controversas._ Se o seu PR aborda uma área que já foi controversa no passado, você provavelmente deverá estar preparado para não apenas oferecer patches, mas também justificar por que os patches são "A Coisa Certa A Se Fazer ". Como observado acima, uma busca cuidadosa nas listas de discussão usando os arquivos em https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists] é sempre uma boa preparação.
* _Seja educado._ Quase todo mundo que potencialmente irá trabalhar em seu PR é um voluntário. Ninguém gosta que digam o que eles tem que fazer quando já estão fazendo por alguma motivação que não seja o ganho monetário. É sempre bom ter isso em mente em projetos de código aberto.

[[pr-writing-before-beginning]]
== Antes de Começar

Considerações semelhantes se aplicam ao uso do https://bugs.freebsd.org/bugzilla/enter_bug.cgi[formulário web de envio de PR]. Cuidado com as operações de recortar e colar que podem alterar o espaços em branco ou outras formatações de texto.

Finalmente, se o envio for demorado, prepare o trabalho off-line para que nada seja perdido se houver um problema ao enviá-lo.

[[pr-writing-attaching-patches]]
== Anexando Patches ou Arquivos

Em geral, recomendamos usar `git format-patch` para gerar um ou uma série de diffs unificados em relação ao branch base (por exemplo, `origin/main`). Os patches gerados dessa forma incluirão os hashes do Git e incluirão seu nome e endereço de e-mail, tornando mais fácil para os committers aplicarem seu patch e creditarem você como autor (usando `git am`). Para pequenas alterações em que você prefere não usar o git, certifique-se de usar man:diff[1] com a opção `-u` para criar um diff unificado, pois isso daria aos desenvolvedores mais contexto e seria mais legível do que outros formatos de diff.

Para problemas com o kernel ou com os utilitários da base, um patch para o FreeBSD-CURRENT (o principal branch do Git) é o preferido, já que todo código novo deve ser aplicado e testado lá primeiro. Após testes apropriados ou substanciais terem sido feitos, o código será mesclado/migrado para a branch FreeBSD-STABLE.

Se você anexar um patch inline, em vez de um anexo, observe que o problema mais comum, de longe, é a tendência de alguns programas de email renderizar tabs como espaços, o que ira arruinar completamente qualquer coisa destinada a fazer parte de um Makefile.

Não envie patches como anexos usando `Content-Transfer-Encoding: quoted-printable`. Isso irá escapar os caracteres e todo o patch se tornará inútil.

Observe também que, embora a inclusão de pequenos patches em um PR geralmente esteja correto - particularmente quando eles corrigem o problema descrito no PR - patches grandes e especialmente códigos novos que podem exigir uma revisão substancial antes do commit, deveriam ser colocados em um servidor web ou FTP, e a URL deveria ser incluída no PR em vez do patch. Patches por e-mail tendem a ficar embaralhados, e quanto maior o patch, mais difícil será para as partes interessadas recuperá-lo. Além disso, postar um patch na web permite modificá-lo sem ter que reenviar todo o patch em um followup do PR original. Finalmente, os patches grandes simplesmente aumentam o tamanho do banco de dados, uma vez que os PRs fechados não são realmente excluídos, mas sim mantidos e simplesmente marcados como completos.

Você também deve observar que, a menos que você especifique explicitamente o contrário em seu PR ou no próprio patch, quaisquer patches enviados por você serão considerados licenciados sob os mesmos termos do arquivo original que você modificou.

[[pr-writing-filling-template]]
== Preenchendo o formulário

[NOTE]
====
O endereço de e-mail que você usa se tornará publico e poderá se tornar disponível para spammers. Você deve ter procedimentos de tratamento de spam ou usar uma conta de email temporária. No entanto, observe que, se você não usar uma conta de e-mail válida, não poderemos fazer perguntas sobre seu PR.
====

Quando você for reportar um bug, você encontrará os seguintes campos:

* _Summary (Sumário):_ Preencha com uma descrição breve e precisa do problema. A sinopse é usada como assunto do email do relatório de problemas. A sinopse é usada em listagens e resumos de relatórios de problemas; relatórios de problemas com sinopses obscuras tendem a ser ignoradas.
* _Severity (Gravidade):_ Um dos `Affects only me (Afeta somente eu)`, `Affects some people (Afeta algumas pessoas)` ou `Affects many people (Afeta muitas pessoas)`. Não exagere; abstenha-se de rotular seu problema como `Afeta muitas pessoas` a menos que ele realmente afete. 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.
* _Category (Categoria):_ Escolha uma categoria apropriada.
+
A primeira coisa que você precisa fazer é decidir em que parte do sistema está seu problema. Lembre-se, o FreeBSD é um sistema operacional completo, que instala tanto um kernel, bibliotecas padrão, muitos drivers de periféricos e um grande número de utilitários (o "sistema básico"). No entanto, existem milhares de aplicativos adicionais na coleção de portes. Você primeiro precisa decidir se o problema está no sistema básico ou algo instalado via a Coleção de Ports.
+
Aqui está uma descrição das categorias principais:

** Se um problema for com o kernel, as bibliotecas (como a biblioteca C padrão `libc`), ou o driver de algum periférico no sistema base, em geral você irá usar a categoria `kern`. (Existem algumas exceções; veja abaixo). Em geral, são coisas descritas nas seções 2, 3 ou 4 das páginas de manual.
** Se o problema for com um programa binário, como man:sh[1] ou man:mount[8], primeiro você precisará determinar se esses programas estão no sistema básico ou se foram adicionados por meio da Coleção de Ports. Se não tiver certeza, você pode executar `whereis _nome_do_programa_`. A convenção do FreeBSD para a Coleção de Ports é instalar tudo abaixo do [.filename]#/usr/local#, embora esse comportamento possa ser alterado por um administrador do sistema. Para estes, você usará a categoria `ports` (sim, mesmo se a categoria do port for `www`; veja abaixo). Se a localização for [.filename]#/bin#, [.filename]#/usr/bin#, [.filename]#/sbin# , ou [.filename]#/usr/sbin#, ele faz parte do sistema base, e você deve usar a categoria `bin`. Essas são todas as coisas descritas na seção 1 ou 8 das páginas de manual.
** Se você acredita que o erro está nos scripts de inicialização `(rc)`, ou em algum outro tipo de arquivo de configuração não-executável, então a categoria correta é `conf` (configuração) . Estas são as coisas descritas na seção 5 das páginas de manual.
** Se você encontrou um problema no conjunto de documentação (artigos, livros, man pages) ou no website, a escolha correta é `docs`.
+
[NOTE]
====
Se você estiver tendo um problema com algum port chamado `www/_algum-nome-de-port_`, mesmo assim, isso vai na categoria `ports`.
====
+
Existem algumas categorias mais especializadas.

** Se o problema, por outro lado, estar colocado em `kern`, mas tem a ver com o subsistema USB, a escolha correta é `usb`.
** Se o problema, por outro lado, estiver colocado em `kern`, mas tem a ver com as bibliotecas de threads, a escolha correta é `threads`.
** Se o problema, por outro lado, estiver no sistema base, mas tem a ver com nossa fidelidade a padrões como POSIX(R), a escolha correta é `standards`.
** Se estiver convencido de que o problema ocorrerá apenas sob a arquitetura do processador que você está usando, selecione uma das categorias específicas da arquitetura: geralmente `i386` para máquinas compatíveis com Intel 32 bits; `amd64` para máquinas AMD rodando em 64 bits (isto também inclui máquinas compatíveis com Intel rodando em modo EMT64); e menos comumente, as arquiteturas `arm` ou `powerpc`.
+
[NOTE]
====
Estas categorias são muitas vezes mal utilizadas para problemas definidos como "Eu não sei". Em vez de adivinhar, por favor apenas use a categoria `misc`.
====
+
.Uso Correto da Categoria Específica de Arquitetura
[example]
====
Você tem uma máquina comum baseada em PC e acha que encontrou um problema específico para um determinado chipset ou uma placa-mãe em particular: `i386` é a categoria correta.
====
+
.Uso Incorreto da Categoria Específica de Arquitetura
[example]
====
Você está tendo um problema com uma placa periférica adicional em um barramento comum, ou um problema com um tipo específico de unidade de disco rígido: neste caso, provavelmente se aplica a mais de uma arquitetura, e `kern` é a categoria correta.
====
** Se você realmente não sabe onde o problema se encaixa (ou a explicação não parece se encaixar nos itens acima), use a categoria `misc`. Antes de fazer isso, você pode pedir ajuda primeiro na {freebsd-questions}. Você pode ser avisado que com certeza uma das categorias existentes é uma escolha melhor.
* _Environment:_ Isto deve descrever, com a maior precisão possível, o ambiente em que o problema foi observado. Isto inclui a versão do sistema operacional, a versão do programa ou arquivo específico que contém o problema e quaisquer outros itens relevantes, como configuração do sistema, outro software instalado que influencia no problema, etc. - simplesmente tudo o que um desenvolvedor precisa saber para reconstruir o ambiente em que ocorra o problema.
* _Description:_ Uma descrição completa e precisa do problema que você está enfrentando. Tente evitar especular sobre as causas do problema, a menos que tenha certeza de que você está no caminho certo, pois isso pode induzir o desenvolvedor a fazer suposições incorretas sobre o problema. Ela deve incluir as ações que você precisa executar para reproduzir o problema. Se você conhece alguma solução alternativa, inclua-a. Ela não apenas ajuda outras pessoas com o mesmo problema a contorná-lo, mas também pode ajudar um desenvolvedor a entender a causa do problema.

[[pr-followup]]
== Acompanhamento

Uma vez que o relatório de problema foi colocado na fila, você receberá uma confirmação por e-mail que incluirá o número de rastreamento que foi atribuído ao seu relatório de problema e uma URL que você pode usar para verificar seu status. Com um pouco de sorte, alguém se interessará por seu problema e tentará resolvê-lo, ou, conforme o caso, explicar por que isso não é um problema. Você será automaticamente notificado de qualquer alteração de status e receberá cópias de quaisquer comentários ou correções que alguém possa anexar à trilha de auditoria do seu relatório de problemas.

Se alguém solicitar informações adicionais de você, lembrar ou descobrir algo que você não mencionou no relatório inicial, por favor, adicione um novo comentário de acompanhamento. O motivo número um para um bug não ser corrigido é a falta de comunicação com o criador do relatório. A maneira mais fácil de fazer isso é usar a opção de comentário na página da Web individual do PR, que você pode acessar a partir da https://bugs.freebsd.org/bugzilla/query.cgi[página de pesquisa de PRs].

Se o relatório de problemas permanecer aberto após o desaparecimento do problema, basta adicionar um comentário dizendo que o relatório de problemas pode ser fechado e, se possível, explicar como ou quando o problema foi corrigido.

As vezes, há um atraso de uma semana ou duas em que o relatório do problema permanece intocado, não atribuído ou comentado por alguém. Isto pode acontecer quando há um aumento na lista de pendências de relatórios de problemas ou durante uma temporada de feriados. Quando um relatório de problema não recebe atenção após várias semanas, vale a pena encontrar um committer particularmente interessado em trabalhar nele.

Existem algumas maneiras de se fazer isso, idealmente na seguinte ordem, com alguns dias entre a tentativa em cada canal de comunicação:

* Envie uma mensagem para extref:{handbook}eresources/[a lista em questão, eresources-summary] solicitando comentários sobre o relatório.
* Junte-se aos canais relevantes do IRC. Uma lista parcial está aqui: https://wiki.freebsd.org/IrcChannels[]. Informe as pessoas nesse canal sobre o relatório de problemas e peça ajuda. Seja paciente e fique no canal depois de postar, para que as pessoas de diferentes fusos horários ao redor do mundo tenham a chance de responder.
* Encontre committers interessados no problema que foi relatado. Se o problema estiver em uma ferramenta, binário, porta, documento ou arquivo fonte específico, verifique o https://cgit.FreeBSD.org[Repositório Git]. Localize os últimos committers que fizeram alterações substanciais no arquivo e tente falar com eles pelo IRC ou por email. Uma lista de committers e seus e-mails podem ser encontrados no artigo extref:{contributors}[Contribuidores do FreeBSD].

Lembre-se de que essas pessoas são voluntárias, assim como mantenedores e usuários, portanto, podem não estar disponíveis imediatamente para ajudar no relatório de problemas. Paciência e consistência nos acompanhamentos são altamente recomendados e apreciados. Com cuidado e esforço suficientemente dedicados a esse processo de acompanhamento, encontrar um committer para cuidar do relatório do problema é apenas uma questão de tempo.

[[pr-problems]]
== Se Existir Problemas

Se você encontrou um problema com o sistema de bugs, registre um bug! Existe uma categoria exatamente para esse propósito. Se você não conseguir, entre em contato com os organizadores do bug em mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org].

[[pr-further]]
== Leitura Adicional

Esta é uma lista de recursos relevantes para a escrita adequada e processamento de relatórios de problemas. Não está de modo algum completo.

* https://github.com/smileytechguy/reporting-bugs-effectively/blob/master/ENGLISH.md[Como reportar bugs efetivamente] -um excelente ensaio de Simon G. Tatham sobre como compor de forma útil relatórios de problemas (não específicos do FreeBSD).
* extref:{pr-guidelines}[Diretrizes para manuseio de relatórios de problemas] --informações valiosas sobre como os relatórios de problemas são tratados pelos desenvolvedores do FreeBSD.
