Issue templates

En vez de un textarea vacío, GitHub puede ofrecer a quien abre una issue un menú de plantillas: “Bug report”, “Feature request”, etc. Cada plantilla precompleta la estructura para que llegue la información que necesitás. Todo vive en la carpeta .github/ISSUE_TEMPLATE/ (plural en el path, singular en el nombre exacto ISSUE_TEMPLATE).

Dos formatos

Formato	Extensión	Cómo se completa
Markdown clásico	.md	Front-matter + cuerpo Markdown que el usuario edita libremente
Issue forms YAML	.yml / .yaml	Formulario estructurado con campos tipados y validaciones

Template Markdown clásico

Un archivo .md con front-matter (name, about, title, labels, assignees) y un cuerpo que se pega como texto inicial de la issue:

---
name: Bug report
about: Reportar un comportamiento incorrecto
title: "[BUG] "
labels: bug
assignees: ""
---

**Descripción del bug**

**Pasos para reproducir**

**Comportamiento esperado**

Issue form YAML

Genera un formulario real con campos que el usuario completa. Todo archivo de issue form debe comenzar obligatoriamente con los pares name, description y body — donde body es un array de elementos de formulario.

name: Bug report
description: Reportar un fallo reproducible
labels: ["bug"]
body:
  - type: dropdown
    id: version
    attributes:
      label: Versión afectada
      options:
        - "5.x"
        - "4.x"
        - "< 4.0"
    validations:
      required: true
  - type: textarea
    id: pasos
    attributes:
      label: Pasos para reproducir
      description: Enumerá los pasos exactos
      render: bash
    validations:
      required: true

Elementos de un issue form

Tipo	Para qué
markdown	Texto informativo (no es un campo de entrada)
input	Una línea de texto simple
textarea	Texto multilínea; con render: opcional lo muestra como bloque de código
dropdown	Selección de una lista de options
checkboxes	Casillas para marcar (ej. confirmar que buscó duplicados)

Cada elemento puede llevar id, attributes.label y validations.required para volverlo obligatorio.

config.yml: la pantalla de selección

Un archivo config.yml dentro de .github/ISSUE_TEMPLATE/ configura el menú que ve el usuario antes de elegir plantilla:

blank_issues_enabled: false
contact_links:
  - name: Comunidad en Discord
    url: https://discord.gg/tu-servidor
    about: Preguntas de uso y ayuda rápida
  - name: GitHub Discussions
    url: https://github.com/org/repo/discussions
    about: Ideas y debate general

• blank_issues_enabled: false oculta la opción de abrir una issue en blanco, forzando el uso de una plantilla.
• contact_links (array de name, url, about) muestra enlaces a recursos externos — Discord, Discussions, Stack Overflow — para redirigir a quien no debería abrir una issue.

Así canalizás las preguntas de soporte fuera del issue tracker y te asegurás de que las issues reales lleguen con la estructura correcta.

---

Anterior → Capítulo 9: SECURITY.md · Siguiente → Capítulo 11: PR templates y Discussions