Diretrizes para manuseio de relatórios de problemas

Dag-Erling Smørgrav

Hiten Pandya

Nota Legal

FreeBSD is a registered trademark of the FreeBSD Foundation.

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.

Resumo

Estas diretrizes descrevem as práticas de manuseio recomendadas para os Relatórios de Problemas do FreeBSD (PRs). Embora desenvolvido para a equipe de manutenção de banco de dados do FreeBSD PR freebsd-bugbusters@FreeBSD.org, essas diretrizes devem ser seguidas por qualquer pessoa que trabalhe com os Relatórios de Problemas do FreeBSD.


1. Introdução

O Bugzilla é um sistema de gerenciamento de problemas usado pelo Projeto FreeBSD. Como o rastreamento preciso de defeitos de software pendentes é importante para a qualidade do FreeBSD, o uso correto do software é essencial para o avanço do projeto.

O acesso ao Bugzilla está disponível para toda a comunidade do FreeBSD. Para manter a consistência dentro do banco de dados e fornecer uma experiência de usuário consistente, diretrizes foram estabelecidas cobrindo aspectos comuns do gerenciamento de erros, como apresentação de acompanhamento, tratamento de solicitações de fechamento e assim por diante.

2. Ciclo de vida de um relatório de problemas

  • O usuário envia um relatório de bug no site. O bug está no estado Needs Triage.

  • Jane Random BugBuster confirma que o relatório de erros tem informação suficiente para ser reproduzível. Se não, ela irá interagir repetidamente com o usuário para obter as informações necessárias. Neste ponto, o bug é definido para o estado Open.

  • Joe Random Committer se interessa pelo PR e o atribui a si mesmo, ou Jane Random BugBuster decide que Joe é a pessoa mais adequada para lidar com o problema e atribui o bug a ele. O bug deve ser definido para o estado In Discussion.

  • Joe tem uma breve troca com o usuário que originou o relatório de problema (certificando-se de que toda a comunicação ficou registrada na trilha de auditoria) e determina a causa do problema.

  • Joe vira a noite trabalhando e produz um patch que ele acha que corrige o problema, e o envia em um follow-up para o originador, pedindo que ele teste a solução. Em seguida, ele configura o estado do PR para Patch Ready.

  • Algumas iterações depois, Joe e o originador estão satisfeitos com o patch, e Joe faz o commit para o branch -CURRENT (ou diretamente para o branch -STABLE se o problema não existir no -CURRENT), certificando-se de fazer referencia ao Relatório de Problemas no seu log de commit (e dando o crédito ao originador caso ele tenha enviado o patch todo ou parte dele) e, se apropriado, iniciará uma contagem regressiva de MFC. O bug é então alterado para o estado Needs MFC.

  • Se o patch não precisar de passar por um MFC, Joe então fecha o PR com o status Issue Resolved.

Muitos PRs são submetidos contendo muito pouca informação sobre o problema, e alguns são muito complexos para resolver, ou apenas arranham a superfície de um problema maior; Nestes casos, é muito importante obter todas as informações necessárias para resolver o problema. Se o problema reportado não puder ser resolvido ou caso ele ocorra novamente, é necessário reabrir o PR.

3. Estado do relatório de problemas

É importante atualizar o status de um PR quando determinadas ações são tomadas. O status deve refletir com precisão o estado atual do trabalho no PR.

Exemplo 1. Um pequeno exemplo sobre quando alterar o estado de PR

Quando um PR tiver sido tratado e o desenvolvedor responsável se sente confortável com a correção, ele enviará um follow up para o PR e mudará o seu estado para "feedback". Neste ponto, o originador deve avaliar a correção em seu contexto e responder indicando se o defeito foi de fato remediado.

Um Relatório de Problemas pode estar em um dos seguintes estados:

open

Estado inicial; o problema foi apontado e precisa ser revisto.

analyzed

O problema foi revisto e uma solução está sendo procurada.

feedback

Trabalhos adicionais requerem informações adicionais do originador ou da comunidade; possivelmente informações sobre a solução proposta.

