4. Escribiendo el informe de problemas

Ahora que ha decidido que su problema merece un informe de problemas y que es un problema de FreeBSD, es el momento de escribir el informe de problemas propiamente dicho. Antes de pasar a describir los mecanismos utilizados por el programa encargado de generar y enviar los PRs, aquí hay algunos consejos y trucos para ayudarle a asegurarse de que su PR sea más efectivo.

4.1. Consejos y trucos para escribir un buen informe de problemas

  • No deje el campo Summary vacío. Los PRs se envían a una lista de correo global (donde se utiliza el campo Summary para la línea Subject:), y se almacenan en una base de datos. Cualquiera que haga una búsqueda por el campo synopsis (sinopsis) en la base de datos y encuentre un PR con la línea del subject (asunto) en blanco tiende a omitirlo. Recuerde que los PR permanecen en esta base de datos hasta que alguien los cierra; un PR que no esté debidamente cumplimentado pasará desapercibido.

  • Rellene el campo Summary correctamente, no use descripciones vagas. No asuma que aquella persona que lea su PR entienda el contexto que motivó su envío, por lo tanto, cuanta más información proporcione, mejor. Por ejemplo, ¿en qué parte del sistema se produce el problema? ¿El problema sucede solo durante la instalación o durante la ejecución del sistema? Por ejemplo, en lugar de, Summary: portupgrade is broken, podría utilizar este otro, el cual, tiene mucha más información: Summary: port ports-mgmt/portupgrade coredumps on -current. (En el caso de los ports, es especialmente útil tener el nombre de la categoría y el nombre del port en el campo Summary).

  • Si tiene un parche, dígalo. Es más probable que se analice un PR con un parche incluido que uno sin él. Incluya la palabra clave patch en Bugzilla.

  • Si es un maintainer, dígalo. Si mantiene una parte del código fuente (por ejemplo, un port que ya exista), debe establecer el campo Class de su PR a maintainer-update. De esta forma, cualquier committer que se ocupe de su PR no tendrá que verificarlo.

  • Sea concreto. Cuanta más información se proporcione sobre el problema que tiene, más posibilidades de obtener una respuesta.

    • Incluya la versión de FreeBSD que está ejecutando (existe un lugar donde escribir esta información, vea a continuación) y en qué arquitectura. Debe incluir si se está ejecutando desde una release (por ejemplo, desde un CD-ROM o descarga), o si es desde un sistema mantenido por Subversion (y, si es así, en qué número de revisión se encuentra). Si está usando la rama FreeBSD-CURRENT, esa es la primera pregunta que le harán, porque las correcciones (especialmente para problemas de alto nivel) tienden a aplicarse muy rápidamente, y se espera que los usuarios de FreeBSD-CURRENT se mantengan al día.

    • Incluya qué opciones globales ha especificado en sus ficheros make.conf, src.conf y src-env.conf. Dado el número infinito de opciones, no todas las combinaciones pueden ser totalmente compatibles.

    • Si el problema se puede reproducir fácilmente, incluya información que ayude al desarrollador a reproducirlo por sí mismo. Si se puede hacer una demostración con una entrada específica, incluya un ejemplo con esa entrada, si es posible, e incluya la salida real y la esperada. Si la información es grande o no se puede hacer pública, intente crear un archivo con lo mínimo que muestre el mismo problema y que pueda incluirse en el PR.

    • Si se trata de un problema del kernel, prepárese para proporcionar la siguiente información. (No es necesario incluir esta información por defecto, puesto que lo único que produce es un crecimiento desmesurado de la base de datos, pero sí puede merecer la pena incluir extractos que usted considere importantes):

      • la configuración del kernel (incluidos los dispositivos de hardware que ha instalado)

      • si tiene o no opciones de depuración activadas (como WITNESS), y si es así, si el problema persiste cuando se cambia el valor de dichas opciones

      • el texto completo de cualquier backtrace, panic u otra salida por consola, o entradas en /var/log/messages, si se generó alguna

      • la salida de pciconf -l y partes relevantes de su salida dmesg si su problema se relaciona con una pieza específica de hardware

      • el hecho de que haya leído src/UPDATING y que su problema no esté listado (seguro que alguien le preguntará sobre este punto)

      • si puede o no ejecutar otro kernel de respaldo sin problemas (se trata de descartar problemas relacionados con el hardware, como discos con errores o CPUs con sobrecalentamiento, que pueden confundirse fácilmente con problemas del kernel)

    • Si se trata de un problema relacionado con los ports, prepárese para poder proporcionar la información que se muestra a continuación. (No es necesario incluir esta información por defecto, ya que esto solo produce un crecimiento indeseado de la base de datos, pero debe incluir extractos que considere que pueden ser relevantes):

      • Qué ports ha instalado

      • Cualquier variable de entorno que sobrescriba los valores por defecto del archivo bsd.port.mk, como PORTSDIR

      • El hecho de que ha leído el archivo ports/UPDATING y que su problema no se encuentra en la lista (puede preguntar a alguien)

  • Evitar peticiones de características vagas. Los PRs del estilo alguien debería implementar algo que haga esto, aquello y lo de más allá son informes con pocas probabilidades de obtener resultados positivos. Recuerde, el código fuente se encuentra disponible para todo el mundo, por lo tanto, si desea una característica, ¡la mejor manera de asegurarse de que se incluya es ponerse a trabajar en ella! También tenga en cuenta que para discutir este tipo de problemas resulta más adecuado utilizar la lista freebsd-questions, que una entrada en la base de datos de PR, como ya se ha comentado anteriormente.

  • Asegúrese que nadie más ha enviado un PR similar. Aunque esto ya se ha mencionado anteriormente, vale la pena repetirlo aquí. Solamente lleva uno o dos minutos utilizar el motor de búsqueda web en https://bugs.freebsd.org/bugzilla/query.cgi. (Por supuesto, todo el mundo es culpable de olvidarse de hacerlo de vez en cuando).

  • Informe un solo problema por informe. Evite incluir dos o más problemas dentro del mismo informe, a menos que estén relacionados. Al enviar parches, evite agregar múltiples funciones o corregir varios errores en el mismo PR, a menos que estén estrechamente relacionados — ya que los PR suelen tardar más en resolverse.

  • Evite peticiones controvertidas. Si su PR se dirige a un área que ha sido controvertida en el pasado, probablemente debería estar preparado para no solo ofrecer parches, sino también una justificación de por qué los parches son la forma correcta de hacerlo. Como se avisó anteriormente, una búsqueda meticulosa en las listas de correo utilizando los archivos históricos en https://www.FreeBSD.org/search/search.html#mailinglists es siempre una buena opción.

  • Sea educado. Practicamente cualquier persona que se encargue de tratar su PR es un voluntario. A nadie le gusta que le digan que tiene que hacer algo cuando ya lo están haciendo por alguna otra motivación que no sea la económica. Es bueno tenerlo en cuenta en todo momento en los proyectos de código abierto.

