              Diretrizes para manuseio de relatorios de problemas

  Dag-Erling Smo/rgrav

  Hiten Pandya

   Revisao: 7306e748ee

   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 "(TM)" or the "(R)"
   symbol.

   2018-09-06 00:29:07 +0000 por Edson Brandi.
   Resumo

   Estas diretrizes descrevem as praticas de manuseio recomendadas para os
   Relatorios de Problemas do FreeBSD (PRs). Embora desenvolvido para a
   equipe de manutenc,ao de banco de dados do FreeBSD PR <
   freebsd-bugbusters@FreeBSD.org >, essas diretrizes devem ser seguidas por
   qualquer pessoa que trabalhe com os Relatorios de Problemas do FreeBSD.

   [ Documento HTML em partes / Documento HTML completo ]

     ----------------------------------------------------------------------

   Indice

   1. Introduc,ao

   2. Ciclo de vida de um relatorio de problemas

   3. Estado do relatorio de problemas

   4. Tipos de relatorios de problemas

   5. Leitura Adicional

1. Introduc,ao

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

   O acesso ao Bugzilla esta disponivel para toda a comunidade do FreeBSD.
   Para manter a consistencia dentro do banco de dados e fornecer uma
   experiencia de usuario consistente, diretrizes foram estabelecidas
   cobrindo aspectos comuns do gerenciamento de erros, como apresentac,ao de
   acompanhamento, tratamento de solicitac,oes de fechamento e assim por
   diante.