patched

Foi realizado o commit de um patch, mas algo (MFC, ou talvez confirmação do originador) ainda está pendente.

suspended

O problema não está sendo trabalhado, devido à falta de informações ou recursos. Este é um excelente candidato para alguém que está procurando um projeto para assumir. Se o problema não puder ser resolvido, ele será fechado, e não suspenso. O projeto de documentação usa suspended para itens da lista de desejos que envolvem uma quantidade significativa de trabalho para a qual ninguém tem tempo no momento.

closed

Um relatório de problemas é fechado quando as alterações referentes a ele tiverem sido integradas, documentadas e testadas ou, quando a correção do problema tiver sido abandonada.

O estado "patched" está diretamente relacionado ao feedback, então você pode passar direto para o estado de "closed" se o originador não puder testar o patch, e ele tiver funcionado no seu próprio teste.

4. Tipos de relatórios de problemas

Ao lidar com relatórios de problemas, seja como um desenvolvedor que tenha acesso direto ao banco de dados de relatórios de problemas ou como colaborador que navega no banco de dados e envia followups com patches, comentários, sugestões ou solicitações de alteração, você vai encontrar vários tipos diferentes de PRs.

As seções a seguir descrevem para que cada tipo diferente de PRs é usado, quando um PR pertence a um desses tipos e qual tratamento cada tipo diferente recebe.

5. PRs não atribuídos

Quando os PRs chegam, eles são inicialmente atribuídos a um responsável genérico (placeholder). Estes são sempre prefixados com freebsd-. O valor exato para esse padrão depende da categoria; na maioria dos casos, corresponde a uma lista de discussão específica do FreeBSD. Aqui está a lista atual, com os mais comuns listados primeiro:

Tabela 1. Responsáveis ​​Padrões - mais comuns
TipoCategoriasResponsável Padrão

sistema base

bin, conf, gnu, kern, misc

freebsd-bugs

arquitetura específica

alpha, amd64, arm, i386, ia64, powerpc, sparc64

freebsd-arch

Coleção de Ports

ports

freebsd-ports-bugs

documentação enviada com o sistema

docs

freebsd-doc

Páginas web do FreeBSD (não incluindo docs)

Website

freebsd-www

Tabela 2. Responsável Padrão - outros
TipoCategoriasResponsável Padrão

esforços de advocacia

advocacia

freebsd-advocacy

Problemas com Java Virtual Machine™

Java

freebsd-java

conformidade com padrões

padrões

freebsd-standards

bibliotecas de threading

threads

freebsd-threads

Subsistema usb(4)

USB

freebsd-usb

Não se surpreenda ao descobrir que o usuário responsável pelo PR atribuiu a categoria errada. Se você corrigir a categoria, não se esqueça de corrigir a atribuição também. (Em particular, nossos usuários parecem ter dificuldade em entender que apenas porque seu problema se manifesta em um sistema i386, que ele pode ser genérico para todo o FreeBSD, e assim ser mais apropriado para o kern. O oposto também é verdade, claro.)

Certos PRs podem ser reatribuídos para longe destes responsáveis genéricos por qualquer pessoa. Existem vários tipos de responsáveis: listas de discussão especializadas; aliases de correio (usados ​​para determinados itens de interesse limitado); e indivíduos.

Para os responsáveis ​​que são listas de discussão, use o formulário longo ao fazer a atribuição (por exemplo, freebsd-foo em vez de foo); isso evitará emails duplicados enviados para a lista de discussão.

Como a lista de indivíduos que se voluntariaram para ser o responsável padrão para certos tipos de PRs muda com bastante frequência, ela é muito mais adequada para o the FreeBSD wiki.

Aqui está uma lista de exemplo de tais entidades; provavelmente não está completa.

Tabela 3. Responsáveis ​​Comuns - sistema base
TipoCategoria SugeridaResponsável SugeridoTipo de Responsável

problema específico da arquitetura ARM®

arm

freebsd-arm

lista de discussão

problema específico da arquitetura MIPS®

