                  Guia para el manejo de informes de problemas

  Dag-Erling Smo/rgrav

  Hiten Pandya

   Revision: aeb0de7ee1

   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.

   Last modified on 2019-11-16 11:55:41 +0000 by Sergio Carlavilla Delgado.
   Resumen

   Esta guia describe las practicas recomendadas para manejar los informes de
   problemas (PRs) de FreeBSD. Aunque se desarrollo para el FreeBSD PR
   database maintenance team <freebsd-bugbusters@FreeBSD.org>, cualquiera que
   trabaje con PRs de FreeBSD debe seguir estas pautas.

   [ Split HTML / Single HTML ]

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

   Tabla de contenidos

   1. Introduccion

   2. Ciclo de vida de un informe de problemas

   3. Estados de los informes de problemas

   4. Tipos de informes de problemas

   5. Lecturas adicionales

1. Introduccion

   Bugzilla es un sistema de gestion de errores que utiliza el proyecto
   FreeBSD. El seguimiento preciso de los defectos de software pendientes es
   importante para la calidad de FreeBSD. Del mismo modo, el uso correcto del
   software es esencial para el progreso del proyecto.

   El acceso a Bugzilla esta abierto a toda la comunidad de FreeBSD. Se han
   establecido ciertas pautas para cubrir aspectos comunes de la gestion de
   errores como la presentacion del seguimiento, la gestion de solicitudes de
   cierre, etc con el fin de mantener la coherencia dentro de la base de
   datos y proporcionar una experiencia de usuario consistente.

2. Ciclo de vida de un informe de problemas

     * El usuario envia un informe de error al sitio web. El error esta en el
       estado Needs Triage.

     * Jane Random BugBuster confirma que el error reportado contiene la
       suficiente informacion para ser reproducido. Si no, se interactuara
       repetidamente con el usuario hasta obtener la informacion necesaria.
       En este punto el error se establece en el estado Open.

     * Joe Random Committer se interesa por el PR y se lo asigna a si mismo,
       o Jane Random BugBuster decide que Joe es la persona mas adecuada para
       resolver el problema y le asigna el error. El error se debe poner en
       el estado In Discussion.

     * Joe tiene una breve conversacion con el usuario que ha enviado el
       informe del problema (asegurandose de que todo queda registrado) y
       determina la causa.

     * Joe esta toda la noche trabajando y elabora un parche que cree que
       soluciona el problema y lo envia en un follow-up, pidiendole al
       usuario que lo ha reportado que lo pruebe. A continuacion fija el
       estado del PR en Patch Ready.

     * Un par de interaciones mas tarde tanto Joe como el usuario que lo ha
       creado estan satisfechos con el parche y Joe realiza el commit a
       -CURRENT (o directamente a -STABLE si el problema no existe en
       -CURRENT), asegurandose de hacer referencia al informe de problemas en
       su log del commit (y dando el credito al usuario si envio todo o parte
       del parche) y, si corresponde, iniciara una cuenta atras de MFC. El
       error se fija en el estado Needs MFC.

     * Si el parche no necesita pasar por un MFC Joe cierra el PR con el
       estado Issue Resolved.

  Nota:

   Muchos PRs se envian con muy poca informacion sobre el problema y algunos
   son muy complejos de resolver, o simplemente aranan la superficie de un
   problema mayor; en estos casos es muy importante conseguir toda la
   informacion necesaria para resolver el problema. Si el problema no se
   puede resolver o si el problema se repite, es necesario volver a abrir el
   PR.