4.2. Antes de comenzar

Se aplican consideraciones similares al uso del formulario de envío de PR por la aplicación web. Tenga cuidado con las operaciones de cortar y pegar que puedan cambiar los espacios en blanco u otro formato de texto.

Finalmente, si el envío es largo, prepare el trabajo sin conexión, de forma que no se pierda nada si hay un problema al enviarlo.

4.3. Adjuntar parches o archivos

Al adjuntar un parche, asegúrese de usar svn diff o diff(1) con el argumento -u para crear un diff unificado, y asegúrese de especificar el número de revisión SVN del repositorio contra el que modificó los archivos, para que los desarrolladores que lean su informe puedan aplicarlos fácilmente. Para problemas relacionados con el kernel o utilidades del sistema base, se prefiere un parche contra FreeBSD-CURRENT (la rama HEAD de Subversion), ya que todo el código nuevo debe aplicarse y probarse allí primero. Después de que se hayan realizado las pruebas adecuadas o importantes, se hará el merge/migración a la rama FreeBSD-STABLE.

Si adjunta un parche como parte del mensaje, en lugar de como adjunto, tenga en cuenta que uno de los problemas más comunes es la tendencia de algunos programas de correo electrónico de mostrar las tabulaciones como espacios, lo cual estropeará por completo todo lo que pretenda que forme parte de un Makefile.