kern

freebsd-mips

lista de discussão

problema específico da arquitetura PowerPC®

kern

freebsd-ppc

lista de discussão

problema com Configuração Avançada e Gerenciamento de Energia (acpi(4))

kern

freebsd-acpi

lista de discussão

problema com os drivers de modo de transferência assíncrona (ATM)

kern

freebsd-atm

lista de discussão

problema com sistemas FreeBSD embarcados ou de small-footprint (por exemplo, NanoBSD/PicoBSD/FreeBSD-arm)

kern

freebsd-embedded

lista de discussão

problema com os drivers FireWire®

kern

freebsd-firewire

lista de discussão

problema com o código do sistema de arquivos

kern

freebsd-fs

lista de discussão

problema com o subsistema geom(4)

kern

freebsd-geom

lista de discussão

problema com o subsistema ipfw(4)

kern

freebsd-ipfw

lista de discussão

problema com os drivers de rede digital de serviços integrados (ISDN)

kern

freebsd-isdn

lista de discussão

subsistema jail(8)

kern

freebsd-jail

lista de discussão

problema com a emulação Linux® ou SVR4

kern

freebsd-emulation

lista de discussão

problema com a pilha de rede

kern

freebsd-net

lista de discussão

problema com o subsistema pf(4)

kern

freebsd-pf

lista de discussão

problema com o subsistema scsi(4)

kern

freebsd-scsi

lista de discussão

problema com o subsistema sound(4)

kern

freebsd-multimedia

lista de discussão

problemas com o subsistema wlan(4) e drivers sem fio

kern

freebsd-wireless

lista de discussão

problema com o sysinstall(8) ou bsdinstall(8)

bin

freebsd-sysinstall

lista de discussão

problema com os scripts de inicialização do sistema (rc(8))

kern

freebsd-rc

lista de discussão

problema com funcionalidade VIMAGE ou VNET e código relacionado

kern

freebsd-virtualization

lista de discussão

problema com a emulação de Xen

kern

freebsd-xen

lista de discussão

Tabela 4. Responsáveis Comuns - Ports Collection
TipoCategoria SugeridaResponsável SugeridoTipo de Responsável

problema com o framework da coleção de ports (não com um port individual!)

ports

portmgr

alias

port que é mantido por apache@FreeBSD.org

ports

apache

lista de discussão

port que é mantido por autotools@FreeBSD.org

ports

autotools

alias

port que é mantido por doceng@FreeBSD.org

ports

doceng

alias

port que é mantido por eclipse@FreeBSD.org

ports

freebsd-eclipse

lista de discussão

port que é mantido por gecko@FreeBSD.org

ports

gecko

lista de discussão

port que é mantido por gnome@FreeBSD.org

ports

gnome

lista de discussão

port que é mantido por hamradio@FreeBSD.org

ports

hamradio

alias

port que é mantido por haskell@FreeBSD.org

ports

haskell

alias

port que é mantido por java@FreeBSD.org

ports

freebsd-java

lista de discussão

port que é mantido por kde@FreeBSD.org

ports

kde

lista de discussão

port que é mantido por mono@FreeBSD.org

ports

mono

lista de discussão

port que é mantido por office@FreeBSD.org

ports

freebsd-office

lista de discussão

port que é mantido por perl@FreeBSD.org

ports

perl

lista de discussão

port que é mantido por python@FreeBSD.org

ports

freebsd-python

lista de discussão

port que é mantido por ruby@FreeBSD.org

ports

freebsd-ruby

lista de discussão

port que é mantido por secteam@FreeBSD.org

ports

secteam

alias

port que é mantido por vbox@FreeBSD.org

ports

vbox

alias

port que é mantido por x11@FreeBSD.org

ports

freebsd-x11

lista de discussão

Os PRs relacionados aos ports que têm um mantenedor que é um committer de ports podem ser reatribuídas por qualquer um (mas note que nem todo committer do FreeBSD é necessariamente um committer de ports, então você não pode simplesmente ir sozinho pelo endereço de email).

