GitHub Projects

Librería reusable y CLI para sincronizar backlog versionado en Markdown con GitHub Issues y GitHub Projects.

Objetivo

Permitir que cualquier repo consumidor mantenga su backlog como documentos versionados y publique ese estado en GitHub de forma reproducible, automatizable y auditable.

Capacidades actuales

• crear o reutilizar un GitHub Project a partir de configuración compartida
• crear y actualizar fields del project
• crear y actualizar labels estáticos y derivados en el repositorio destino
• empujar documentos EP-*.md y US-*.md hacia issues y project items con push
• sincronizar un documento puntual con push issue
• actualizar o reconstruir Markdown local desde issues y project items administrados con pull
• mantener relaciones padre/hijo mediante bloques administrados en el body del issue
• validar documentación antes de sincronizar
• autocorregir headings, aliases simples de frontmatter y doc_id mal ordenados cuando el padre es inequívoco
• emitir salidas JSON para validación, push, pull y sincronización completa

Inicio rápido

Pasos mínimos para poner a funcionar un repo consumidor:

1. instalar el paquete en el repo consumidor
2. crear docs/epics/project.env
3. crear docs/epics/github-projects.yml
4. crear una épica y una historia con frontmatter válido
5. validar documentos
6. inicializar o reconciliar el project
7. hacer push de la iniciativa

Lo mínimo que necesitas definir:

• docs/epics/project.env con PROJECT_OWNER, PROJECT_TITLE y opcionalmente PROJECT_NUMBER
• docs/epics/github-projects.yml con repository, include patterns y reglas de sync
• al menos una épica y una historia con doc_id, type, title, status, priority y parent_id cuando aplique
• opcionalmente issue_state si quieres controlar apertura o cierre del issue además del status del project

Ejemplo de arranque:

yarn add -D file:../github-projects
github-projects validate docs --fix --json
github-projects push project --dry-run
github-projects push project
github-projects push initiative --initiative EP-01-initiative-one --dry-run --fix-docs
github-projects push initiative --initiative EP-01-initiative-one --fix-docs

Navegación

• índice de documentación: docs/README.md
• configuración detallada: docs/CONFIGURATION.md
• convención documental: config/PROJECT_SYNC_CONVENTIONS.md
• operación diaria, ejemplos JSON y troubleshooting: docs/OPERATIONS.md

Requisitos

• Node.js 20+
• Yarn 1.x
• GitHub CLI gh instalado y autenticado
• scope project habilitado en gh para mutaciones reales sobre GitHub Projects

Instalación

Instalación local desde un repo consumidor vecino:

yarn add -D file:../github-projects

Instalación desde npm:

npm install -D @velion-solutions/github-projects

o con Yarn:

yarn add -D @velion-solutions/github-projects

Releases

El paquete usa release-it para manejar versión, tag git y publicación a npm.

Comandos disponibles:

yarn release:dry-run
yarn release

yarn release ejecuta este flujo:

• valida con yarn test, yarn typecheck y yarn build
• actualiza la versión en package.json
• crea commit y tag vX.Y.Z
• publica en npm con acceso público

Antes de correrlo necesitas:

• working tree limpio en git
• permisos de publicación sobre @velion-solutions/github-projects
• npm login válido o token con permisos de publish

Scripts típicos en el repo consumidor:

{
  "scripts": {
    "github-projects:push:project": "github-projects push project",
    "github-projects:push:initiative": "github-projects push initiative",
    "github-projects:push:issue": "github-projects push issue",
    "github-projects:push:labels": "github-projects push labels",
    "github-projects:push:all": "github-projects push all --fix-docs",
    "github-projects:pull:initiative": "github-projects pull initiative",
    "github-projects:pull:issue": "github-projects pull issue",
    "github-projects:pull:all": "github-projects pull all",
    "github-projects:validate:docs": "github-projects validate docs"
  }
}

Convención mínima

La convención detallada vive en config/PROJECT_SYNC_CONVENTIONS.md. En el README solo queda el resumen operativo:

• doc_id es la identidad estable del documento
• parent_id es la relación padre recomendada
• en historias, doc_id debe terminar con parent_id
• el título visible del issue usa una versión compacta derivada del doc_id

Comandos principales

• push: familia de comandos para sincronizar hacia GitHub sin duplicar operadores
• pull: familia de comandos para reconstruir o actualizar Markdown local desde GitHub
• validate: familia de comandos de validación local

Los ejemplos completos, salidas JSON y flujos operativos viven en docs/OPERATIONS.md.

Uso como librería

El paquete también expone funciones para ejecución desde scripts Node. El ejemplo completo de uso programático vive en docs/OPERATIONS.md.

Fuera de alcance actual

• importación arbitraria de issues no administrados por github-projects cuando no tienen Doc ID ni metadata suficiente
• resolución automática de conflictos cuando Markdown local y GitHub divergen al mismo tiempo
• manejo de dependencias entre múltiples repositorios en una sola operación
• publicación automática a npm

Checklist de cambio

• actualizar este README si cambia la forma de consumir el paquete
• actualizar docs/CONFIGURATION.md si cambia la resolución de configuración o las reglas de pull
• actualizar docs/OPERATIONS.md si cambian comandos, JSON o troubleshooting
• validar yarn typecheck
• validar yarn build
• validar al menos un flujo --dry-run cuando cambie el comportamiento de sincronización