← Volver al listado de tecnologías ← Índice de .github de Cero a Experto

PR templates y Discussions

Por: Artiko
githubpull-requestsdiscussionstemplates

PR templates y Discussions

Así como los issue templates guían a quien reporta un bug, los pull request templates guían a quien abre un PR: precompletan la descripción con las secciones que tu proyecto quiere ver siempre (qué cambia, cómo probarlo, checklist). Menos PRs con la descripción vacía, menos ida y vuelta en la review.

Template único de PR

El caso más común: un solo template para todos los PRs. Creás el archivo PULL_REQUEST_TEMPLATE.md dentro de .github/ (también es válido en la raíz del repo o en docs/, pero .github/ es lo recomendado). GitHub toma su contenido y lo carga en el textarea de descripción cada vez que alguien abre un PR.

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Qué cambia

<!-- Describí en una o dos frases qué resuelve este PR. -->

## Cómo probarlo

1. …
2. …

## Checklist

- [ ] Los tests pasan localmente (`bun test`)
- [ ] Actualicé la documentación si hacía falta
- [ ] El PR apunta a la rama correcta

Los comentarios HTML (<!-- … -->) sirven como instrucciones para quien escribe: se ven al editar pero desaparecen del PR renderizado.

Nota: el nombre del archivo es case-insensitive, pero la convención es PULL_REQUEST_TEMPLATE.md en mayúsculas. Si el archivo está mal ubicado o mal nombrado, GitHub simplemente no lo carga (sin error visible).

Múltiples templates seleccionables

Cuando un proyecto tiene tipos de PR muy distintos (una feature, un hotfix, un cambio de docs), un solo template no alcanza. Para eso, en lugar de un archivo suelto usás una carpeta: .github/PULL_REQUEST_TEMPLATE/ (plural), con un .md por cada variante.

.github/PULL_REQUEST_TEMPLATE/
  feature.md
  hotfix.md
  docs.md

A diferencia de los issue templates, GitHub no muestra un menú de selección automático al pulsar “New pull request”. Elegís el template de dos formas:

flowchart TD
    START["Abrir un PR"] --> Q{"¿Cómo está<br/>configurado?"}
    Q -->|"PULL_REQUEST_TEMPLATE.md<br/>(archivo único)"| ONE["Se precarga siempre<br/>el mismo template"]
    Q -->|"PULL_REQUEST_TEMPLATE/<br/>(carpeta, varios .md)"| MANY["Se elige con<br/>?template=nombre.md<br/>o desde el dropdown"]
Template únicoMúltiples templates
Ubicación.github/PULL_REQUEST_TEMPLATE.md.github/PULL_REQUEST_TEMPLATE/ (carpeta)
SelecciónAutomática (siempre el mismo)?template=nombre.md o dropdown
Cuándo usarloUn flujo de PR homogéneoTipos de PR muy distintos

Templates de Discussions

GitHub Discussions es la feature de foro del repositorio (preguntas, anuncios, ideas), separada de las issues. Debe estar habilitada en el repo (Settings → Features → Discussions) para que aparezca la pestaña.

Igual que las issues tienen ISSUE_TEMPLATE/, las discusiones tienen su propia carpeta análoga: .github/DISCUSSION_TEMPLATE/. Cada archivo corresponde a una categoría de discusión y usa el mismo formato de YAML forms que los issue templates (bloques body: con type: input, textarea, dropdown, etc.).

# .github/DISCUSSION_TEMPLATE/ideas.yml
body:
  - type: textarea
    id: propuesta
    attributes:
      label: Tu idea
      description: Contanos qué proponés y qué problema resuelve.
    validations:
      required: true
  - type: dropdown
    id: area
    attributes:
      label: Área afectada
      options:
        - Frontend
        - Backend
        - Documentación

El nombre del archivo debe coincidir con el slug de la categoría de discusión que definís en la configuración del repo. Así, cuando alguien abre una discusión en esa categoría, ve el formulario en lugar de un campo vacío.

Nota: los templates de Discussions solo tienen efecto si Discussions está habilitado. Si la feature está apagada, la carpeta se ignora.

Recomendación práctica

Empezá con un PULL_REQUEST_TEMPLATE.md único con una checklist corta y accionable; es el mayor retorno por el menor esfuerzo. Pasá a la carpeta con múltiples templates solo cuando notes que un solo formato no cubre los distintos tipos de PR de tu proyecto.

Anterior → Capítulo 10: Issue templates · Siguiente → Capítulo 12: Dependabot

← Volver al listado de tecnologías ← Índice de .github de Cero a Experto