No envíe parches como archivos adjuntos usando Content-Transfer-Encoding: quoted-printable. Esto escapará el carácter (character escaping) y todo el parche será inútil.

También tenga en cuenta que, incluir pequeños parches en un PR, en general, está bien, especialmente cuando soluciona el problema descrito en el PR, los parches grandes y especialmente el nuevo código que pueda requerir una revisión sustancial antes de realizar el commit deben colocarse en un servidor web o ftp, y la URL debe incluirse en el PR en lugar del parche. Los parches en el correo electrónico tienden a ser destrozados, y cuanto más grande sea el parche, más difícil será para las partes interesadas desenmarañarlo. Además, la publicación de un parche en la web le permite modificarlo sin tener que volver a enviar el parche completo en un follow-up al PR original. Finalmente, los parches grandes simplemente aumentan el tamaño de la base de datos, ya que los PR cerrados no se eliminan, sino que se guardan y simplemente se marcan como completos.

También debe tener en cuenta que, a menos que se especifique explícitamente lo contrario en su PR o en el propio parche, se asumirá que los parches que envíe se licenciarán en los mismos términos que el archivo original que modificó.

4.4. Rellenar el formulario

Nota:

La dirección de correo electrónico que utilice pasará a ser pública y podrá estar disponible para los spammers. Debe tener implementados procedimientos de manejo de spam o usar una cuenta de correo electrónico temporal. Sin embargo, tenga en cuenta que si no utiliza una cuenta de correo electrónico válida, no podremos hacerle preguntas sobre su PR.

