Guía para hacer preguntas de uso, reportar errores y solicitar nuevas características para LEILA
En esta guía encontrará las recomendaciones y pasos necesarios para realizar preguntas, reportar errores y solicitar o sugerir adiciones relacionadas con la ejecución y uso de las funciones o módulos de LEILA. Todas estas participaciones se podrán realizar a través de la sección de Issues del repositorio en GitHub de la librería.
- Verifique que el error que se va a reportar efectivamente es causado por alguna funcionalidad de LEILA, y no debido a otros elementos de su código.
- Verifique la correcta instalación, tanto de LEILA como de los paquetes adicionales que requiere para su funcionamiento. Para mayor información sobre la instalación de LEILA, por favor consultar la documentación de la librería.
- Revise la documentación de LEILA. En particular, lea la documentación de las funciones y/o módulos que está utilizando en su código para encontrar posibles fallas debido a uso incorrecto de las funcionalidades o parámetros de LEILA.
- Lea los issues anteriores (abiertos y cerrados) publicados en el repositorio de LEILA; es posible que otra persona haya tenido un problema igual o similar al suyo y ya se sepa cómo solucionarlo. Para esto, puede apoyarse en las opciones de búsqueda que ofrece GitHub.
- Lea los issues anteriores (abiertos y cerrados) publicados en el repositorio de LEILA; es posible que otra persona haya tenido una duda o idea muy similar a la que usted tiene en este momento. Para esto, puede apoyarse en las opciones de búsqueda que ofrece GitHub.
Nota: Si después de buscar en los issues existentes identifica alguno que sea de su interés, está totalmente invitado a participar en el mismo. Nos interesa mucho conocer la retroalimentación de la comunidad sobre LEILA, sus funcionalidades y sus aplicaciones; por lo tanto, toda opinión o discusión será muy apreciada.
Si, después de seguir las recomendaciones descritas anteriormente, determina que su pregunta, sugerencia o reporte de error es pertinente y no ha sido mencionado previamente, el siguiente paso es crear un nuevo issue. La creación de un nuevo issue ayudará al equipo desarrollador de LEILA a identificar el tema reportado y, si aplica, a incluirlo en su plan de trabajo para dar una respuesta satisfactoria al mismo.
Para crear un nuevo issue, debe dirigirse a la pestaña de Issues del repositorio en GitHub de LEILA y seleccionar la opción New issue.
Al elegir esta opción, en su navegador web aparecerá un formulario con dos campos principales: el título y el cuerpo (o descripción) del issue. A continuación se dan recomendaciones para el diligenciamiento de estos dos campos.
-
Trate de que sea una oración clara y concisa resumiendo el tema que desea abordar. El título debería ser auto explicativo, dando a los lectores la información esencial para entender de qué se trata el issue.
-
Si aplica, incluya detalles que puedan ayudar a identificar y resolver el error o la pregunta planteada, tales como mensajes de error o alertas en la ejecución. Esto, además de dar claridad sobre el tema consultado, hará que para otros usuarios con el mismo error o la misma pregunta sea más fácil encontrar este issue a través de motores de búsqueda.
-
Si su consulta es referente a una parte específica de la librería (por ejemplo, una función o un módulo en particular), menciónelo para acotar de mejor manera el issue.
En la siguiente tabla se muestran un par de ejemplos de buenos y malos títulos para expresar una misma idea.
| Mal título | Buen título |
|---|---|
| Confusión con int y float | ¿Por qué al usar variables de tipo float en lugar de int obtengo diferentes resultados, si todas mis entradas son números enteros? |
| No me deja calcular correlaciones | Error < nombre del error > al utilizar la función CorrelacionCategoricas para calcular la correlación entre variables usando el método de cramer |
-
Antes de publicar cualquier fragmento de código, empiece por expandir el problema, duda o sugerencia que se ha resumido en el título. Si está reportando un problema, explique algunos aspectos de cómo encontró el problema o cómo se generó este, describiendo lo que estaba intentando hacer y qué ha intentado para resolver el error. Si está planteando una pregunta o haciendo una sugerencia, describa cómo llegó a tener esa duda/sugerencia, explicando con más detalle lo que le gustaría poder entender o hacer por medio de LEILA, y por qué considera que es importante resolverlo.
-
Dar información suficiente para reproducir el problema. Esto aplica principalmente cuando se está reportando un error, pero es posible que también sea útil al momento de plantear una pregunta. Si su issue tiene que ver con el uso de alguna parte de LEILA, es de gran utilidad que proporcione un ejemplo del problema. Es importante no copiar el código completo de su programa; en su lugar, debe incluir solo el código suficiente y, si aplica, los datos o insumos necesarios para permitir a otros reproducir su problema. Para mayor información, puede revisar esta entrada de Stack Overflow sobre Cómo crear un ejemplo mínimo, completo y verificable.
Al seguir estas dos recomendaciones, se tendrá como resultado una descripción detallada y reproducible del problema que ayudará al equipo desarrollador (o, incluso, a otros miembros de la comunidad) a resolver el tema planteado de forma más rápida y sencilla.
Antes de publicar su issue, haga una última lectura y revisión del mismo. Trate de verlo con los ojos de una persona distinta (o, si puede, pídale a alguien más que lo revise) y evalúe si la información presentada es clara, completa y, si aplica, reproducible para poder entender y resolver el tema planteado.
Luego de hacer esta revisión, y de realizar los últimos cambios que considere necesarios, puede publicar el issue por medio del botón Submit new issue. Al hacer esto, el issue quedará publicado y se le será asignado un número único de identificación; puede guardar este número para consultar el estado de avance del mismo más adelante, o para referenciar este issue en otras discusiones dentro del repositorio de LEILA.
- Una vez su issue esté publicado, nuestro equipo responderá lo mas pronto posible para informarle que se ha recibido su contribución y, si es necesario, pidiendo más información sobre el tema solicitado para poder darle una solución adecuada.
- En algunas ocasiones el issue reportado puede no tener una respuesta sencilla o rápida de implementar. En estos casos, se pueden tomar distintas medidas como dividir la solicitud en acciones más pequeñas y/o incluir lo solicitado en el plan de mejora continua de la librería, estableciendo tiempos y responsables para lograr los objetivos planteados en el corto, mediano o largo plazo.
- Una vez que su reporte, pregunta o sugerencia haya sido respondida satisfactoriamente y no se reciban comentarios adicionales, se optará por cerrar el issue, indicando que se ha resuelto con éxito. Si lo desean, los usuarios y la comunidad en general pueden seguir comentando sobre issues que ya han sido cerrados.
Para mayor información sobre buenas prácticas al momento de crear un issue, lo invitamos a revisar las siguientes referencias.