2. Ciclo de vida de um relatorio de problemas

     * O usuario envia um relatorio de bug no site. O bug esta no estado
       Needs Triage .

     * Jane Random BugBuster confirma que o relatorio de erros tem
       informac,ao suficiente para ser reproduzivel. Se nao, ela ira
       interagir repetidamente com o usuario para obter as informac,oes
       necessarias. Neste ponto, o bug e 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 e 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 usuario que originou o relatorio de
       problema (certificando-se de que toda a comunicac,ao 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 soluc,ao. Em seguida, ele configura o estado
       do PR para Patch Ready.

     * Algumas iterac,oes depois, Joe e o originador estao satisfeitos com o
       patch, e Joe faz o commit para o branch -CURRENT (ou diretamente para
       o branch -STABLE se o problema nao existir no -CURRENT),
       certificando-se de fazer referencia ao Relatorio de Problemas no seu
       log de commit (e dando o credito ao originador caso ele tenha enviado
       o patch todo ou parte dele) e, se apropriado, iniciara uma contagem
       regressiva de MFC. O bug e entao alterado para o estado Needs MFC .

     * Se o patch nao precisar de passar por um MFC, Joe entao fecha o PR com
       o status Issue Resolved.

  Nota:

   Muitos PRs sao submetidos contendo muito pouca informac,ao sobre o
   problema, e alguns sao muito complexos para resolver, ou apenas arranham a
   superficie de um problema maior; Nestes casos, e muito importante obter
   todas as informac,oes necessarias para resolver o problema. Se o problema
   reportado nao puder ser resolvido ou caso ele ocorra novamente, e
   necessario reabrir o PR.

3. Estado do relatorio de problemas

   E importante atualizar o status de um PR quando determinadas ac,oes sao
   tomadas. O status deve refletir com precisao 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 responsavel se sente
   confortavel com a correc,ao, ele enviara um follow up para o PR e mudara o
   seu estado para "feedback". Neste ponto, o originador deve avaliar a
   correc,ao em seu contexto e responder indicando se o defeito foi de fato
   remediado.

   Um Relatorio 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 soluc,ao esta sendo procurada.

   feedback

           Trabalhos adicionais requerem informac,oes adicionais do
           originador ou da comunidade; possivelmente informac,oes sobre a
           soluc,ao proposta.

   patched

           Foi realizado o commit de um patch, mas algo (MFC, ou talvez
           confirmac,ao do originador) ainda esta pendente.

   suspended

           O problema nao esta sendo trabalhado, devido `a falta de
           informac,oes ou recursos. Este e um excelente candidato para
           alguem que esta procurando um projeto para assumir. Se o problema
           nao puder ser resolvido, ele sera fechado, e nao suspenso. O
           projeto de documentac,ao usa "suspended" para itens da "lista de
           desejos" que envolvem uma quantidade significativa de trabalho
           para a qual ninguem tem tempo no momento.

   closed

           Um relatorio de problemas e fechado quando as alterac,oes
           referentes a ele tiverem sido integradas, documentadas e testadas
           ou, quando a correc,ao do problema tiver sido abandonada.

  Nota:

   O estado "patched" esta diretamente relacionado ao feedback, entao voce
   pode passar direto para o estado de "closed" se o originador nao puder
   testar o patch, e ele tiver funcionado no seu proprio teste.

4. Tipos de relatorios de problemas

   Ao lidar com relatorios de problemas, seja como um desenvolvedor que tenha
   acesso direto ao banco de dados de relatorios de problemas ou como
   colaborador que navega no banco de dados e envia followups com patches,
   comentarios, sugestoes ou solicitac,oes de alterac,ao, voce vai encontrar
   varios tipos diferentes de PRs.

     * PRs que ainda nao estao atribuidos para ninguem.

     * PRs ja atribuidos para alguem.

     * Duplicatas de PRs existentes.

     * PRs Obsoletos

     * PRs que nao estao relacionados a bugs

   As sec,oes a seguir descrevem para que cada tipo diferente de PRs e usado,
   quando um PR pertence a um desses tipos e qual tratamento cada tipo
   diferente recebe.

  4.1. PRs nao atribuidos

   Quando os PRs chegam, eles sao inicialmente atribuidos a um responsavel
   generico (placeholder). Estes sao sempre prefixados com freebsd-. O valor
   exato para esse padrao depende da categoria; na maioria dos casos,
   corresponde a uma lista de discussao especifica do FreeBSD. Aqui esta a
   lista atual, com os mais comuns listados primeiro:

   Tabela 1. Responsaveis &#8203;&#8203;Padroes - mais comuns

   +------------------------------------------------------------------------+
   |           Tipo            |      Categorias       | Responsavel Padrao |
   |---------------------------+-----------------------+--------------------|
   | sistema base              | bin, conf, gnu, kern, | freebsd-bugs       |
   |                           | misc                  |                    |
   |---------------------------+-----------------------+--------------------|
   |                           | alpha, amd64, arm,    |                    |
   | arquitetura especifica    | i386, ia64, powerpc,  | freebsd-arch       |
   |                           | sparc64               |                    |
   |---------------------------+-----------------------+--------------------|
   | Colec,ao de Ports         | ports                 | freebsd-ports-bugs |
   |---------------------------+-----------------------+--------------------|
   | documentac,ao enviada com | docs                  | freebsd-doc        |
   | o sistema                 |                       |                    |
   |---------------------------+-----------------------+--------------------|
   | Paginas web do FreeBSD    | Website               | freebsd-www        |
   | (nao incluindo docs)      |                       |                    |
   +------------------------------------------------------------------------+

   Tabela 2. Responsavel Padrao - outros

   +------------------------------------------------------------------------+
   |                 Tipo                 | Categorias | Responsavel Padrao |
   |--------------------------------------+------------+--------------------|
   | esforc,os de advocacia               | advocacia  | freebsd-advocacy   |
   |--------------------------------------+------------+--------------------|
   | Problemas com Java Virtual           | Java       | freebsd-java       |
   | Machine(TM)                          |            |                    |
   |--------------------------------------+------------+--------------------|
   | conformidade com padroes             | padroes    | freebsd-standards  |
   |--------------------------------------+------------+--------------------|
   | bibliotecas de threading             | threads    | freebsd-threads    |
   |--------------------------------------+------------+--------------------|
   | Subsistema usb(4)                    | USB        | freebsd-usb        |
   +------------------------------------------------------------------------+

   Nao se surpreenda ao descobrir que o usuario responsavel pelo PR atribuiu
   a categoria errada. Se voce corrigir a categoria, nao se esquec,a de
   corrigir a atribuic,ao tambem. (Em particular, nossos usuarios parecem ter
   dificuldade em entender que apenas porque seu problema se manifesta em um
   sistema i386, que ele pode ser generico para todo o FreeBSD, e assim ser
   mais apropriado para o kern. O oposto tambem e verdade, claro.)

   Certos PRs podem ser reatribuidos para longe destes responsaveis genericos
   por qualquer pessoa. Existem varios tipos de responsaveis: listas de
   discussao especializadas; aliases de correio (usados &#8203;&#8203;para
   determinados itens de interesse limitado); e individuos.

   Para os responsaveis &#8203;&#8203;que sao listas de discussao, use o
   formulario longo ao fazer a atribuic,ao (por exemplo, freebsd-foo em vez
   de foo); isso evitara emails duplicados enviados para a lista de
   discussao.

  Nota:

   Como a lista de individuos que se voluntariaram para ser o responsavel
   padrao para certos tipos de PRs muda com bastante frequencia, ela e muito
   mais adequada para o the FreeBSD wiki.

   Aqui esta uma lista de exemplo de tais entidades; provavelmente nao esta
   completa.

   Tabela 3. Responsaveis &#8203;&#8203;Comuns - sistema base

   +-------------------------------------------------------------------------+
   |            Tipo            |Categoria| Responsavel Sugerido |  Tipo de  |
   |                            |Sugerida |                      |Responsavel|
   |----------------------------+---------+----------------------+-----------|
   |problema especifico da      |arm      |freebsd-arm           |lista de   |
   |arquitetura ARM(R)          |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema especifico da      |kern     |freebsd-mips          |lista de   |
   |arquitetura MIPS(R)         |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema especifico da      |kern     |freebsd-ppc           |lista de   |
   |arquitetura PowerPC(R)      |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com Configurac,ao  |         |                      |lista de   |
   |Avanc,ada e Gerenciamento de|kern     |freebsd-acpi          |discussao  |
   |Energia (acpi(4))           |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema com os drivers de  |         |                      |lista de   |
   |modo de transferencia       |kern     |freebsd-atm           |discussao  |
   |assincrona (ATM)            |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema com sistemas       |         |                      |           |
   |FreeBSD embarcados ou de    |         |                      |lista de   |
   |small-footprint (por        |kern     |freebsd-embedded      |discussao  |
   |exemplo,                    |         |                      |           |
   |NanoBSD/PicoBSD/FreeBSD-arm)|         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema com os drivers     |kern     |freebsd-firewire      |lista de   |
   |FireWire(R)                 |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o codigo do    |kern     |freebsd-fs            |lista de   |
   |sistema de arquivos         |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o subsistema   |kern     |freebsd-geom          |lista de   |
   |geom(4)                     |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o subsistema   |kern     |freebsd-ipfw          |lista de   |
   |ipfw(4)                     |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com os drivers de  |         |                      |lista de   |
   |rede digital de servic,os   |kern     |freebsd-isdn          |discussao  |
   |integrados (ISDN)           |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |subsistema jail(8)          |kern     |freebsd-jail          |lista de   |
   |                            |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com a emulac,ao    |kern     |freebsd-emulation     |lista de   |
   |Linux(R) ou SVR4            |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com a pilha de rede|kern     |freebsd-net           |lista de   |
   |                            |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o subsistema   |kern     |freebsd-pf            |lista de   |
   |pf(4)                       |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o subsistema   |kern     |freebsd-scsi          |lista de   |
   |scsi( 4 )                   |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o subsistema   |kern     |freebsd-multimedia    |lista de   |
   |sound( 4 )                  |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problemas com o subsistema  |kern     |freebsd-wireless      |lista de   |
   |wlan( 4 ) e drivers sem fio |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com o sysinstall(8)|bin      |freebsd-sysinstall    |lista de   |
   |ou bsdinstall(8)            |         |                      |discussao  |
   |----------------------------+---------+----------------------+-----------|
   |problema com os scripts de  |         |                      |lista de   |
   |inicializac,ao do sistema   |kern     |freebsd-rc            |discussao  |
   |(rc(8))                     |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema com funcionalidade |         |                      |lista de   |
   |VIMAGE ou VNET e codigo     |kern     |freebsd-virtualization|discussao  |
   |relacionado                 |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema com a emulac,ao de |kern     |freebsd-xen           |lista de   |
   |Xen                         |         |                      |discussao  |
   +-------------------------------------------------------------------------+

   Tabela 4. Responsaveis Comuns - Ports Collection

   +------------------------------------------------------------------------+
   |            Tipo            | Categoria |   Responsavel   |   Tipo de   |
   |                            | Sugerida  |    Sugerido     | Responsavel |
   |----------------------------+-----------+-----------------+-------------|
   | problema com o framework   |           |                 |             |
   | da colec,ao de ports (nao  | ports     | portmgr         | alias       |
   | com um port individual!)   |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | apache          | lista de    |
   | apache@FreeBSD.org         |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | autotools       | alias       |
   | autotools@FreeBSD.org      |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | doceng          | alias       |
   | doceng@FreeBSD.org         |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-eclipse | lista de    |
   | eclipse@FreeBSD.org        |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | gecko           | lista de    |
   | gecko@FreeBSD.org          |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | gnome           | lista de    |
   | gnome@FreeBSD.org          |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | hamradio        | alias       |
   | hamradio@FreeBSD.org       |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | haskell         | alias       |
   | haskell@FreeBSD.org        |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-java    | lista de    |
   | java@FreeBSD.org           |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | kde             | lista de    |
   | kde@FreeBSD.org            |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | mono            | lista de    |
   | mono@FreeBSD.org           |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-office  | lista de    |
   | office@FreeBSD.org         |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | perl            | lista de    |
   | perl@FreeBSD.org           |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-python  | lista de    |
   | python@FreeBSD.org         |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-ruby    | lista de    |
   | ruby@FreeBSD.org           |           |                 | discussao   |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | secteam         | alias       |
   | secteam@FreeBSD.org        |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | vbox            | alias       |
   | vbox@FreeBSD.org           |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port que e mantido por     | ports     | freebsd-x11     | lista de    |
   | x11@FreeBSD.org            |           |                 | discussao   |
   +------------------------------------------------------------------------+

   Os PRs relacionados aos ports que tem um mantenedor que e um committer de
   ports podem ser reatribuidas por qualquer um (mas note que nem todo
   committer do FreeBSD e necessariamente um committer de ports, entao voce
   nao pode simplesmente ir sozinho pelo enderec,o de email).

   Para outros PRs, por favor, nao os reatribua para outros individuos
   (outros que nao sejam voce), a menos que tenha certeza de que o
   responsavel realmente deseja acompanhar o PR. Isso ajudara a evitar
   situac,oes em que ninguem se dedica para consertar um problema em
   particular, porque todos assumem que o responsavel ja esta trabalhando
   nele.

   Tabela 5. Responsaveis &#8203;&#8203;Comuns - Outros

   +------------------------------------------------------------------------+
   |              Tipo              | Categoria | Responsavel |   Tipo de   |
   |                                | Sugerida  |  Sugerido   | Responsavel |
   |--------------------------------+-----------+-------------+-------------|
   | problema com o banco de dados  | bin       | bugmeister  | alias       |
   | de PR                          |           |             |             |
   |--------------------------------+-----------+-------------+-------------|
   | problema com o formulario web  | doc       | bugmeister  | alias       |
   | do Bugzilla.                   |           |             |             |
   +------------------------------------------------------------------------+

  4.2. PRs Atribuidos

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

   PRs designados nao devem ser tocados por ninguem alem do responsavel ou do
   bugmeister. Se voce tiver comentarios, envie um followup. Se, por algum
   motivo, voce achar que o PR deve mudar de estado ou ser reatribuido, envie
   uma mensagem ao responsavel. Se o responsavel nao responder dentro de duas
   semanas, cancele a atribuic,ao do PR e fac,a o que quiser.

  4.3. PRs Duplicados

   Se voce encontrar mais de um PR que descreva o mesmo problema, escolha
   aquele que contem a maior quantidade de informac,oes uteis e feche os
   outros, indicando claramente o numero do PR substituto. Se varios PRs
   contiverem informac,oes uteis que nao se sobrepoem, envie todas as
   informac,oes ausentes para um para um deles por meio de um followup,
   incluindo referencias aos outros; em seguida, feche os outros PRs (que
   agora estao completamente substituidos).

  4.4. PRs Obsoletos

   Um PR e considerado obsoleto se nao 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 voce tiver sucesso, envie um followup
       detalhando suas descobertas e tente encontrar alguem para atribui-lo.
       Defina o estado para "analyzed", se apropriado.

     * Se o PR descrever um problema que voce sabe ser o resultado de um erro
       de uso (configurac,ao 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 voce 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 voce sabe ter sido corrigido no -CURRENT,
       mas nao no -STABLE, tente descobrir quando a pessoa que o corrigiu
       esta planejando o MFC ou tente encontrar alguem (talvez voce?) para
       faze-lo. Defina o estado para "patched" e atribua-o a quem quer que
       tenha ficado responsavel por fazer o MFC.

     * Em outros casos, pec,a ao originador para confirmar se o problema
       ainda existe em versoes mais recentes. Se o originador nao responder
       dentro de um mes, feche o PR com a notac,ao "Feedback timeout".

  4.5. 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 comentario do porque o problema reportado nao
   e realmente um PR e orienta-lo sobre onde a mensagem deve ser postada.

   Os enderec,os de e-mail que o Bugzilla utiliza para receber os PRs foram
   publicados como parte da documentac,ao do FreeBSD, e tambem foram
   anunciados e listados no website. Isso significa que os spammers os
   encontraram.

   Sempre que voce fechar um desses PRs, fac,a o seguinte:

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

     * Defina o responsavel para nobody@FreeBSD.org.

     * Defina o estado como Issue Resolved.

   Definir a categoria como junk torna obvio que nao ha conteudo util dentro
   do PR e ajuda a reduzir a desordem nas categorias principais.

5. Leitura Adicional

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

     * Como escrever relatorios de problemas para o FreeBSD - diretrizes para
       usuarios que enviam um PR.
