<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//ES">
%articles.ent;
]>
<article>
<articleinfo>
<title>Cómo enviar informes de problemas de &os;</title>
<pubdate>$FreeBSD$</pubdate>
<!--
$FreeBSDes: doc/es_ES.ISO8859-1/articles/problem-reports/article.sgml,v 1.2 2004/10/09 01:56:32 jesusr Exp $
-->
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.cvsup;
&tm-attrib.ibm;
&tm-attrib.intel;
&tm-attrib.sparc;
&tm-attrib.sun;
&tm-attrib.general;
</legalnotice>
<abstract>
<para>Este artículo describe cómo realizar y enviar
informes de errores para el proyecto &os; de la mejor forma
posible.</para>
&trans.es.jrh;
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Smørgrav</surname>
<contrib>Escrito por </contrib>
</author>
</authorgroup>
</articleinfo>
<indexterm><primary>problem reports</primary></indexterm>
<section id="pr-intro">
<title>Introducción</title>
<para>Una de las experiencias más fustrantes que se pueden
experimentar como usuario de software es aquella en la cual el
usuario se toma la molestia de rellenar un informe de problemas
detallado para observar tras un determinado espacio de tiempo
que dicho informe se cierra con una explicación corta y abrupta
como <quote>no es un error</quote> o <quote>PR erroneo</quote>.
De forma semejante, una de las experiencias más fustrantes que
puede experimentar un desarrollador de aplicaciones consiste en
verse inundado por una cantidad ingente de informes de errores
que en realidad vienen a ser solicitudes de
soporte o ayuda, o que contienen poca o ninguna información
sobre cúal es el problema y como se puede reproducir.</para>
<para>Este documento intenta describir cómo escribir informes de
problemas de calidad. Usted se preguntará cómo se pueden
escribir informes de problemas de calidad. Bien, para ir
directos al grano, un informe de problemas de calidad es aquél
que se puede analizar y tratar rápidamente, para mútua
satisfacción del usuario y del desarrollador.</para>
<para>Aunque el objetivo principal de este artículo se centra en
los informes de problemas de &os; la mayoría de los conceptos se
pueden aplicar bastante bien en otros proyectos de software.</para>
<para>Dése cuenta de que este artículo se organiza de forma
temática, no cronológicamente, de tal forma que se debe
leer el documento íntegro antes de enviar informes
de problemas. No debe tratarse como un tutorial del estilo paso
a paso.</para> </section>
<section id="pr-when">
<title>Cuándo enviar informes de problemas</title>
<para>Existen varios tipos de problemas y no todos ellos se
merecen la creación de un informe de problemas. Por supuesto,
nadie es perfecto, y existirán ocasiones en las que estaremos
convencidos de haber encontrado un <quote>bug</quote> en un programa
cuando realmente hemos malinterpretado la sintaxis o el funcionamiento de
dicho programa, o simplemente hemos cometido un error
tipográfico en un fichero de configuración (aunque en este
último caso podría tratarse de un indicador de
documentación escasa o que la aplicación peca de una
gestión de errores defectuosa. Incluso
teniendo estos aspectos en cuenta existen varios casos en los cuales
el envío de un informe de problemas resulta claramente
<emphasis>no ser</emphasis> la mejor forma de proceder, ya que dicho
envío puede servir para frustrar tanto a quien envía el
informe como a quien desarrolló la aplicación.
Por el contrario, también existen casos
en los que puede resultar apropiado enviar un informe de problemas sobre
algo más aparte de <quote>bugs</quote>: una mejora o una solucitud
nuevas características, por citar un par de ejemplos.</para>
<para>Así que ¿cómo podemos determinar qué
constituye un <quote>bug</quote> y qué no? Como regla para
principiantes podemos decir que su problema
<emphasis>no</emphasis> es un <quote>bug</quote> si
se puede expresar como una pregunta (normalmente del estilo de
<quote>¿cómo hago X?</quote> o
<quote>¿donde puedo encontrar Y?</quote>). No siempre las
cosas son blancas o negras, pero la regla de las preguntas suele
cubrir una gran mayoría de casos. Si lo que se quiere es una
respuesta a una consulta, se pueden enviar dichas preguntas a la
&a.questions;.</para>
<para>A continuación se muestran algunos casos en los que resulta
apropiado enviar un informe de problemas sobre algo que no se
considera un <quote>bug</quote>:</para>
<itemizedlist>
<listitem>
<para>Solucitudes para mejora de características. Normalmente
es una buena idea airear estas propuestas en las listas de
distribución antes de enviar un informe de problemas.</para>
</listitem>
<listitem>
<para>Notificación de actualizaciones de software que se
mantiene externamente (principalmente ports, pero también
componentes del sistema base al cargo de proyectos independientes
de &os;, como BIND o diversas utilidades GNU)</para>
</listitem>
</itemizedlist>
<para>Otro tema es que si el sistema donde se experimentó el
<quote>bug</quote> no está medianamente actualizado se debe
considerar muy seriamente su actualización e intentar reproducir
el problema en un sistema actualizado antes de emitir el informe.
Existen pocas cosas que molesten más a un desarrollador que
recibir un informe de problemas sobre un problema que ya ha
resuelto.</para>
<para>Por último, un <quote>bug</quote> que no se puede
reproducir difícilmente puede arreglarse. Si el
<quote>bug</quote> sólo ocurrió una vez y no somos capaces
de reproducirlo, y parece que no le ocurre a nadie más,
es muy probable que ni siquiera los desarrolladores puedan
reproducirlo y por lo tanto ni siquiera puedan imaginarse qué es
lo que falla. Esto no significa que el <quote>bug</quote> no haya
ocurrido, sino que las probabilidades de que nuestro informe de errores
sirva para corregir un defecto son muy pequeñas. Para complicar
más las cosas, a menudo estas clases de errores se producen
debido a fallos en los discos duros o al sobrecalentamiento del
procesador: debe intentar siempre descubrir estos
fallos, siempre que sea posible, antes de enviar un PR.</para>
</section>
<section id="pr-prep">
<title>Preparativos</title>
<para>Una buena regla que se puede seguir consiste en realizar
siempre una búsqueda antes de enviar un informe
de problemas. Quizá nuestro problema ya ha sido reportado;
quizá se está discutiendo en las listas de
distribución o fue discutido hace poco; incluso es posible que
se haya arreglado en versiones más recientes del software.
Por lo tanto, se deben consultar los sitios y fuentes más obvias
antes de proceder con el envío del informe de errores.
En &os; esto significa:</para>
<itemizedlist>
<listitem>
<para>Las
<ulink url="http://www.freebsd.org/doc/en/books/faq/index.html">Preguntas Más
<!--
XXX
<ulink url="&url.books.faq;/index.html">Preguntas Más
-->
Frecuentes</ulink> (FAQ) de &os;.
Las FAQ intentan proporcionar respuestas para un
amplio rango de dudas, tales como aquellas relacionadas
con las
<!--
<ulink url="&url.books.faq;/hardware.html">compatibilidades
hardware</ulink>, las
<ulink url="&url.books.faq;/applications.html">aplicaciones
de usuario</ulink> y la
<ulink url="&url.books.faq;/kernelconfig.html">configuración
del kernel</ulink>.
-->
<ulink
url="http://www.freebsd.org/doc/en/books/faq/hardware.html">compatibilidades
hardware</ulink>, las
<ulink
url="http://www.freebsd.org/doc/en/books/faq/applications.html">aplicaciones
de usuario</ulink> y la
<ulink
url="http://www.freebsd.org/doc/en/books/faq/kernelconfig.html">configuración
del kernel</ulink>.</para>
</listitem>
<listitem>
<para>Las
<!--
<ulink
url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">listas
-->
<ulink
url="http://www.freebsd.org/doc/en/books/handbook/eresources.html#ERESOURCES-MAIL">listas
de correo</ulink>. Si no está subscrito utilice
<ulink
url="http://www.FreeBSD.org/search/search.html#mailinglists">la
búsqueda en los archivos</ulink> del sitio web de &os;. Si
el problema no se ha discutido con anterioridad en las
listas, se puede intentar enviar un mensaje y esperar unos
pocos días para ver si alguien puede aconsejarle
adecuadamente sobre algún punto que quizá haya pasado
por alto en relación con el problema.</para>
</listitem>
<listitem>
<para>Opcionalmente, la web entera—utilice su motor de
búsqueda favorito para localizar cualquier referencia a su
problema. Incluso pueden aparecer listas de correo o grupos
de noticias de los cuales ni siquiera tuviera conocimiento
de su existencia o quizá no consideró apropiado
consultarlas al principio.</para> </listitem>
<listitem>
<para>A continuación, la búsqueda a través de
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
la base de datos &os; PR</ulink> (GNATS). A menos que
nuestro problema sea muy reciente o rebuscado, existe un
gran número de posibilidades de que ya haya sido informado o
reportado.</para>
</listitem>
<listitem>
<para>Lo más importante, se debería intentar comprobar
si la documentación existente en el código fuente del
programa puede resolver el problema.</para>
<para>En el caso de las fuentes del sistema &os; debe estudiarse
cuidadosamente el contenido del fichero
<filename>/usr/src/UPDATING</filename> del sistema o su
última versión, que se encuentra en <ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>.
(Esta información se considera de vital importancia si se
está actualizando de una versión a otra, especialmente
si la actualización se realiza de la versión estable a
la versión &os.current;).</para>
<para>No obstante, si el problema se encuentra en algo que se
instaló como parte de la collección de ports de &os;,
se debe consultar el archivo
<filename>/usr/ports/UPDATING</filename> (para ports
individuales) o el archivo
<filename>/usr/ports/CHANGES</filename> (para cambios que
afectan a la colección de ports completa). <ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING"></ulink>
y <ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES"></ulink>
también se encuentran disponibles a través de CVSweb.
</para>
</listitem>
</itemizedlist>
<para>A continuación debemos asegurarnos de que el informe de
errores llega a las personas adecuadas.</para>
<para>La primera consideración llegados a este punto consiste en:
Si el problema resulta ser un bug en un software
de terceras partes (un port o un paquete que se ha instalado)
se debe informar sobre el bug al autor original del software, no
al proyecto &os;. Existen dos excepciones a esta regla: la
primera ocurre cuando el bug no se produce en otras plataformas,
en cuyo caso el problema puede residir en cómo fue migrado el
software a &os;; la segunda excepción ocurre cuando el autor
original ya ha corregido el problema y distribuido un parche o
una nueva versión de su software, pero el port de &os;
todavía no se ha actualizado.</para>
<para>La segunda consideración es que el sistema de seguimiento de
bugs de &os; ordena los informes de problemas de acuerdo con la
categoría que ha seleccionado el informador. De este modo, si se
selecciona una categoría incorrecta cuando se envía el
informe de problemas, existe una gran probabilidad de que nadie se de
cuenta de su existencia durante un período de tiempo indefinido,
hasta que alguien se encarge de re-categorizarlo.</para>
</section>
<section id="pr-writing">
<title>Escribir el informe de problemas</title>
<para>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 &os;, 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.</para>
<section>
<title>Consejos y trucos para escribir un buen informe de
problemas</title>
<itemizedlist>
<listitem>
<para><emphasis>No deje la línea de <quote>Synopsis</quote>
vacía</emphasis>. Los PRs se dirigen tanto a una lista de
correo mundial (donde se utiliza el campo
<quote>Synopsis</quote> para rellenar la línea
<literal>Subject:</literal> del correo) como a una base
de datos (GNATS). Cualquier persona que consulte la base
de datos por el campo <literal>sinopsis</literal> y encuentre un
PR con una línea de <literal>Asunto</literal> 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.</para>
</listitem>
<listitem>
<para><emphasis>Evite utilizar una línea de
<quote>Synopsis</quote> débil.</emphasis>. 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 <literal>Synopsis: portupgrade is
broken</literal>, se pueden ver las ventajas que
proporciona una línea como la siguiente:
<literal>Synopsis: port sysutils/portupgrade produce un
coredump en -current</literal>. (En el caso concreto de
los ports, resulta especialmente útil poseer tanto la
categoría como el nombre del port en la línea
<quote>Synopsis</quote>.)</para>
</listitem>
<listitem>
<para><emphasis>Si se dispone de un parche, dígalo.
</emphasis> 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
<literal>[patch]</literal> al comienzo de la línea
<quote>Synopsis</quote>. (Aunque no es obligatorio
utilizar dicha cadena, se trata de un estándar de facto
que se utiliza de forma mayoritaria.)</para>
</listitem>
<listitem>
<para><emphasis>Si es mantenedor del port, dígalo.</emphasis>
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
<literal>[maintainer update]</literal> al comienzo de la
línea de sinopsis, y además se debería
asignar el campo <quote>Class</quote> del PR a la cadena
<literal>maintainer-update</literal>. De esta forma
cualquier committer que maneje el PR no tendrá que
realizar comprobaciones.</para> </listitem>
<listitem>
<para><emphasis>Sea concreto.</emphasis>
Cuanta más información se proporcione sobre el
problema que se tiene, más posiblidades de obtener una
respuesta.</para>
<itemizedlist>
<listitem>
<para>Incluya la versión del &os; 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 &man.cvsup.1; (y, si esto último se cumple,
con qué frecuencia se realiza la actualización). Si se está siguiendo la rama &os.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 &os.current; un seguimiento cercano de
las actualizaciones aplicadas.</para> </listitem>
<listitem>
<para>Incluya qué opciones globales se han especificado
en el archivo <filename>make.conf</filename>. Aviso:
Es bien conocido por todos que especificar
<literal>-O2</literal> y valores superiores para
&man.gcc.1; produce fallos y resulta ser proclive a
errores en muchas situaciones. Aunque los
desarrolladores de &os; 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.</para>
</listitem>
<listitem>
<para>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):</para>
<itemizedlist>
<listitem>
<para>La configuración del kernel (incluyendo los
dispositivos hardware que se tienen
instalados)</para>
</listitem>
<listitem>
<para>Si se tienen opciones de depuración activadas
(tales como <literal>WITNESS</literal>), y en tal
caso, si el problema persiste cuando se cambia el
valor de dichas opciones</para>
</listitem>
<listitem>
<para>Una traza de depuración, si se pudo
generar.</para> </listitem>
<listitem>
<para>El hecho de que se ha leido detenidamente el
archivo <filename>src/UPDATING</filename> para
constatar que el problema no se ha identificado
allí (se garantiza que alguién le
preguntará sobre este punto)</para>
</listitem>
<listitem>
<para>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)</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>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):</para>
<itemizedlist>
<listitem>
<para>Los ports que se tiene instalados</para>
</listitem>
<listitem>
<para>Cualesquiera variables de entorno que
sobreescriban los valores por defecto del archivo
<filename>bsd.port.mk</filename>, tales como
<makevar>PORTSDIR</makevar></para>
</listitem>
<listitem>
<para>El hecho de que se ha leido
<filename>ports/UPDATING</filename> y que nuestro
problema no se encuentra identificado en dicho
archivo (se garantiza que alguien puede preguntar
este hecho).</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><emphasis>Evitar peticiones de características
vagas.</emphasis> Los PRs del estilo de
<quote>alguien debería implementar algo que haga
esto y aquello y lo de más allá</quote> 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
<literal>freebsd-questions</literal>, como ya se ha
comentado anteriormente.</para>
</listitem>
<listitem>
<para><emphasis>Asegúrese que nadie más ha enviado un
PR similar.</emphasis> 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 <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>.
(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)</para></listitem>
<listitem>
<para><emphasis>Evite peticiones controvertidas.</emphasis>
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 <quote>Forma Correcta de
Hacerlo</quote>. Como se avisó anteriormente, una
búsqueda meticulosa en las listas de correo en los
archivos históricos sitos en <ulink
url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink>
resulta siempre una buena idea y sirve para preparar
nuestro razonamiento y aprender de la experiencia y de las
decisiones tomadas en el pasado.</para> </listitem>
<listitem>
<para><emphasis>Sea educado.</emphasis>
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.</para> </listitem> </itemizedlist>
</section>
<section>
<title>Antes de comenzar.</title>
<para>Antes de ejecutar el programa &man.send-pr.1;, asegúrese
de que la variable de entorno <envar>VISUAL</envar> (o
<envar>EDITOR</envar> si la variable <envar>VISUAL</envar> no
se encuentra definida) se encuentra apuntando a algo con
sentido.</para>
<para>Es importante comprobar que la entrega de correo funciona
correctamente. &man.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 &man.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 &os; consulte el capítulo de
<quote>Correo Electrónico</quote> del manual de &os; en <ulink
url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">
</ulink>.</para>
</section>
<section>
<title>Adjuntar parches o archivos</title>
<para>El programa &man.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
<option>-a</option> de línea de comandos para especificar los
nombres de todos los archivos que se desean adjuntar:</para>
<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen>
<para>No se preocupe por los archivos binarios, dichos archivos
se codifican automáticamente para no interferir con el agente
de correo.</para>
<para>Si se adjunta un parche, asegúrese que se utiliza la
opción <option>-c</option> o la opción
<option>-u</option> de &man.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 &os.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
&os.stable;, mediante unión o migración.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para> </section>
<section>
<title>Rellenar la plantilla</title>
<para>Cuando se ejecuta &man.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.</para>
<para>Al comienzo de la plantilla, justo debajo de las líneas de
<literal>SEND-PR:</literal>, 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
<literal>From:</literal> y <literal>Reply-To:</literal> 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 <literal>Cc:</literal>.</para>
<para>A continuación aparecen una serie de campos de una sola
línea:</para>
<itemizedlist>
<listitem>
<para><emphasis>Submitter-Id:</emphasis> No cambie este
campo. El valor por defecto
<literal>current-users</literal> es correcto, incluso si
se está ejecutando &os.stable;.</para> </listitem>
<listitem>
<para><emphasis>Originator:</emphasis> Se rellena
automáticamente con el campo <literal>gecos</literal> 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 < >.</para> </listitem>
<listitem>
<para><emphasis>Organization:</emphasis> Escriba lo que
usted quiera. Este campo no se utiliza para nada
significativo.</para> </listitem>
<listitem>
<para><emphasis>Confidential:</emphasis> Esto se rellena
automáticamente con el literal <literal>no</literal>.
Cambiar este valor carece de sentido ya que no existe
ningún informe de problemas de &os; confidencial—la
base de datos de PR se distribuye a todo el mundo de forma
pública mediante <application>CVSup</application>.</para>
</listitem>
<listitem>
<para><emphasis>Synopsis:</emphasis> 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.</para>
<para>Como se avisó anteriormente, si su informe de
problemas incluye un parche, por favor incluya en la
sinopsis la etiqueta <literal>[patch]</literal> al
comienzo; si usted es un mantenedor de software, también
puede añadir la cadena <literal>[maintainer
update]</literal> y asignar el campo <quote>Class</quote>
del informe al valor
<literal>maintainer-update</literal>.</para> </listitem>
<listitem>
<para><emphasis>Severity:</emphasis> Los valores aceptados
son <literal>non-critical</literal>,
<literal>serious</literal> o <literal>critical</literal>.
No sea exagerado; evite etiquetar el problema como
<literal>critital</literal> a menos que sea realmente algo
crítico (e.g. escalada de permisos hacia
<username>root</username>, kernel panic fácilmente
reproducible). Incluso debe pensarse detenidamente
etiquetar algo como <literal>serious</literal> 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 &os; 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.</para> </listitem>
<listitem>
<para><emphasis>Priority:</emphasis> Los valores aceptados
son <literal>low</literal>, <literal>medium</literal> o
<literal>high</literal>. <literal>high</literal> debe
reservarse para problemas que afecten a la mayoría de los
usuarios de &os; y <literal>medium</literal> para aquellos
problemas que afecten a varios usuarios.</para>
</listitem>
<listitem>
<para><emphasis>Category:</emphasis> Seleccione uno de los
siguientes valores (extraídos de
<filename>/usr/gnats/gnats-adm/categories</filename>):</para>
<itemizedlist> <listitem>
<para><literal>advocacy:</literal> para problemas
relacionados con la imagen pública de &os;. Raras veces
utilizado.</para> </listitem>
<listitem>
<para><literal>alpha:</literal> para problemas
específicos de la plataforma Alpha.</para> </listitem>
<listitem>
<para><literal>amd64:</literal> para problemas
específicos de la plataforma AMD64.</para> </listitem>
<listitem>
<para><literal>bin:</literal> para problemas con
aplicaciones de la zona de usuario del sistema
base.</para> </listitem>
<listitem>
<para><literal>conf:</literal> para problemas de
archivos de configuración, valores por defecto,
etc.</para> </listitem>
<listitem>
<para><literal>docs:</literal> para problemas con las
páginas de manual o la documentación online.
</para> </listitem>
<listitem>
<para><literal>gnu:</literal> para problemas
realacionados con aplicaciones gnu de &os; tales como
&man.gcc.1; o &man.grep.1;.</para> </listitem>
<listitem>
<para><literal>i386:</literal> para problemas
específicos de la plataforma &i386;.</para> </listitem>
<listitem>
<para><literal>ia64:</literal> para problemas
específicos de la plataforma ia64.</para> </listitem>
<listitem>
<para><literal>java:</literal> para problemas
relacionados con &java;.</para> </listitem>
<listitem>
<para><literal>kern:</literal> para problemas
relacionados con el kernel o con (no especifícos de
ninguna plataforma) controladores de
dispositivos.</para> </listitem>
<listitem>
<para><literal>misc:</literal> 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).</para>
</listitem>
<listitem>
<para><literal>ports:</literal> para problemas
relacionados con el árbol de ports.</para> </listitem>
<listitem>
<para><literal>powerpc:</literal> para problemas
específicos de la plataforma &powerpc;.</para>
</listitem>
<listitem>
<para><literal>sparc64:</literal> para problemas
específicos de la plataforma &sparc64;.</para>
</listitem>
<listitem>
<para><literal>standards:</literal> para problemas
relativos a la adecuación con estándares.</para>
</listitem>
<listitem>
<para><literal>threads:</literal> para problemas
relacionados con la implementación de threads de &os;
(especialmente en &os.current;).</para> </listitem>
<listitem>
<para><literal>www:</literal> para cambios o mejoras
del sitio web de &os;.</para> </listitem>
</itemizedlist> </listitem>
<listitem>
<para><emphasis>Class:</emphasis> Se puede seleccionar uno
entre los siguientes:</para>
<itemizedlist>
<listitem>
<para><literal>sw-bug:</literal> bugs de software.</para>
</listitem>
<listitem>
<para><literal>doc-bug:</literal> errores en la
documentación.</para> </listitem>
<listitem>
<para><literal>change-request:</literal> peticiones de
características adicionales o de cambios en las
características existentes.</para> </listitem>
<listitem>
<para><literal>update:</literal> actualizaciones de
ports o de software contribuido por terceros.</para>
</listitem>
<listitem>
<para><literal>maintainer-update:</literal>
actualizaciones de ports de los cuales usted es
mantenedor.</para> </listitem> </itemizedlist>
</listitem>
<listitem>
<para><emphasis>Release:</emphasis> La versión de &os; que
se está ejecutando. El programa &man.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.</para> </listitem>
</itemizedlist>
<para>Por último, existen una serie de campos
multilínea:</para>
<itemizedlist>
<listitem>
<para><emphasis>Environment:</emphasis> 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.</para> </listitem>
<listitem>
<para><emphasis>Description:</emphasis> 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.</para>
</listitem>
<listitem>
<para><emphasis>How-To-Repeat:</emphasis> Un resumen de las
acciones que deben llevarse a cabo para reproducir el
problema.</para> </listitem>
<listitem>
<para><emphasis>Fix:</emphasis> 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.</para> </listitem> </itemizedlist>
</section>
<section>
<title>Envío del informe de problemas</title>
<para>Una vez que hemos terminado de rellenar la plantilla,
hemos salvado y hemos salido del editor, &man.send-pr.1; nos
dará a conocer las siguientes opciones: <prompt>s)end, e)dit
or a)bort?</prompt>. Es en estos momentos cuando podemos
teclear <userinput>s</userinput> para continuar y enviar el
informe de problemas, <userinput>e</userinput> para relanzar
el editor y realizar más modificaciones a la plantilla o
<userinput>a</userinput> para abortar el programa. Si se
selecciona esta última alternativa, el informe de problemas no
será destruido, sino que permanecerá en disco
(&man.send-pr.1; nos indicará el nombre del fichero antes
de finalizar), de tal forma que se puede editar de forma individual
(sin &man.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 <option>f</option> de
línea de comandos de &man.send-pr.1;:</para>
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
<para>Esto leerá el archivo especificado, validando sus
contenidos, y eliminará los comentarios para finalmente
enviarlo.</para> </section>
</section>
<section id="pr-followup">
<title>Follow-up</title>
<para>Una vez enviado el informe de problemas, se recibe una
confirmación por correo electrónico en la que se incluye el
número asignado al informe y la URL que puede utilizarse para
consultar su estado. Con un poquito de suerte, alguien mostrará
interés en el problema y tratará de solucionarlo, o de
explicar por qué razón no se considera un problema,
como ha ocurrido en muchas ocasiones. Recibiremos
automáticamente una notificación relativa a
cualquier cambio de estado, además de recibir copias de
cualquier comentario o de los parches que se generen
relacionados con nuestro informe.</para>
<para>Si alguien solicita información adicional sobre el problema,
o de repente descubre o recuerda algo que no tuvo ocasión de
mencionar en el informe inicial, puede utilizar una de las
siguientes opciones para enviar una continuación
(<quote>followup</quote>) a dicho informe:</para>
<itemizedlist>
<listitem>
<para>La forma más sencilla consiste en utilizar el enlace
followup que aparece en la página web asociada a nuestro
informe de problemas, la cual se puede alcanzar a partir de
la página de búsquedas de PRs en <ulink
url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>
. Al pinchar en dicho enlace se mostrará una pantalla con
las líneas de To: y Subject correctamente rellenadas (siempre
y cuando el navegador soporte esta característica de
autorelleno).</para> </listitem>
<listitem>
<para>Alternativamente, se puede enviar un correo eletrónico
directamente a <email>bug-followup@FreeBSD.org</email>,
asegurando que el número de seguimiento se incluye en el
asunto para que el sistema de seguimiento de informes pueda
adjuntar la respuesta al informe apropiado.</para>
<note>
<para>Si <emphasis>no</emphasis> se incluye el número de
seguimiento, GNATS no reconocerá el informe inicial y
creará un PR totalmente nuevo, que quedará asignado
al administrador de GNATS, de tal forma que el followup
quedará en el vacío hasta que alguien resuelva el
entuerto, lo cual puede tardar dias o semanas.</para>
<para>Forma incorrecta:<programlisting>Subject: ese PR que
envié en su día</programlisting> Forma
correcta:<programlisting>Subject: Re: ports/12345:
problema de compilación en foo/bar</programlisting></para>
</note> </listitem>
</itemizedlist>
<para>Si el informe de problemas permanece abierto una vez que
dicho problema ha desaparecido, simplemente envíe un followup
(de la forma descrita anteriormente) diciendo que el informe de
problemas se puede cerrar y, a ser posible, también conviene
explicar la forma en que el problema se resolvió.</para>
</section>
<section id="pr-further">
<title>Lecturas recomendadas</title>
<para>A continuación se muestra una lista de recursos relacionados
con la escritura adecuada de informes y con el procesamiento de
dichos informes. No pretende ser una completa
enumeración.</para>
<itemizedlist>
<listitem>
<para><ulink
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
How row to Report Bugs Effectively</ulink>—un
excelente ensayo por Simon G. Tatham sobre la redacción de
informes de problemas (el texto no es específico sobre
&os;)</para>
</listitem>
<listitem>
<!--
<para><ulink
url="&url.articles.pr-guidelines;/article.html">Problem
Report Handling Guidelines</ulink>—resumen de valor
-->
<para><ulink
url="http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html">Problem
Report Handling Guidelines</ulink>—resumen de valor
sobre cómo los desarrolladores de &os; manejan y gestionan
los informes de problemas.</para>
</listitem>
</itemizedlist>
</section>
</article>