3. Estados de los informes de problemas

   Es importante actualizar el estado de un PR cuando se llevan a cabo
   ciertas acciones.

   Ejemplo 1. Un ejemplo simple de cuando cambiar el estado de un PR.

   Cuando un PR se haya gestionado y el/los desarrollador/es esten
   satisfechos con la solucion se envia un follow-up al PR y su estado
   cambiara a "feedback". En este punto el usuario que lo ha creado debe
   evaluar la solucion en su contexto y responder indicando si el defecto ha
   sido solucionado.

   Un informe de problemas puede estar en uno de los siguientes estados:

   open

           Estado inicial: el problema ha sido reportado y necesita ser
           revisado.

   analyzed

           El problema consta como revisado y se esta buscando una solucion.

   feedback

           Hay que realizar trabajos adicionales que requieren mas
           informacion del usuario o de la comunidad; es posible que haga
           falta tambien mas informacion sobre la solucion propuesta.

   patched

           Se ha realizado un commit con el parche, pero aun hay algo
           pendiente (MFC o tal vez confirmacion del usuario que lo creo).

   suspended

           No se esta trabajando en el problema debido a la falta de
           informacion o recursos. Este es un candidato excelente para
           alguien que este buscando un proyecto. Si el problema no se puede
           resolver se cerrara en lugar de suspenderse. El proyecto de
           documentacion utiliza "suspended" para los elementos de la
           "wish-list" que implican una cantidad significativa de trabajo
           para el cual nadie dispone de tiempo.

   closed

           Un informe de problemas se cierra cuando se han integrado,
           documentado y probado los cambios o cuando se abandona la solucion
           del problema.

  Nota:

   El estado "patched" esta directamente relacionado con el feedback, por lo
   que puede ir directamente al estado "closed" si el usuario que lo creo no
   puede probar el parche y funciona en sus propias pruebas.

