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.
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 lide com 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 Subversion (e, caso seja afirmativo, em qual número de revisão 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 make.conf
, src.conf
e 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 /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 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 bsd.port.mk
, assim como PORTSDIR
o fato de você ter lido 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
. (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 multiplos 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/search.html#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.
Considerações semelhantes se aplicam ao uso do formulário de envio de PR web-based (com base em web). 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.
Ao anexar um patch, certifique-se de usar svn diff
ou diff(1) com o argumento -u
para criar ou unificar o diff e certificar-se de especificar os números de revisão exatos do SVN dos arquivos que você modificou para que os desenvolvedores que lerem seu relatório possam aplicá-los facilmente. Para problemas com o kernel ou com os utilitários de base, um patch para o FreeBSD-CURRENT (a branch HEAD do Subversion) é 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 correções 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.
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 sh(1) ou 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
. A convenção do FreeBSD para a Coleção de Ports é instalar tudo abaixo do nome_do_programa
/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 /bin
, /usr/bin
, /sbin
, ou /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
.
Se você estiver tendo um problema com algum port chamado www/
, mesmo assim, isso vai na categoria algum nome de port
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®, 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
.
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
.
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.
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 lista de discussão de perguntas gerais do FreeBSD. 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.
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.