Skip to main content

ADR ↔ Discussions workflow

Filosofía​

Las ideas se conversan en GitHub Discussions (categoría Ideas). Cuando una conversación madura y el equipo quiere formalizar la decisión, cualquier miembro con write access comenta /adr en el hilo y un workflow:

  1. Crea un PR con un ADR stub (frontmatter + secciones vacías).
  2. El stub ya trae discussion: <número> apuntando al hilo original.
  3. Postea en la Discussion el link al PR.

La Discussion no se cierra al mergear el PR: queda como hilo permanente para amendments, clarificaciones y revisitar la decisión después.

No hay categoría Decisions separada. Para un equipo pequeño, crear otro canal de conversación sería ceremonia innecesaria.

Flow​

  Ideas (Discussions)
         │
         ▼  conversación libre, días o semanas
         │
    alguien comenta:
         /adr
         │
         ▼
 .github/workflows/adr-from-discussion.yml
    1. Guard: /adr + category=ideas + write access
    2. Checkout main
    3. Next ADR number = max(files en docs/adrs/) + 1
    4. Crea branch adr/NNNN-<slug-from-title>
    5. Escribe docs/adrs/NNNN-<slug>.md con:
         - frontmatter (title, status:Proposed, date, discussion:<num>)
         - secciones vacías + :::info bootstrap note
    6. gh pr create
    7. Reacciona al /adr con 🚀
    8. Comenta en la Discussion con el link del PR
         │
         ▼
  Autor del ADR completa el contenido, abre review
         │
         ▼
  PR merge → ADR publicado
  (Discussion sigue abierta como canal permanente)

Cómo usarlo​

Escenario 1: ADR nace de una discusión​

  1. Abrir Discussion en la categoría Ideas, título = título futuro del ADR.
  2. Discutir libremente (sin ceremonia).
  3. Cuando hay consenso, alguien comenta simplemente: 
    /adr
  4. En ~30 segundos el bot abre un PR y comenta con el link.
  5. Editar el PR, completar secciones, pedir review, mergear.

Escenario 2: ADR sin Discussion previa​

Algunas decisiones son obvias y no merecen un hilo. Abrir el PR directamente copiando docs/adrs/template.md. El card renderiza No discussion linked en la fila Discussion — es informativo, no bloquea nada.

Triple guard del workflow (cero costo cuando no matchea)​

if: |
  startsWith(github.event.comment.body, '/adr') &&
  github.event.discussion.category.slug == 'ideas' &&
  contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'),
           github.event.comment.author_association)
  • Comentarios normales → workflow run marcado como Skipped, no se asigna runner, cero minutos consumidos.
  • /adr fuera de la categoría Ideas → skipped.
  • /adr de alguien sin write access → skipped (evita abuso por outside contributors).

Setup (una vez)​

Estos pasos requieren admin y UI web:

  1. Habilitar Discussions en el repo: Settings → General → Features → Discussions. ✅ Ya habilitado.
  2. Categoría Ideas: viene por defecto cuando habilitas Discussions. ✅ Ya existe.
  3. Workflow permissions: el workflow declara explícitamente contents: write, discussions: write, pull-requests: write. No necesitas cambiar el default.

Permissions del token​

La acción usa GITHUB_TOKEN default con:

  • contents: write — crear branch, commit, push
  • discussions: write — comentar y reaccionar en la Discussion
  • pull-requests: write — abrir PR

Si/cuando se cambie a la GitHub App eigenoid-release-bot, los scopes son idénticos — solo swappear el token env var.

Troubleshooting​

  • Comenté /adr y no pasa nada
    • ¿La Discussion está en la categoría Ideas? (otras categorías no disparan)
    • ¿Tienes write access al repo? (outside contributors son filtrados)
    • Revisa Actions tab: busca el run "ADR from Discussion". Si está en Skipped, el guard rechazó. Si está en Failed, revisa logs.
  • PR se creó pero la Discussion no muestra el comentario
    • Puede ser race/delay de la API. Refrescar en 30s. Si persiste, revisar logs.
  • "File already exists"
    • Dos /adr simultáneos en distintos hilos chocaron. Uno se crea, el otro falla. Re-comentar /adr y tomará el siguiente número libre.
  • Discussion original vinculada a ADR mergeado queda huérfana
    • Por diseño. La dejamos abierta permanentemente como canal de follow-ups post-Accepted.
  • ADR template: docs/adrs/template.md
  • Workflow: .github/workflows/adr-from-discussion.yml
  • Script: .github/scripts/bootstrap-adr-from-discussion.mjs