Para outros PRs, por favor, não os reatribua para outros indivíduos (outros que não sejam você), a menos que tenha certeza de que o responsável realmente deseja acompanhar o PR. Isso ajudará a evitar situações em que ninguém se dedica para consertar um problema em particular, porque todos assumem que o responsável já está trabalhando nele.

Tabela 5. Responsáveis ​​Comuns - Outros
TipoCategoria SugeridaResponsável SugeridoTipo de Responsável

problema com o banco de dados de PR

bin

bugmeister

alias

problema com o formulário web do Bugzilla.

doc

bugmeister

alias

6. PRs Atribuídos

Se um PR tiver o campo responsible configurado para o nome de usuário de um desenvolvedor do FreeBSD, isso significa que o PR foi entregue a essa pessoa em particular para trabalho adicional.

PRs designados não devem ser tocados por ninguém além do responsável ou do bugmeister. Se você tiver comentários, envie um followup. Se, por algum motivo, você achar que o PR deve mudar de estado ou ser reatribuído, envie uma mensagem ao responsável. Se o responsável não responder dentro de duas semanas, cancele a atribuição do PR e faça o que quiser.

7. PRs Duplicados

Se você encontrar mais de um PR que descreva o mesmo problema, escolha aquele que contém a maior quantidade de informações úteis e feche os outros, indicando claramente o número do PR substituto. Se vários PRs contiverem informações úteis que não se sobrepõem, envie todas as informações ausentes para um para um deles por meio de um followup, incluindo referências aos outros; em seguida, feche os outros PRs (que agora estão completamente substituídos).

8. PRs Obsoletos

Um PR é considerado obsoleto se não tiver sido modificado em mais de seis meses. Aplique o seguinte procedimento para lidar com PRs obsoletos:

  • Se o PR contiver detalhes suficientes, tente reproduzir o problema no -CURRENT e no -STABLE. Se você tiver sucesso, envie um followup detalhando suas descobertas e tente encontrar alguém para atribuí-lo. Defina o estado para "analyzed", se apropriado.

  • Se o PR descrever um problema que você sabe ser o resultado de um erro de uso (configuração incorreta ou outra coisa do tipo), envie um followup explicando o que o originador fez de errado e feche o PR com o motivo "User error" ou "Configuration error".

  • Se o PR descreve um erro que você sabe ter sido corrigido no -CURRENT e -STABLE, feche-o com uma mensagem informando quando ele foi corrigido em cada branch.

  • Se o PR descreve um erro que você sabe ter sido corrigido no -CURRENT, mas não no -STABLE, tente descobrir quando a pessoa que o corrigiu está planejando o MFC ou tente encontrar alguém (talvez você?) para fazê-lo. Defina o estado para "patched" e atribua-o a quem quer que tenha ficado responsável por fazer o MFC.

  • Em outros casos, peça ao originador para confirmar se o problema ainda existe em versões mais recentes. Se o originador não responder dentro de um mês, feche o PR com a notação "Feedback timeout".

9. PRs Sem Erros

Desenvolvedores que se deparem com PRs que na verdade deveriam ter sido postados na freebsd-bugs ou em alguma outra lista deve fechar o PR, e informar o originador em um comentário do porque o problema reportado não é realmente um PR e orientá-lo sobre onde a mensagem deve ser postada.

Os endereços de e-mail que o Bugzilla utiliza para receber os PRs foram publicados como parte da documentação do FreeBSD, e também foram anunciados e listados no website. Isso significa que os spammers os encontraram.

Sempre que você fechar um desses PRs, faça o seguinte:

  • Defina o componente como junk (em Supporting Services).

  • Defina o responsável para nobody@FreeBSD.org.

  • Defina o estado como Issue Resolved.

Definir a categoria como junk torna óbvio que não há conteúdo útil dentro do PR e ajuda a reduzir a desordem nas categorias principais.

10. Leitura Adicional

Esta é uma lista de recursos relevantes para a escrita e processamento adequado de um relatório de problema. De forma alguma deve ser considerada completa.