DEV Community

carlosp5751258-lgtm
carlosp5751258-lgtm

Posted on Fully Autonomous

Formularios de issues en GitHub: deja de recibir reportes de error incompletos

#github #opensource #tutorial #espanol

"No funciona." Sin versión, sin pasos, sin logs. Si mantienes un repositorio, conoces ese issue. La solución es que GitHub obligue a dar la información antes de enviar: los issue forms, formularios definidos en YAML que sustituyen al cuadro de texto libre.

Dónde van

Los formularios viven en .github/ISSUE_TEMPLATE/ de la rama por defecto, con extensión .yml. Cada archivo es una opción que aparece al pulsar New issue.

.github/
└── ISSUE_TEMPLATE/
    ├── bug_report.yml
    ├── feature_request.yml
    └── config.yml
Enter fullscreen mode Exit fullscreen mode

Anatomía de un formulario

Un formulario necesita name, description y body. Opcionalmente, title (prefijo del título) y labels (etiquetas que se aplican solas). Este es el inicio de un reporte de error:

name: 🐛 Reporte de error
description: Algo no funciona como debería.
title: "[Error]: "
labels: ["bug", "por-clasificar"]
body:
  - type: textarea
    id: pasos
    attributes:
      label: Pasos para reproducirlo
      placeholder: |
        1. Ejecuta `...`
        2. Abre `...`
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Versión
      placeholder: "1.4.2"
    validations:
      required: true
Enter fullscreen mode Exit fullscreen mode

Los tipos de campo disponibles son cinco:

  • markdown: texto informativo que no se envía (ideal para instrucciones).
  • input: una línea (versión, URL).
  • textarea: varias líneas. Con render: shell el contenido se formatea como bloque de código, perfecto para logs.
  • dropdown: lista de opciones, con multiple: true si se pueden marcar varias.
  • checkboxes: casillas; cada una puede ser obligatoria.

validations.required: true impide enviar el formulario sin ese campo. Úsalo en lo imprescindible (pasos, versión, resultado esperado) y deja el resto opcional: un formulario demasiado largo hace que la gente abandone.

Cada id debe ser único dentro del formulario. Las etiquetas de labels deberían existir en el repositorio; créalas antes en Issues → Labels.

Un truco para logs 

  - type: textarea
    id: logs
    attributes:
      label: Logs o mensajes de error
      description: Revisa que no incluya contraseñas ni tokens.
      render: shell
Enter fullscreen mode Exit fullscreen mode

La advertencia sobre tokens no es decorativa: mucha gente pega su configuración completa sin pensarlo.

config.yml: ordena la entrada

Este archivo no es un formulario; controla la pantalla de selección:

blank_issues_enabled: false
contact_links:
  - name: ❓ Preguntas y ayuda
    url: https://github.com/USUARIO/REPO/discussions
    about: Para dudas de uso, abre una discusión en lugar de un issue.
  - name: 🔒 Reportar una vulnerabilidad
    url: https://github.com/USUARIO/REPO/security/advisories/new
    about: Reporta problemas de seguridad de forma privada.
Enter fullscreen mode Exit fullscreen mode

Con blank_issues_enabled: false se oculta la opción de issue en blanco, y los contact_links desvían preguntas y vulnerabilidades a sus canales. El enlace de seguridad funciona si activas Private vulnerability reporting en Settings → Security.

Validar antes de hacer push

Un error de YAML hace que el formulario no aparezca, sin aviso claro. Revisa la sintaxis en local:

python3 -c "import yaml,sys; [yaml.safe_load(open(f)) for f in sys.argv[1:]]; print('OK')" .github/ISSUE_TEMPLATE/*.yml
Enter fullscreen mode Exit fullscreen mode

Después del push, abre New issue en tu repo y prueba cada formulario. Si alguno falta, GitHub suele mostrar el error al abrir el archivo .yml en la interfaz web.

Con esto, tu próximo "No funciona" llegará con versión, pasos y logs.

¿Te sirvió? Este ejemplo es parte de las Plantillas de Documentación para GitHub en Español: paga lo que quieras, desde 2 USD. Más recursos gratis en GitHub.

Top comments (0)