4. Tipos de informes de problemas

   Al tratar con informes de problemas, ya sea como desarrollador que tiene
   acceso directo a la base de datos de informes de problemas o como
   colaborador que navega por la base de datos y envia follow-ups con
   parches, comentarios, sugerencias o solicitudes de cambio, va a
   encontrarse usted con distintos tipos de PRs.

     * PRs que todavia no estan asignados a nadie

     * PRs asignados a alguien

     * Duplicados de PRs existentes

     * PRs obsoletos

     * PRs que no estan relacionados con errores

   Las siguientes secciones describen para que se usa cada tipo de PRs,
   cuando un PR pertenece a uno de estos tipos y que tratamiento recibe cada
   tipo.

  4.1. PRs sin asignar

   Cuando los PRs llegan se asignan en primer lugar a un responsable generico
   (placeholder). Estos siempre tienen el prefijo freebsd-. El valor exacto
   para este patron depende de la categoria. En la mayoria de los casos
   corresponde a una lista de correo especifica de FreeBSD. Esta es una lista
   actualizada con los mas comunes en primer lugar:

   Tabla 1. Asignaciones predeterminadas - mas comunes

   +------------------------------------------------------------------------+
   |         Tipo          |        Categorias         |     Asignacion     |
   |                       |                           |   predeterminada   |
   |-----------------------+---------------------------+--------------------|
   | sistema base          | bin, conf, gnu, kern,     | freebsd-bugs       |
   |                       | misc                      |                    |
   |-----------------------+---------------------------+--------------------|
   | arquitectura          | alpha, amd64, arm, i386,  | freebsd-arch       |
   | especifica            | ia64, powerpc, sparc64    |                    |
   |-----------------------+---------------------------+--------------------|
   | coleccion de ports    | ports                     | freebsd-ports-bugs |
   |-----------------------+---------------------------+--------------------|
   | documentacion enviada | docs                      | freebsd-doc        |
   | junto con el sistema  |                           |                    |
   |-----------------------+---------------------------+--------------------|
   | paginas web de        |                           |                    |
   | FreeBSD (sin incluir  | sitio web                 | freebsd-www        |
   | docs)                 |                           |                    |
   +------------------------------------------------------------------------+

   Tabla 2. Asignaciones predeterminadas - otros

   +------------------------------------------------------------------------+
   |             Tipo              | Categorias | Asignacion predeterminada |
   |-------------------------------+------------+---------------------------|
   | labores de promocion          | promocion  | freebsd-advocacy          |
   |-------------------------------+------------+---------------------------|
   | problemas con la Java Virtual | java       | freebsd-java              |
   | Machine(TM)                   |            |                           |
   |-------------------------------+------------+---------------------------|
   | cumplimiento de estandares    | estandares | freebsd-standards         |
   |-------------------------------+------------+---------------------------|
   | bibliotecas de threading      | threads    | freebsd-threads           |
   |-------------------------------+------------+---------------------------|
   | subsistema usb(4)             | usb        | freebsd-usb               |
   +------------------------------------------------------------------------+

   Es bastante habitual que el usuario responsable del PR lo asigne a la
   categoria incorrecta. Si usted corrige la categoria recuerde por favor que
   hay que corregir tambien la asignacion. Nuestros usuarios parecen tener
   dificultades en particular con el hecho de que aunque su problema ocurra
   en un sistema i386 podria afectar a todas las plataformas de FreeBSD y por
   lo tanto ser mas adecuado para kern. Lo contrario tambien sucede, por
   supuesto.

   Cualquiera puede reasignar estos PR de sus responsables genericos a otra
   persona en grupo. Hay varios tipos de responsables: listas de correo
   especializadas, alias de correo (utilizados para asuntos muy especificos)
   de interes limitado) e individuos.

   Para los responsables que son listas de correo utilice la designacion
   larga al realizar la asignacion: por ejemplo, freebsd-foo en lugar de foo.
   Asi evitara los correos electronicos duplicados enviados a las listas de
   distribucion.

  Nota:

   Como la lista de personas que se han ofrecido voluntarias para ser los
   responsables predeterminados para ciertos tipos de PRs cambia con bastante
   frecuencia es mucho mas adecuado recurrir a la wiki de FreeBSD.

   A continuacion hay un listado con ejemplos de dichas entidades. Es
   probable que el listado no sea exhaustivo.

   Tabla 3. Responsables comunes - sistema base

   +-------------------------------------------------------------------------+
   |            Tipo            |Categoria| Responsable sugerido |  Tipo de  |
   |                            |sugerida |                      |responsable|
   |----------------------------+---------+----------------------+-----------|
   |problema especifico de la   |arm      |freebsd-arm           |lista de   |
   |arquitectura ARM(R).        |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema especifico de la   |kern     |freebsd-mips          |lista de   |
   |arquitectura MIPS(R)        |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema especifico de la   |kern     |freebsd-ppc           |lista de   |
   |arquitectura PowerPC(R)     |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con la interfaz    |         |                      |lista de   |
   |avanzada de configuracion y |kern     |freebsd-acpi          |correo     |
   |energia (acpi(4))           |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema con los            |         |                      |           |
   |controladores del modo de   |kern     |freebsd-atm           |lista de   |
   |transferencia asincrono     |         |                      |correo     |
   |(ATM)                       |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problemas con sistemas      |         |                      |           |
   |FreeBSD embebidos o de      |         |                      |lista de   |
   |small-footprint (por        |kern     |freebsd-embedded      |correo     |
   |ejemplo,                    |         |                      |           |
   |NanoBSD/PicoBSD/FreeBSD-arm)|         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema con los            |kern     |freebsd-firewire      |lista de   |
   |controladores de FireWire(R)|         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el codigo      |         |                      |lista de   |
   |fuente del sistema de       |kern     |freebsd-fs            |correo     |
   |archivos                    |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema  |kern     |freebsd-geom          |lista de   |
   |geom(4)                     |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema  |kern     |freebsd-ipfw          |lista de   |
   |ipfw(4)                     |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con los            |         |                      |           |
   |controladores de la red     |kern     |freebsd-isdn          |lista de   |
   |digital de servicios        |         |                      |correo     |
   |integrados (ISDN)           |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |subsistema jail(8)          |kern     |freebsd-jail          |lista de   |
   |                            |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con la emulacion   |kern     |freebsd-emulation     |lista de   |
   |Linux(R) o SVR4             |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el stack de red|kern     |freebsd-net           |lista de   |
   |                            |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema  |kern     |freebsd-pf            |lista de   |
   |pf(4)                       |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema  |kern     |freebsd-scsi          |lista de   |
   |scsi(4)                     |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema  |kern     |freebsd-multimedia    |lista de   |
   |sound(4)                    |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con el subsistema y|         |                      |lista de   |
   |controladores wireless      |kern     |freebsd-wireless      |correo     |
   |wlan(4)                     |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema con sysinstall(8) o|bin      |freebsd-sysinstall    |lista de   |
   |bsdinstall(8)               |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con los scripts de |kern     |freebsd-rc            |lista de   |
   |inicio del sistema (rc(8))  |         |                      |correo     |
   |----------------------------+---------+----------------------+-----------|
   |problema con la             |         |                      |lista de   |
   |funcionalidad VIMAGE o VNET |kern     |freebsd-virtualization|correo     |
   |y el codigo relacionado     |         |                      |           |
   |----------------------------+---------+----------------------+-----------|
   |problema con la emulacion de|kern     |freebsd-xen           |lista de   |
   |Xen                         |         |                      |correo     |
   +-------------------------------------------------------------------------+

   Tabla 4. Responsables comunes - colecion de ports

   +------------------------------------------------------------------------+
   |            Tipo            | Categoria |   Responsable   |   Tipo de   |
   |                            | sugerida  |    sugerido     | responsable |
   |----------------------------+-----------+-----------------+-------------|
   | problema con el framework  |           |                 |             |
   | de ports (!no con un port  | ports     | portmgr         | alias       |
   | en concreto!)              |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | apache          | lista de    |
   | apache@FreeBSD.org         |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | autotools       | alias       |
   | autotools@FreeBSD.org      |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | doceng          | alias       |
   | doceng@FreeBSD.org         |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-eclipse | lista de    |
   | eclipse@FreeBSD.org        |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | gecko           | lista de    |
   | gecko@FreeBSD.org          |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | gnome           | lista de    |
   | gnome@FreeBSD.org          |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | hamradio        | alias       |
   | hamradio@FreeBSD.org       |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | haskell         | alias       |
   | haskell@FreeBSD.org        |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-java    | lista de    |
   | java@FreeBSD.org           |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | kde             | lista de    |
   | kde@FreeBSD.org            |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | mono            | lista de    |
   | mono@FreeBSD.org           |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-office  | lista de    |
   | office@FreeBSD.org         |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | perl            | lista de    |
   | perl@FreeBSD.org           |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-python  | lista de    |
   | python@FreeBSD.org         |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-ruby    | lista de    |
   | ruby@FreeBSD.org           |           |                 | correo      |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | secteam         | alias       |
   | secteam@FreeBSD.org        |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | vbox            | alias       |
   | vbox@FreeBSD.org           |           |                 |             |
   |----------------------------+-----------+-----------------+-------------|
   | port mantenido por         | ports     | freebsd-x11     | lista de    |
   | x11@FreeBSD.org            |           |                 | correo      |
   +------------------------------------------------------------------------+

   Los PRs relacionados con los ports que tienen un maintainer que es a la
   vez un committer de ports pueden ser reasignados por cualquiera, pero es
   importante recordar que no todos los committers de FreeBSD tienen un
   commit bit de ports, por lo que no puede guiarse unicamente por la
   direccion de correo electronico.

   En el caso de otros PRs por favor no los reasigne a otros individuos (que
   no sean usted) a menos que este seguro de que el responsable realmente
   quiere estar al tanto del PR. Esto ayudara a evitar situaciones en las que
   nadie se dedica a solucionar un problema en particular porque todo el
   mundo implicado asume que el responsable ya esta en ello.

   Tabla 5. Responsables comunes - otros

   +------------------------------------------------------------------------+
   |              Tipo              | Categoria | Responsable |   Tipo de   |
   |                                | sugerida  |  sugerido   | responsable |
   |--------------------------------+-----------+-------------+-------------|
   | problema con la base de datos  | bin       | bugmeister  | alias       |
   | de PR                          |           |             |             |
   |--------------------------------+-----------+-------------+-------------|
   | problema con el formulario web | doc       | bugmeister  | alias       |
   | de Bugzilla.                   |           |             |             |
   +------------------------------------------------------------------------+

  4.2. PRs asignados

   Si un PR tiene el campo responsible establecido con el nombre de usuario
   de un desarrollador de FreeBSD significa que el PR se ha entregado a esa
   persona en particular para que desarrolle sobre el trabajo adicional.

   Los PRs asignados no deben ser modificados por nadie mas que el
   responsable o el bugmeister. Si tiene algun comentario que hacer al
   respecto envie un follow-up. Si por algun motivo cree que el PR debe
   cambiar de estado o reasignarse envie un mensaje al responsable. Si el
   responsable no responde en dos semanas anule la asignacion del PR y haga
   lo que estime conveniente.

  4.3. PRs duplicados

   Si encuentra mas de un PR que describe el mismo problema elija el que
   contiene la mayor cantidad de informacion util y cierre los demas
   indicando claramente el numero de PR sustituidos. Si varios PRs contienen
   informacion util que no esta repetida envie toda la informacion restante
   en un follow-up, incluidas las referencias a los demas. Cierre despues los
   otros PRs una vez hayan sido completamente reemplazados.

  4.4. PRs obsoletos

   Un PR se considera obsoleto si no ha sido modificado en mas de seis meses.
   Siga el siguiente procedimiento para gestionar PRs obsoletos:

     * Si el PR contiene suficientes detalles intente reproducir el problema
       en -CURRENT y en -STABLE. Si logra reproducir el problema envie un
       follow-up detallando sus hallazgos e intente encontrar a alguien a
       quien asignarselo. Establezca el estado en "analyzed" si ese es el
       caso.

     * Si el PR describe un problema que sabe que es el resultado de un error
       de uso (configuracion incorrecta o de otro tipo) envie un follow-up
       que explique que hizo mal el usuario. Mas tarde cierre el PR con el
       motivo "User error" o "Configuration error".

     * Si el PR describe un error que sabe que ha sido corregido tanto en
       -CURRENT como en -STABLE cierrelo con un mensaje que indique cuando se
       soluciono en cada rama.

     * Si el PR trata de un error que sabe que ha sido corregido en -CURRENT
       pero no en -STABLE intente averiguar cuando espera la persona que lo
       corrigio ejecutar el MFC, o intente encontrar a alguien mas (quizas
       usted mismo) que pueda hacerlo. Establezca el estado en "patched" y
       asignelo a quien quiera que se haya encargado de hacer el MFC.

     * En cualquier otro caso solicite al usuario que confirme si el problema
       persiste en las versiones mas recientes. Si el usuario no responde en
       un mes cierre el PR con la anotacion "Feedback timeout".

  4.5. PRs sin errores

   Los desarrolladores que encuentren PRs que han aparecido ya en
   freebsd-bugs o alguna otra lista deberian cerrar el PR informando al
   usuario en un comentario por que el problema reportado no es realmente un
   PR y donde debe publicarse el mensaje.

   Las direcciones de correo electronico que utiliza Bugzilla para recibir
   los PR se publican en la documentacion de FreeBSD y se anuncian y publican
   en el sitio web. Esto significa que los spammers ya las tienen.

   Cuando cierre uno de estos PRs, haga lo siguiente:

     * Establezca el componente en junk (en Supporting Services).

     * Establezca como responsable a nobody@FreeBSD.org.

     * Establezca el estado en Issue Resolved.

   Establecer la categoria en junk indica que no hay contenido util dentro
   del PR y ayuda a reducir el desorden en las categorias principales.

5. Lecturas adicionales

   Esta es una lista de recursos relevantes para la correcta escritura y
   procesamiento de informes de problemas. De ninguna manera debe
   considerarse completa.

     * Como escribir informes de problemas para FreeBSD - directrices para
       los usuarios que envian un PR.
