diff options
| author | Jesus Rodriguez Cuesta <jesusr@FreeBSD.org> | 2004-10-09 02:02:29 +0000 |
|---|---|---|
| committer | Jesus Rodriguez Cuesta <jesusr@FreeBSD.org> | 2004-10-09 02:02:29 +0000 |
| commit | 3d819359cf00addf113c0d252ffd6b11856b5838 (patch) | |
| tree | 439b62d0009b9e2621a61af2327e85b71b80ce68 | |
| parent | fd666cbd15167166eb092486a5c928747f54d033 (diff) | |
Notes
| -rw-r--r-- | es_ES.ISO8859-1/articles/Makefile | 2 | ||||
| -rw-r--r-- | es_ES.ISO8859-1/articles/problem-reports/Makefile | 20 | ||||
| -rw-r--r-- | es_ES.ISO8859-1/articles/problem-reports/article.sgml | 1026 |
3 files changed, 1048 insertions, 0 deletions
diff --git a/es_ES.ISO8859-1/articles/Makefile b/es_ES.ISO8859-1/articles/Makefile index 9f02e2017a..4b20c13da6 100644 --- a/es_ES.ISO8859-1/articles/Makefile +++ b/es_ES.ISO8859-1/articles/Makefile @@ -1,4 +1,5 @@ # $FreeBSD$ +# $FreeBSDes: doc/es_ES.ISO8859-1/articles/Makefile,v 1.3 2004/10/09 02:01:17 jesusr Exp $ SUBDIR = SUBDIR+= contributing @@ -6,6 +7,7 @@ SUBDIR+= dialup-firewall SUBDIR+= explaining-bsd SUBDIR+= fbsd-from-scratch SUBDIR+= laptop +SUBDIR+= problem-reports SUBDIR+= zip-drive DOC_PREFIX?= ${.CURDIR}/../.. diff --git a/es_ES.ISO8859-1/articles/problem-reports/Makefile b/es_ES.ISO8859-1/articles/problem-reports/Makefile new file mode 100644 index 0000000000..b7104e0cf9 --- /dev/null +++ b/es_ES.ISO8859-1/articles/problem-reports/Makefile @@ -0,0 +1,20 @@ +# +# $FreeBSD$ +# $FreeBSDes: doc/es_ES.ISO8859-1/articles/problem-reports/Makefile,v 1.1 2004/10/08 23:06:08 carvay Exp $ +# +# Article: Writing FreeBSD Problem Reports + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.sgml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/es_ES.ISO8859-1/articles/problem-reports/article.sgml b/es_ES.ISO8859-1/articles/problem-reports/article.sgml new file mode 100644 index 0000000000..8bb4113dfd --- /dev/null +++ b/es_ES.ISO8859-1/articles/problem-reports/article.sgml @@ -0,0 +1,1026 @@ +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; +<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous +FreeBSD Entities//EN"> %freebsd; +<!ENTITY % newsgroups PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//ES"> %newsgroups; +<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN"> +%authors; +<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//ES"> +%mailing-lists; +<!ENTITY % translators PUBLIC "-//FreeBSD//ENTITIES DocBook Translator Entities//ES"> +%translators; +<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN"> +%trademarks; +<!ENTITY % not.published "IGNORE"> +]> + + + +<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 donde se requiere + 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 mutua + satisfacción del usuario y del desarrollador.</para> + + <para>Aunque el objetivo principal de este artículo se centra en + los informes de problemas, 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 proceder a enviar informes + de problemas. No debe tratarse como un tutorial del estilo paso + a paso.</para> </section> + + <section id="pr-when"> + <title>Cuando 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 donde estaremos + convencidos de haber encontrado un bug en un programa cuando + realmente hemos malentendido la sintaxis o el funcionamiento de + dicho programa, o simplemente hemos cometido un error + tipográfico en un archivo de configuración (aunque en este + último caso podría tratarse de un indicador de + documentación pobre o de manejo de errores inadecuado por parte + de la aplicación). 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 actuar, ya que dicho envío puede servir para + fustrar tanto al creador del informe como al desarrollador de + 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 bugs; una mejora o una solucitud de + nueva característica, por citar un par de ejemplos.</para> + + <para>Así que ¿cómo podemos determinar qué + constituye un bug y qué no? Como regla para principiantes + podemos decir que su problema <emphasis>no</emphasis> es un bug 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 bug:</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 bug + no se encuentra medianamente actualizado, se debe considerar muy + seriamente su actualización e intentar reproducir el problema en + un sistema actualizado antes de emitir el informe de problemas. + 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 bug que no se puede reproducir + difícilmente puede arreglarse. Si el bug + sólo corrió 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 que es + lo que falla. Esto no significa que el bug 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 sobrecalentamiento del + procesador — usted debe siempre intentar 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 en segundo plano 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>El &os; + <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). + La lista de FAQ intenta proporcionar respuestas para un + amplio rango de preguntas, 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 documentaicó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 eletró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, + cómo 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> |