Ahora que hemos determinado que el problema que estamos experimentando se merece la redacción de un informe de problemas y que se trata de un problema de FreeBSD, es la hora de comenzar a escribir dicho informe. Antes de pasar a describir los mecanismos utilizados por el programa encargado de generar los informes PR, vamos a describir una serie de trucos y consejos que nos asegurarán la mayor efectividad posible de nuestro informe.
No deje la línea de “Synopsis”
vacía. Los PRs se dirigen tanto a una lista de
correo mundial (donde se utiliza el campo
“Synopsis” para rellenar la línea
Subject:
del correo) como a una base
de datos (GNATS). Cualquier persona que consulte la base
de datos por el campo sinopsis
y encuentre un
PR con una línea de Asunto
vacía
tiende simplemente a pasar por alto el informe. Recuerde que un
PR permanece en la base de datos hasta que alguien se encarga de
cerrar el informe; un informe anónimo normalmente se
perderá para siempre entre el ruido y tardará mucho
en cerrarse.
Evite utilizar una línea de
“Synopsis” débil.. No debe
suponerse que quien lea el PR conoce el contexto adecuado en el
que su mensaje tiene sentido, así que cuanta más
información se proporcione, mejor que mejor.
Por ejemplo, ?qué parte del sistema se ve afectado
por el informe?, ?el problema aparece cuando se está
instalando o cuando se está ejecutando?. Para
ejemplificar, en lugar de Synopsis: portupgrade is
broken
, se pueden ver las ventajas que
proporciona una línea como la siguiente:
Synopsis: port sysutils/portupgrade produce un
coredump en -current
. (En el caso concreto de
los ports, resulta especialmente útil poseer tanto la
categoría como el nombre del port en la línea
“Synopsis”.)
Si se dispone de un parche, dígalo.
Un PR con un parche incluido tiene muchas más
posibilidades de ser tratado que uno que no lo tiene. Si
se include dicho parche, escriba la cadena
[patch]
al comienzo de la línea
“Synopsis”. (Aunque no es obligatorio
utilizar dicha cadena, se trata de un estándar de facto
que se utiliza de forma mayoritaria.)
Si es mantenedor del port, dígalo.
Si se está manteniendo el código fuente de una
aplicación (por ejemplo, de un port), se puede
considerar la adición de la cadena
[maintainer update]
al comienzo de la
línea de sinopsis, y además se debería
asignar el campo “Class” del PR a la cadena
maintainer-update
. De esta forma
cualquier committer que maneje el PR no tendrá que
realizar comprobaciones.
Sea concreto. Cuanta más información se proporcione sobre el problema que se tiene, más posiblidades de obtener una respuesta.
Incluya la versión del FreeBSD que se está ejecutando (existe un lugar donde escribir esta esta información, vea más abajo) y en qué arquitectura. Se debe incluir si se está ejecutando desde una release (e.g. desde un CDROM o descarga), o si es desde un sistema mantenido mediante cvsup(1) (y, si esto último se cumple, con qué frecuencia se realiza la actualización). Si se está siguiendo la rama FreeBSD-CURRENT, se trata de la primera pregunta que nos harán, debido a que los parches (sobre todo para problemas de alto nivel) tienden a aplicarse muy rápidamente, y se espera de los usuarios de FreeBSD-CURRENT un seguimiento cercano de las actualizaciones aplicadas.
Incluya qué opciones globales se han especificado
en el archivo make.conf
. Aviso:
Es bien conocido por todos que especificar
-O2
y valores superiores para
gcc(1) produce fallos y resulta ser proclive a
errores en muchas situaciones. Aunque los
desarrolladores de FreeBSD normalmente dan por buenos y
aceptan los parches proporcionados por el creador del
informe de problemas, normalmente no desean investigar
dichas condiciones extrañas debido simplemente a la
falta de tiempo y de voluntarios, y puede que
respondan diciendo simplemente que dicha opción de
compilación no se encuentra soportada.
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 GNATS, pero sí puede merecer la pena incluir resúmenes que usted considere importantes):
La configuración del kernel (incluyendo los dispositivos hardware que se tienen instalados)
Si se tienen opciones de depuración activadas
(tales como WITNESS
), y en tal
caso, si el problema persiste cuando se cambia el
valor de dichas opciones
Una traza de depuración, si se pudo generar.
El hecho de que se ha leido detenidamente el
archivo src/UPDATING
para
constatar que el problema no se ha identificado
allí (se garantiza que alguién le
preguntará sobre este punto)
Si se puede o no se puede ejecutar otro kernel sin problemas (se trata de identificar problemas relacionados con el hardware como discos con errores o CPUs sobrecalentadas, 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 sólo produce un crecimiento indeseado de la base de datos, pero sí se pueden incluir resúmenes de aquellos datos que usted considere relevantes):
Los ports que se tiene instalados
Cualesquiera variables de entorno que
sobreescriban los valores por defecto del archivo
bsd.port.mk
, tales como
PORTSDIR
El hecho de que se ha leido
ports/UPDATING
y que nuestro
problema no se encuentra identificado en dicho
archivo (se garantiza que alguien puede preguntar
este hecho).
Evitar peticiones de características
vagas. Los PRs del estilo de
“alguien debería implementar algo que haga
esto y aquello y lo de más allá” son
informes con pocas probabilidades de obtener resultados
positivos. Las características deben ser muy concretas y
específicas. Recuerde que el código fuente se
encuentra disponible para todo el mundo, de tal forma que si usted
necesita una característica, la mejor forma de verla
incluida en futuras versiones de la herramienta consiste
en ponerse usted mismo a trabajar sobre ella, manos a la
obra. También tenga en cuenta que para discutir este tipo
de problemas resulta más adecuado utilizar la lista
freebsd-questions
, como ya se ha
comentado anteriormente.
Asegúrese que nadie más ha enviado un PR similar. Aunque esto ya se ha mencionado anteriormente, merece la pena que se repita en este punto. Sólamente lleva uno o dos minutos realizar una búsqueda basada en un motor web en http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query. (Por supuesto, a todo el mundo se le puede olvidar realizar esto de vez en cuando, pero por esa misma razón merece la pena hacer incapié en ello)
Evite peticiones controvertidas. Si nuestro PR se dirige hacia un área o tema controvertido en el pasado, debemos prepararnos no sólo a ofrecer parches, si no también a justificar por qué motivo los parches proporcionados son la “Forma Correcta de Hacerlo”. Como se avisó anteriormente, una búsqueda meticulosa en las listas de correo en los archivos históricos sitos en http://www.FreeBSD.org/search/search.html#mailinglists resulta siempre una buena idea y sirve para preparar nuestro razonamiento y aprender de la experiencia y de las decisiones tomadas en el pasado.
Sea educado. Casi cualquier persona que se encarge de tratar nuestro informe de problemas trabajará en el como un voluntario. A nadie le gusta que le digan cómo hacer las cosas cuando ya se están haciendo de una forma determinada, especialmente cuando la motivación para realizarlas no es monetaria. Este hecho es bueno tenerlo en mente y aplicarlo para cualquier proyecto de Software Libre.
Antes de ejecutar el programa send-pr(1), asegúrese
de que la variable de entorno VISUAL
(o
EDITOR
si la variable VISUAL
no
se encuentra definida) se encuentra apuntando a algo con
sentido.
Es importante comprobar que la entrega de correo funciona correctamente. send-pr(1) utiliza mensajes de correo para enviar y realizar un seguimiento de los informes de problemas. Si no se puede generar correo electrónico desde la máquina en la que se ejecuta send-pr(1), el informe jamás llegará a la base de datos GNATS. Si quiere saber más sobre la configuración del correo en FreeBSD consulte el capítulo de “Correo Electrónico” del manual de FreeBSD en .
El programa send-pr(1) posee la capacidad de adjuntar
archivos al informe de problemas. Se pueden adjuntar tantos
archivos como se quiera siempre y cuando se utilice un nombre
distinto para cada archivo (e.g. el nombre del archivo después
de eliminar el path). Simplemente basta con utilizar la opción
-a
de línea de comandos para especificar los
nombres de todos los archivos que se desean adjuntar:
%
send-pr -a /var/run/dmesg -a /tmp/errors
No se preocupe por los archivos binarios, dichos archivos se codifican automáticamente para no interferir con el agente de correo.
Si se adjunta un parche, asegúrese que se utiliza la
opción -c
o la opción
-u
de diff(1) para crear un contexto
unificado (el contexto suele ser el preferido por quienes lo han de
recibir) y además asegúrese de especificar
los números de revisión de CVS de los archivos que se
modifican para que los desarrolladores que lean el informe
puedan aplicar dichos parches fácilmente. Para problemas
relacionados con el kernel o con las utilidades del sistema
base, se prefiere un parche contra FreeBSD-CURRENT (la rama HEAD
del árbol CVS) ya que cualquier código nuevo debe
probar se primeramente en dicha rama. Después de comprobar su
correcto funcionamiento de una forma sustancial y extensa,
eventualmente dicho código pasará a formar parte de
FreeBSD-STABLE, mediante unión o migración.
Si se envía un parte en línea, en vez de como adjunto, tenga en cuenta que el principal problema de esta forma de enviar los parches es que, dependiendo del lector de correo utilizado, algunos lectores muestran los tabuladores como espacios, lo cual arruina completamente el formato y la indentación del parche, e invalida totalmente un parche que forme parte de un Makefile.
También tenga en cuenta que mientras que la inclusión de parches en un PR se considera como algo positivo—particularmente cuando se soluciona el problema que describe el informe—partes grandes y especialmente código nuevo que puede requerir una sustancial revisión antes de ser aplicado debería hacerse accesible a través de otros medios, como páginas web o servidores de ftp, y en vez de incluir el parche en el informe se puede incluir la URL. Los parches de gran tamaño en los correos electrónicos tienden a mezclarse o partirse, especialmente cuando GNATS los trata, y cuanto más grande es el parche más difícil resulta recuperar el original. También existe una ventaja añadida a la inclusión del parche a través de una URL, ya que de este modo se puede modificar el parche sin tener que reenviar el informe como una respuesta al informe inicial.
Se debe prestar atención también al hecho de que, a menos que se especifique explícitamente lo contrario en el PR o en el propio parche, cualquier parche enviado se supone licenciado bajo los mismos términos y condiciones que el archivo original que modifica.
Cuando se ejecuta send-pr(1) se nos presenta en pantalla una plantilla. Esta plantilla consiste en una lista de campos, algunos de los cuales se encuentran ya rellenados, mientras que otros poseen comentarios donde se explica su propósito o se comentan los valores aceptables. No se preocupe por los comentarios, puesto que se borran automáticamente antes de generar el informe.
Al comienzo de la plantilla, justo debajo de las líneas de
SEND-PR:
, se encuentran las cabeceras de
correo electrónico. Dichas cabeceras normalmente no se tienen
que modificar, a menos que se esté rellenando el informe desde
una máquina que puede enviar correo pero no puede recibirlo
directamente, en cuyo caso usted tendrá que editar los campos
From:
y Reply-To:
para
escribir la dirección de correo válida. También
puede enviarse una copia a usted mismo o a cualquier otra persona
rellenando el campo Cc:
.
A continuación aparecen una serie de campos de una sola línea:
Submitter-Id: No cambie este
campo. El valor por defecto
current-users
es correcto, incluso si
se está ejecutando FreeBSD-STABLE.
Originator: Se rellena
automáticamente con el campo gecos
del
usuario que está actualmente dentro del sistema. Por
favor, especifique su nombre real, opcionalmente
acompañado por su dirección de correo
electrónico entre < >.
Organization: Escriba lo que usted quiera. Este campo no se utiliza para nada significativo.
Confidential: Esto se rellena
automáticamente con el literal no
.
Cambiar este valor carece de sentido ya que no existe
ningún informe de problemas de FreeBSD confidencial—la
base de datos de PR se distribuye a todo el mundo de forma
pública mediante CVSup.
Synopsis: Rellene este campo con una descripción corta y precisa del problema. 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 obscuras sinopsis tienden a ser completamente ignorados.
Como se avisó anteriormente, si su informe de
problemas incluye un parche, por favor incluya en la
sinopsis la etiqueta [patch]
al
comienzo; si usted es un mantenedor de software, también
puede añadir la cadena [maintainer
update]
y asignar el campo “Class”
del informe al valor
maintainer-update
.
Severity: Los valores aceptados
son non-critical
,
serious
o critical
.
No sea exagerado; evite etiquetar el problema como
critital
a menos que sea realmente algo
crítico (e.g. escalada de permisos hacia
root
, kernel panic fácilmente
reproducible). Incluso debe pensarse detenidamente
etiquetar algo como serious
a menos que
se trate de algo que afecte a muchos usuarios (problemas
con drivers de dispositivos particulares o con utilidades
del sistema). Los desarrolladores de FreeBSD no van a
resolver el problema más rápido por el hecho de
variar esta etiqueta, debido a que existe mucha gente que infla
este campo inadecuadamente. De hecho, los desarrolladores
prestan muy poca atención al valor de este campo y del
siguiente precisamente por esto último.
Priority: Los valores aceptados
son low
, medium
o
high
. high
debe
reservarse para problemas que afecten a la mayoría de los
usuarios de FreeBSD y medium
para aquellos
problemas que afecten a varios usuarios.
Category: Seleccione uno de los
siguientes valores (extraídos de
/usr/gnats/gnats-adm/categories
):
advocacy:
para problemas
relacionados con la imagen pública de FreeBSD. Raras veces
utilizado.
alpha:
para problemas
específicos de la plataforma Alpha.
amd64:
para problemas
específicos de la plataforma AMD64.
bin:
para problemas con
aplicaciones de la zona de usuario del sistema
base.
conf:
para problemas de
archivos de configuración, valores por defecto,
etc.
docs:
para problemas con las
páginas de manual o la documentación online.
gnu:
para problemas
realacionados con aplicaciones gnu de FreeBSD tales como
gcc(1) o grep(1).
i386:
para problemas
específicos de la plataforma i386™.
ia64:
para problemas
específicos de la plataforma ia64.
java:
para problemas
relacionados con Java™.
kern:
para problemas
relacionados con el kernel o con (no especifícos de
ninguna plataforma) controladores de
dispositivos.
misc:
para cualquier cosa que
no encaja en ninguna de las anteriores categorías.
(Tenga en cuenta que es muy fácil que los problemas
bajo esta categoría se pierdan en el olvido).
ports:
para problemas
relacionados con el árbol de ports.
powerpc:
para problemas
específicos de la plataforma PowerPC®.
sparc64:
para problemas
específicos de la plataforma Sparc64®.
standards:
para problemas
relativos a la adecuación con estándares.
threads:
para problemas
relacionados con la implementación de threads de FreeBSD
(especialmente en FreeBSD-CURRENT).
www:
para cambios o mejoras
del sitio web de FreeBSD.
Class: Se puede seleccionar uno entre los siguientes:
sw-bug:
bugs de software.
doc-bug:
errores en la
documentación.
change-request:
peticiones de
características adicionales o de cambios en las
características existentes.
update:
actualizaciones de
ports o de software contribuido por terceros.
maintainer-update:
actualizaciones de ports de los cuales usted es
mantenedor.
Release: La versión de FreeBSD que se está ejecutando. El programa send-pr(1) rellena automáticamente este campo, por lo que sólamente resulta necesaria su modificación cuando estemos rellenando un informe de problemas desde un sistema distinto al sistema donde se ha producido dicho problema.
Por último, existen una serie de campos multilínea:
Environment: Este campo debe describir, tan preciso como sea posible, el entorno en el cual se ha observado el problema. Esto incluye la versión del sistema operativo, la versión del programa que contiene el problema y cualquier otro asunto relevante tales como la configuración del sistema o cualquier otro software instalado que pueda influir en la ejecución del primero, etc. Resumiendo todo lo anterior, se debe especificar todo lo que un desarrollador necesita conocer para poder reconstruir el entorno en el cual se ha producido el problema.
Description: Una descripción completa y precisa del problema que se está sufriendo. Intente evitar especular sobre las posibles causas del problema a menos que se tenga la seguridad de que el camino descrito es el correcto, puesto que puede inducir al desarrollador a realizar falsas presunciones.
How-To-Repeat: Un resumen de las acciones que deben llevarse a cabo para reproducir el problema.
Fix: Preferentemente un parche, o al menos una solución temporal (la cual no sólo ayuda a otras personas que experimenten el mismo problema, sino que puede ayudar también al desarrollador para que investigue sobre las verdaderas causas del problema). No obstante, si no se dispone de ninguna de estas opciones, lo mas sabio es dejar vacío este campo y sobre todo no hacer especulaciones.
Una vez que hemos terminado de rellenar la plantilla,
hemos salvado y hemos salido del editor, send-pr(1) nos
dará a conocer las siguientes opciones: s)end, e)dit
or a)bort?
. Es en estos momentos cuando podemos
teclear s
para continuar y enviar el
informe de problemas, e
para relanzar
el editor y realizar más modificaciones a la plantilla o
a
para abortar el programa. Si se
selecciona esta última alternativa, el informe de problemas no
será destruido, sino que permanecerá en disco
(send-pr(1) nos indicará el nombre del fichero antes
de finalizar), de tal forma que se puede editar de forma individual
(sin send-pr(1)) en cualquier momento, o también se
puede transferir a otro sistema con mejor conectividad para
finalmente enviarlo utilizando la opción f
de
línea de comandos de send-pr(1):
%
send-pr -f ~/my-problem-report
Esto leerá el archivo especificado, validando sus contenidos, y eliminará los comentarios para finalmente enviarlo.
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>.