995 lines
42 KiB
XML
995 lines
42 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
|
|
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="es">
|
|
<info><title>Cómo enviar informes de problemas de &os;</title>
|
|
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
|
|
<legalnotice xml: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><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Escrito por </contrib></author>
|
|
</authorgroup>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
</info>
|
|
|
|
<indexterm><primary>problem reports</primary></indexterm>
|
|
|
|
<section xml: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 xml: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 xml: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
|
|
<link xlink:href="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</link> (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>.
|
|
-->
|
|
<link xlink:href="http://www.freebsd.org/doc/en/books/faq/hardware.html">compatibilidades
|
|
hardware</link>, las
|
|
<link xlink:href="http://www.freebsd.org/doc/en/books/faq/applications.html">aplicaciones
|
|
de usuario</link> y la
|
|
<link xlink:href="http://www.freebsd.org/doc/en/books/faq/kernelconfig.html">configuración
|
|
del kernel</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Las
|
|
<!--
|
|
<ulink
|
|
url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">listas
|
|
-->
|
|
<link xlink:href="http://www.freebsd.org/doc/en/books/handbook/eresources.html#ERESOURCES-MAIL">listas
|
|
|
|
de correo</link>. Si no está subscrito utilice
|
|
<link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">la
|
|
búsqueda en los archivos</link> 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
|
|
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
|
la base de datos &os; PR</link> (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 <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING">http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING</uri>.
|
|
(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). <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING">http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING</uri>
|
|
y <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES">http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES</uri>
|
|
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 xml: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
|
|
<varname>PORTSDIR</varname></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 <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>.
|
|
(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 <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
|
|
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 <uri xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</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
|
|
<systemitem class="username">root</systemitem>, 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 xml: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 <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>
|
|
. 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 xml: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><link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
|
|
How row to Report Bugs Effectively</link>—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><link xlink:href="http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html">Problem
|
|
Report Handling Guidelines</link>—resumen de valor
|
|
sobre cómo los desarrolladores de &os; manejan y gestionan
|
|
los informes de problemas.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<index/>
|
|
</article>
|