course/pr_1213/es/chapter8/5.md

Cómo escribir un buen issue[[how-to-write-a-good-issue]]

Cuando encuentres algo que no parece correcto en una de las librerías de Hugging Face, deberías hacérnoslo saber para que podamos solucionarlo. Lo mismo aplica, por supuesto, a cualquier librería de open source. Si no estás completamente seguro de si el error está en tu propio código o en una de nuestras librerías, el primer lugar donde deberías mirar es en los foros. La comunidad te ayudará a averiguarlo, y el equipo de Hugging Face también sigue de cerca las discusiones que se publican allí.

Cuando estés seguro de que tienes un bug entre manos, el primer paso es construir un ejemplo mínimo reproducible.

Crear un ejemplo mínimo reproducible[[creating-a-minimal-reproducible-example]]

Es muy importante aislar la parte del código que produce el bug, porque nadie en el equipo de Hugging Face es mago, al menos todavía, y no pueden arreglar lo que no pueden ver. Un ejemplo mínimo reproducible debe, como su nombre indica, ser reproducible. Esto significa que no debería depender de archivos externos ni de datos privados que solo tú tengas disponibles. Intenta sustituir los datos que estés usando por valores ficticios que se parezcan a los reales y sigan produciendo el mismo error.

🚨 Muchas incidencias (issues) en el repositorio de 🤗 Transformers se quedan sin resolver porque los datos usados para reproducirlas no son accesibles.

Una vez que tengas algo autocontenido, intenta reducirlo aún más hasta dejarlo en el menor número posible de líneas de código, construyendo lo que llamamos un ejemplo mínimo reproducible. Esto te exige un poco más de trabajo, pero casi garantiza que recibas ayuda y una solución si aportas un reproductor del bug claro y corto.

Si te sientes con confianza, ve a inspeccionar el código fuente donde ocurre tu error. Puede que encuentres una solución a tu problema, en cuyo caso incluso podrías proponer un pull request para arreglarlo. Pero, más en general, esto también puede ayudar a quienes mantienen la librería a entender mejor el origen del problema cuando lean tu reporte.

Rellenar la plantilla del issue[[filling-out-the-issue-template]]

Cuando abras tu issue, verás que hay una plantilla para completar. Aquí seguiremos la de issues de 🤗 Transformers, pero el mismo tipo de información suele hacer falta si reportas un problema en cualquier otro repositorio. No dejes la plantilla en blanco: tomarte el tiempo de rellenarla aumentará mucho las probabilidades de que recibas respuesta y de que tu problema se resuelva.

En general, cuando abras un issue, mantén siempre un tono cortés. Este es un proyecto de open source, así que estás usando software gratuito y nadie tiene obligación de ayudarte. Puedes incluir críticas justificadas si lo consideras necesario, pero quienes mantienen el proyecto pueden tomárselo mal y no sentirse especialmente motivados a ayudarte deprisa. Asegúrate de leer el código de conducta del proyecto.

Incluir la información de tu entorno[[including-your-environment-information]]

🤗 Transformers ofrece una utilidad para obtener toda la información que necesitamos sobre tu entorno. Solo tienes que escribir lo siguiente en tu terminal:

transformers-cli env

y deberías obtener algo como esto:

Copy-and-paste the text below in your GitHub issue and FILL OUT the two last points.

- `transformers` version: 4.12.0.dev0
- Platform: Linux-5.10.61-1-MANJARO-x86_64-with-arch-Manjaro-Linux
- Python version: 3.7.9
- PyTorch version (GPU?): 1.8.1+cu111 (True)
- Tensorflow version (GPU?): 2.5.0 (True)
- Flax version (CPU?/GPU?/TPU?): 0.3.4 (cpu)
- Jax version: 0.2.13
- JaxLib version: 0.1.65
- Using GPU in script?: 
- Using distributed or parallel set-up in script?: 

También puedes añadir un ! al principio del comando transformers-cli env para ejecutarlo desde una celda de notebook y luego copiar y pegar el resultado al principio de tu issue.

Etiquetar a personas[[tagging-people]]

Etiquetar a alguien escribiendo un @ seguido de su identificador de GitHub le enviará una notificación para que vea tu issue y quizá responda más rápido. Usa esto con moderación, porque a las personas que etiquetes puede no hacerles gracia recibir una notificación si no tienen relación directa con el problema. Si has revisado los archivos fuente relacionados con tu bug, deberías etiquetar a la última persona que hizo cambios en la línea que crees que está causando el problema. Puedes encontrar esa información buscando la línea en GitHub, seleccionándola y haciendo clic en "View git blame".

En caso contrario, la propia plantilla suele sugerir algunas personas a las que etiquetar. En general, no etiquetes nunca a más de tres personas.

Incluir un ejemplo reproducible[[including-a-reproducible-example]]

Si has logrado crear un ejemplo autocontenido que produce el bug, este es el momento de incluirlo. Escribe una línea con tres comillas invertidas seguidas de python, así:

```python

y luego pega tu ejemplo mínimo reproducible y termina con otra línea de tres comillas invertidas. Así te aseguras de que el código quede bien formateado.

Si no has conseguido crear un ejemplo reproducible, explica con pasos claros cómo llegaste a tu issue. Incluye, si puedes, un enlace a un notebook de Google Colab donde aparezca el error. Cuanta más información compartas, mejor podrán responderte quienes mantienen la librería.

En todos los casos, deberías copiar y pegar el mensaje de error completo que estás recibiendo. Si estás trabajando en Colab, recuerda que algunos marcos pueden aparecer colapsados automáticamente en el stack trace, así que asegúrate de expandirlos antes de copiarlo. Igual que con el ejemplo de código, coloca el mensaje de error entre dos líneas de tres comillas invertidas para que quede bien formateado.

Describir el comportamiento esperado[[describing-the-expected-behavior]]

Explica en unas pocas líneas qué esperabas obtener, para que quienes mantienen el proyecto entiendan completamente el problema. Esta parte suele ser bastante evidente, así que normalmente cabrá en una sola frase, aunque en algunos casos quizá tengas más cosas que contar.

¿Y después qué?[[and-then-what]]

Una vez que hayas publicado tu issue, revisa rápidamente que todo se vea bien. Puedes editarlo si cometiste un error, o incluso cambiar el título si te das cuenta de que el problema es distinto de lo que pensabas al principio.

No tiene sentido ir notificando a gente si no obtienes respuesta. Si nadie te ayuda en unos días, lo más probable es que nadie haya conseguido entender bien tu problema. No dudes en volver a tu ejemplo reproducible. ¿Puedes hacerlo más corto y más directo? Si no recibes respuesta en una semana, puedes dejar un mensaje pidiendo ayuda con educación, especialmente si has editado el issue para incluir más información sobre el problema.