Cuando presente un error, encontrará los siguientes campos:

  • Synopsis: Rellene este campo con una descripción corta y precisa del problema. El campo debe ser rellenado en inglés, pues es el idioma de comunicación en el proyecto FreeBSD. La sinopsis se utiliza como subject del correo electrónico del informe de problemas, y también se utiliza en los listados y resúmenes de informes de la base de datos; informes de problemas con vagas sinopsis tienden a ser completamente ignorados.

  • Severity: Escoga una de las opciones, Affects only me (Solo me afecta a mi), Affects some people (Afecta a algunas personas) o Affects many people (Afecta a muchas personas). No sea exagerado; absténgase de etiquetar su problema Affects many people (Afecta a muchas personas) a menos que realmente lo haga. Los desarrolladores de FreeBSD no trabajarán en su problema más rápido si infla su importancia, ya que muchas otras personas han hecho exactamente lo mismo.

  • Category: Elija una categoría apropiada.

    Lo primero que debe hacer es decidir en qué parte del sistema se encuentra su problema. Recuerde, FreeBSD es un sistema operativo completo, instala un kernel, la biblioteca estándar, muchos controladores de periféricos y un gran número de utilidades (el sistema base). Sin embargo, hay miles de aplicaciones adicionales en la colección de ports. Primero deberá decidir si el problema está en el sistema base o en algo instalado a través de la colección de ports.

    Aquí una descripción de las principales categorías:

    • Si hay un problema con el kernel, las bibliotecas (como la biblioteca estándar de C libc) o en un controlador de un periférico en el sistema base, en general, utilizará la categoría kern. (Hay algunas excepciones; vea más abajo). En general, estas son las cosas que se describen en la sección 2, 3 ó 4 de las páginas del manual.

    • Si el problema es con un binario como sh(1) o mount(8), primero deberá determinar si estos programas se encuentran en el sistema base o se añadieron a través de la colección de ports. Si no está seguro, puede hacer whereis programname. La convención de FreeBSD para la colección de ports es instalar todo por debajo de /usr/local, aunque un administrador del sistema puede sobreescribirlo. Para estos, utilizará la categoría de ports (sí, incluso si la categoría del port es www; vea más abajo). Si la ubicación es /bin, /usr/bin, /sbin, o /usr/sbin, es parte del sistema base, y debe usar la categoría bin. Estas son todas las cosas que se describen en las secciones 1 u 8 de las páginas del manual.

    • Si cree que el error está en los scripts de inicio (rc), o en algún otro tipo de archivo de configuración no ejecutable, entonces la categoría correcta es conf (configuración). Estas son las cosas que se describen en la sección 5 de las páginas del manual.

    • Si ha encontrado un problema en el conjunto de la documentación (artículos, libros, man pages) o en el sitio web, la elección correcta es docs.

      Nota:

      Si tiene un problema con un port llamado www/algunnombredeport, esto entra en la categoría de ports.

    Hay algunas categorías más especializadas.

    • Si el problema se catalogará en kern pero estuviera relacionado con el subsistema USB, la elección correcta es usb.

    • Si el problema se catalogará en kern pero estuviera relacionado con las bibliotecas de threading, la elección correcta es threads.

    • Si el problema se catalogará en el sistema base, pero estuviera relacionado con nuestra interpretación de estándares, como POSIX®, la elección correcta es standards.

    • Si está convencido de que el problema solo ocurrirá con la arquitectura del procesador que está utilizando, seleccione una de las categories específicas de la arquitectura: normalmente, i386 para ordenadores compatibles con Intel en modo 32 bits; amd64 para máquinas AMD que se ejecutan en modo 64 bits (esto también incluye ordenadores compatibles con Intel que se ejecutan en modo EMT64); y las menos comunes, arm o powerpc.

      Nota:

      Estas categorías se utilizan con frecuencia para los problemas No lo sé. En lugar de suponer, utilice misc.

      Ejemplo 1. Uso correcto de la categoría de arquitectura específica

      Tiene un ordenador común (PC-based machine), y cree que ha encontrado un problema específico para un conjunto de chips o una placa base en particular: i386 es la categoría correcta.


      Ejemplo 2. Uso incorrecto de la categoría de arquitectura específica

      Está teniendo un problema con una tarjeta periférica adicional en un bus común, o un problema con un tipo particular de unidad de disco duro: en este caso, probablemente afecte a más de una arquitectura, y kern es la categoría correcta.


    • Si realmente no sabe dónde está el problema (o la explicación no parece encajar en los anteriores), use la categoría misc. Antes de hacerlo, es posible que primero desee solicitar ayuda en la lista de correo de preguntas generales de FreeBSD. Es posible que le indiquen que una de las categorías ya existentes es mejor opción.

  • Environment: Esto debe describir, con la mayor precisión posible, el entorno en el que se ha observado el problema. Esto incluye la versión del sistema operativo, la versión del programa o archivo específico que contiene el problema y cualquier otro elemento relevante como la configuración del sistema, otro software instalado que influya en el problema, etc. — simplemente todo lo que un desarrollador necesita saber para reconstruir el entorno en el que se produce el problema.

  • Description: Una descripción completa y precisa del problema que está experimentando. Intente evitar especular sobre las posibles causas del problema a menos que se tenga la seguridad de que el camino descrito es el correcto, ya que puede inducir a un desarrollador a hacer suposiciones incorrectas sobre el problema. Debe incluir las acciones que hay que realizar para reproducir el problema. Si conoce alguna solución, inclúyala. No solo ayuda a otras personas con el mismo problema a solucionarlo, sino que también puede ayudar a un desarrollador a entender la causa del problema.

Puede descargar éste y muchos otros documentos desde ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

Si tiene dudas sobre FreeBSD consulte la documentación antes de escribir a la lista <questions@FreeBSD.org>.

Envíe sus preguntas sobre la documentación a <doc@FreeBSD.org>.