paperless-ngx/GITHUB_PROJECT_SETUP.md

📋 GitHub Projects - Configuración y Estructura

Documento: Guía completa para configurar GitHub Projects para IntelliDocs-ngx
Fecha: 2025-11-09
Autoridad: Siguiendo directivas de agents.md

---

🎯 Visión General

Este documento proporciona las instrucciones paso a paso para crear y configurar el GitHub Project que rastreará el progreso del ROADMAP_2026.md de IntelliDocs-ngx.

---

📊 Estructura del Project

Información General del Project

• Nombre: IntelliDocs-ngx Roadmap 2026
• Descripción: Plan anual de desarrollo e implementación para IntelliDocs-ngx
• Template: Board (Kanban) + Roadmap views
• Visibilidad: Privado (solo equipo)

---

🚀 Paso 1: Crear el GitHub Project

Opción A: Desde la Interfaz Web

1. Ir a: https://github.com/orgs/dawnsystem/projects (si es organización) O: https://github.com/dawnsystem/IntelliDocs-ngx/projects (si es repo)

2. Click en "New project"

3. Seleccionar template: "Board"

4. Configurar:

   • Project name: IntelliDocs-ngx Roadmap 2026
   • Description: Hoja de ruta completa para el año 2026. 12 Epics, 147 tareas, distribuidas en 4 trimestres.
   • Visibility: Private

5. Click "Create project"

Opción B: Mediante GitHub CLI

# Instalar GitHub CLI si no está instalado
# brew install gh (macOS)
# apt install gh (Ubuntu/Debian)

# Autenticar
gh auth login

# Crear proyecto
gh project create \
  --owner dawnsystem \
  --title "IntelliDocs-ngx Roadmap 2026" \
  --body "Hoja de ruta completa para el año 2026. 12 Epics, 147 tareas, distribuidas en 4 trimestres."

---

📋 Paso 2: Configurar Columnas (Board View)

Crear las siguientes columnas en el Board:

Columnas del Kanban

1. 📥 Backlog

   • Status: Backlog
   • Descripción: Tareas no iniciadas, priorizadas para futuro

2. 📅 Planned (Q1-Q4)

   • Status: Planned
   • Descripción: Tareas planificadas con trimestre asignado

3. 🔨 In Progress

   • Status: In Progress
   • Descripción: Tareas en desarrollo activo

4. 👀 In Review

   • Status: In Review
   • Descripción: Tareas completadas, esperando code review

5. 🧪 Testing

   • Status: Testing
   • Descripción: Features en QA y testing

6. ✅ Done

   • Status: Done
   • Descripción: Tareas completadas y mergeadas

7. 🚫 Blocked

   • Status: Blocked
   • Descripción: Tareas bloqueadas por dependencias

---

🏷️ Paso 3: Configurar Labels (Etiquetas)

Labels por Prioridad

🔴 priority: critical
🟠 priority: high
🟡 priority: medium
🟢 priority: low

Labels por Epic

epic: 01-testing-qa
epic: 02-api-docs
epic: 03-performance
epic: 04-encryption
epic: 05-mobile
epic: 06-cloud-sync
epic: 07-analytics
epic: 08-collaboration
epic: 09-multi-tenancy
epic: 10-compliance
epic: 11-blockchain
epic: 12-ar-vr

Labels por Trimestre

Q1-2026 (Enero-Marzo)
Q2-2026 (Abril-Junio)
Q3-2026 (Julio-Septiembre)
Q4-2026 (Octubre-Diciembre)

Labels por Tipo

type: feature
type: enhancement
type: bug
type: documentation
type: test
type: infrastructure

Labels por Área

area: backend
area: frontend
area: mobile
area: devops
area: ml-ai
area: ocr
area: security

Comandos para crear labels (GitHub CLI)

# Prioridades
gh label create "priority: critical" --color "d73a4a" --description "Prioridad crítica"
gh label create "priority: high" --color "ff9900" --description "Prioridad alta"
gh label create "priority: medium" --color "fbca04" --description "Prioridad media"
gh label create "priority: low" --color "0e8a16" --description "Prioridad baja"

# Epics (12 totales)
gh label create "epic: 01-testing-qa" --color "0052cc" --description "EPIC 1: Testing y QA"
gh label create "epic: 02-api-docs" --color "0052cc" --description "EPIC 2: API Docs"
gh label create "epic: 03-performance" --color "0052cc" --description "EPIC 3: Performance"
gh label create "epic: 04-encryption" --color "0052cc" --description "EPIC 4: Encriptación"
gh label create "epic: 05-mobile" --color "0052cc" --description "EPIC 5: Mobile App"
gh label create "epic: 06-cloud-sync" --color "0052cc" --description "EPIC 6: Cloud Sync"
gh label create "epic: 07-analytics" --color "0052cc" --description "EPIC 7: Analytics"
gh label create "epic: 08-collaboration" --color "0052cc" --description "EPIC 8: Colaboración"
gh label create "epic: 09-multi-tenancy" --color "0052cc" --description "EPIC 9: Multi-tenancy"
gh label create "epic: 10-compliance" --color "0052cc" --description "EPIC 10: Compliance"
gh label create "epic: 11-blockchain" --color "0052cc" --description "EPIC 11: Blockchain"
gh label create "epic: 12-ar-vr" --color "0052cc" --description "EPIC 12: AR/VR"

# Trimestres
gh label create "Q1-2026" --color "fbca04" --description "Trimestre 1 (Enero-Marzo)"
gh label create "Q2-2026" --color "fbca04" --description "Trimestre 2 (Abril-Junio)"
gh label create "Q3-2026" --color "fbca04" --description "Trimestre 3 (Julio-Septiembre)"
gh label create "Q4-2026" --color "fbca04" --description "Trimestre 4 (Octubre-Diciembre)"

# Tipos
gh label create "type: feature" --color "a2eeef" --description "Nueva funcionalidad"
gh label create "type: enhancement" --color "a2eeef" --description "Mejora de funcionalidad existente"
gh label create "type: bug" --color "d73a4a" --description "Bug fix"
gh label create "type: documentation" --color "0075ca" --description "Documentación"
gh label create "type: test" --color "d4c5f9" --description "Testing"
gh label create "type: infrastructure" --color "fef2c0" --description "Infraestructura"

# Áreas
gh label create "area: backend" --color "c5def5" --description "Backend (Python/Django)"
gh label create "area: frontend" --color "c5def5" --description "Frontend (Angular/TypeScript)"
gh label create "area: mobile" --color "c5def5" --description "Mobile (React Native)"
gh label create "area: devops" --color "c5def5" --description "DevOps/CI-CD"
gh label create "area: ml-ai" --color "c5def5" --description "Machine Learning / AI"
gh label create "area: ocr" --color "c5def5" --description "OCR Avanzado"
gh label create "area: security" --color "c5def5" --description "Seguridad"

---

📊 Paso 4: Configurar Custom Fields

Agregar campos personalizados al project para tracking avanzado:

1. Epic (Single Select)

• Nombre: Epic
• Tipo: Single select
• Opciones:
  • EPIC 1: Testing y QA
  • EPIC 2: API Docs
  • EPIC 3: Performance
  • EPIC 4: Encriptación
  • EPIC 5: Mobile App
  • EPIC 6: Cloud Sync
  • EPIC 7: Analytics
  • EPIC 8: Colaboración
  • EPIC 9: Multi-tenancy
  • EPIC 10: Compliance
  • EPIC 11: Blockchain
  • EPIC 12: AR/VR

2. Trimestre (Single Select)

• Nombre: Trimestre
• Tipo: Single select
• Opciones:
  • Q1 2026 (Enero-Marzo)
  • Q2 2026 (Abril-Junio)
  • Q3 2026 (Julio-Septiembre)
  • Q4 2026 (Octubre-Diciembre)

3. Estimación (Number)

• Nombre: Estimación (días)
• Tipo: Number
• Descripción: Tiempo estimado en días de trabajo

4. Prioridad (Single Select)

• Nombre: Prioridad
• Tipo: Single select
• Opciones:
  • 🔴 Crítica
  • 🟠 Alta
  • 🟡 Media
  • 🟢 Baja

5. Progreso (Number)

• Nombre: Progreso (%)
• Tipo: Number
• Descripción: Porcentaje de completitud (0-100)

6. Fecha Inicio (Date)

• Nombre: Fecha Inicio
• Tipo: Date
• Descripción: Fecha de inicio de la tarea

7. Fecha Fin (Date)

• Nombre: Fecha Fin
• Tipo: Date
• Descripción: Fecha objetivo de finalización

8. Responsable (Person)

• Nombre: Responsable
• Tipo: Person
• Descripción: Persona asignada a la tarea

---

🗺️ Paso 5: Crear Vista de Roadmap

1. En el project, click en "+ New view"

2. Seleccionar "Roadmap"

3. Configurar:

   • Name: Roadmap 2026
   • Date field (start): Fecha Inicio
   • Date field (end): Fecha Fin
   • Group by: Epic
   • Sort by: Fecha Inicio (ascending)

4. Guardar vista

Vista de Roadmap recomendada

• Mostrar markers por trimestre
• Color-code por prioridad
• Agrupar por Epic

---

📥 Paso 6: Importar Issues desde ROADMAP_2026.md

Opción A: Manual (recomendado para iniciar)

Para cada tarea en ROADMAP_2026.md:

1. Crear un Issue en GitHub:

   Título: TSK-2601: Tests para classifier.py (clasificación BERT)
   
   Descripción:
   **Epic:** EPIC 1: Testing y QA
   **Prioridad:** Alta
   **Estimación:** 2 días
   **Trimestre:** Q1 2026
   
   ## Subtareas
   - [ ] test_train_model
   - [ ] test_predict
   - [ ] test_save_load
   - [ ] test_edge_cases
   
   ## Aceptación
   - Tests passing
   - Cobertura >90%
   - Documentado
   

2. Asignar labels:

   • epic: 01-testing-qa
   • priority: high
   • Q1-2026
   • type: test
   • area: ml-ai

3. Agregar al Project:

   • Click en "Projects" en el issue
   • Seleccionar "IntelliDocs-ngx Roadmap 2026"
   • Configurar custom fields

Opción B: Script automatizado (para bulk import)

#!/usr/bin/env python3
"""
Script para importar tareas del ROADMAP_2026.md a GitHub Issues
Requiere: pip install PyGithub
"""

from github import Github
import os

# Configuración
GITHUB_TOKEN = os.environ.get('GITHUB_TOKEN')
REPO_NAME = 'dawnsystem/IntelliDocs-ngx'
PROJECT_NUMBER = 1  # Ajustar al número del project

# Conectar a GitHub
g = Github(GITHUB_TOKEN)
repo = g.get_repo(REPO_NAME)

# Definir tareas (ejemplo para EPIC 1)
tasks = [
    {
        'title': 'TSK-2601: Tests para classifier.py (clasificación BERT)',
        'body': '''**Epic:** EPIC 1: Testing y QA
**Prioridad:** Alta
**Estimación:** 2 días
**Trimestre:** Q1 2026

## Subtareas
- [ ] test_train_model
- [ ] test_predict
- [ ] test_save_load
- [ ] test_edge_cases

## Aceptación
- Tests passing
- Cobertura >90%
- Documentado''',
        'labels': ['epic: 01-testing-qa', 'priority: high', 'Q1-2026', 'type: test', 'area: ml-ai']
    },
    # ... más tareas
]

# Crear issues
for task in tasks:
    issue = repo.create_issue(
        title=task['title'],
        body=task['body'],
        labels=task['labels']
    )
    print(f"Created issue #{issue.number}: {issue.title}")

Opción C: Usar GitHub CLI con loops

#!/bin/bash
# create_issues.sh

# EPIC 1 - Ejemplo
gh issue create \
  --title "TSK-2601: Tests para classifier.py (clasificación BERT)" \
  --body "**Epic:** EPIC 1: Testing y QA
**Prioridad:** Alta
**Estimación:** 2 días
**Trimestre:** Q1 2026

## Subtareas
- [ ] test_train_model
- [ ] test_predict
- [ ] test_save_load
- [ ] test_edge_cases" \
  --label "epic: 01-testing-qa" \
  --label "priority: high" \
  --label "Q1-2026" \
  --label "type: test" \
  --label "area: ml-ai"

# Repetir para cada tarea...

---

📊 Paso 7: Configurar Vistas Adicionales

Vista 1: Por Prioridad

1. Crear nueva vista: "Por Prioridad"
2. Tipo: Board
3. Group by: Prioridad
4. Sort by: Fecha Inicio

Vista 2: Por Trimestre

1. Crear nueva vista: "Por Trimestre"
2. Tipo: Board
3. Group by: Trimestre
4. Sort by: Epic

Vista 3: Por Responsable

1. Crear nueva vista: "Por Responsable"
2. Tipo: Board
3. Group by: Responsable
4. Sort by: Prioridad

Vista 4: Lista Completa

1. Crear nueva vista: "Lista Completa"
2. Tipo: Table
3. Mostrar todas las columnas
4. Sort by: ID (TSK-XXXX)

---

🔄 Paso 8: Configurar Automation

Reglas de Automatización Recomendadas

1. Auto-mover a "In Progress" cuando se asigna

   • Trigger: Item assigned
   • Action: Set status to "In Progress"

2. Auto-mover a "In Review" cuando se abre PR

   • Trigger: Pull request opened
   • Action: Set status to "In Review"

3. Auto-mover a "Done" cuando se cierra issue

   • Trigger: Issue closed
   • Action: Set status to "Done"

4. Auto-calcular progreso del Epic

   • Usar GitHub Actions con script custom

Configurar en Project Settings > Workflows

# .github/workflows/project-automation.yml
name: Project Automation

on:
  issues:
    types: [opened, closed, assigned]
  pull_request:
    types: [opened, closed]

jobs:
  update-project:
    runs-on: ubuntu-latest
    steps:
      - name: Update project board
        uses: actions/add-to-project@v0.5.0
        with:
          project-url: https://github.com/orgs/dawnsystem/projects/1
          github-token: ${{ secrets.GITHUB_TOKEN }}

---

📈 Paso 9: Dashboard y Reporting

Insights y Métricas

En el Project, habilitar Insights para ver:

1. Burndown Chart

   • Visualizar progreso vs tiempo
   • Ajustar por trimestre

2. Velocity

   • Tareas completadas por sprint/semana
   • Identificar bottlenecks

3. Epic Progress

   • % completitud de cada epic
   • Timeline vs plan original

Export de Datos

# Exportar issues a CSV
gh project item-list 1 --owner dawnsystem --format csv > roadmap_export.csv

---

🔗 Paso 10: Integración con Repository

Linkar Issues con PRs

En cada Pull Request, referenciar el issue:

## Descripción
Implementa tests para el clasificador BERT.

## Issue Relacionado
Closes #123 (TSK-2601)

## Checklist
- [x] Tests añadidos
- [x] Tests passing
- [x] Documentación actualizada

Plantilla de PR

Crear .github/PULL_REQUEST_TEMPLATE.md:

## 📋 Descripción
<!-- Describe los cambios -->

## 🎯 Issue Relacionado
Closes #<!-- número del issue -->

## 🧪 Testing
- [ ] Tests unitarios añadidos
- [ ] Tests de integración añadidos
- [ ] Tests passing en CI/CD

## 📚 Documentación
- [ ] README actualizado
- [ ] BITACORA_MAESTRA.md actualizada
- [ ] Comentarios en código

## ✅ Checklist
- [ ] Code review solicitado
- [ ] Linter passing
- [ ] No breaking changes
- [ ] Security scan passed

---

👥 Paso 11: Permisos y Colaboradores

Asignar Roles

1. Admin: @dawnsystem (Director)

   • Puede editar project settings
   • Aprobar cambios al roadmap

2. Write: Developers

   • Pueden mover cards
   • Actualizar custom fields
   • Crear issues

3. Read: Stakeholders

   • Ver progreso
   • Comentar en issues

Configurar en Project Settings > Manage access

---

📊 Ejemplo de Estructura Final

IntelliDocs-ngx Roadmap 2026
├── 📋 Board View
│   ├── 📥 Backlog (20 items)
│   ├── 📅 Planned (50 items)
│   ├── 🔨 In Progress (5 items)
│   ├── 👀 In Review (2 items)
│   ├── 🧪 Testing (1 item)
│   ├── ✅ Done (15 items)
│   └── 🚫 Blocked (0 items)
│
├── 🗺️ Roadmap View
│   ├── Q1 2026 (42 tareas)
│   ├── Q2 2026 (38 tareas)
│   ├── Q3 2026 (35 tareas)
│   └── Q4 2026 (32 tareas)
│
├── 📊 Por Prioridad
│   ├── 🔴 Crítica (15)
│   ├── 🟠 Alta (50)
│   ├── 🟡 Media (65)
│   └── 🟢 Baja (17)
│
└── 📈 Insights
    ├── Burndown Chart
    ├── Velocity
    └── Epic Progress

---

🎓 Best Practices

1. Actualización Regular

• ✅ Actualizar status de tasks diariamente
• ✅ Review del project board en daily standup
• ✅ Update de custom fields al cambiar estado

2. Granularidad de Tasks

• ✅ Tasks no más de 3-5 días
• ✅ Si una task es >5 días, dividirla en subtasks
• ✅ Usar subtasks en el issue description

3. Documentación

• ✅ Cada task debe tener acceptance criteria
• ✅ Link a documentación técnica cuando aplique
• ✅ Screenshots/videos de cambios UI

4. Code Reviews

• ✅ PR reviews obligatorios antes de merge
• ✅ Mínimo 1 aprobación requerida
• ✅ CI/CD debe pasar antes de merge

5. Comunicación

• ✅ Comentar en issues, no en Slack/email
• ✅ Tag (@mention) a personas relevantes
• ✅ Usar reactions para quick feedback

---

🔗 Links Útiles

• GitHub Projects Docs: https://docs.github.com/en/issues/planning-and-tracking-with-projects
• GitHub CLI Docs: https://cli.github.com/manual/
• Project Templates: https://github.com/orgs/community/discussions/categories/project-templates

---

✅ Checklist de Setup Completo

• Project creado
• Columnas configuradas (7 columnas)
• Labels creados (30+ labels)
• Custom fields agregados (8 campos)
• Vista Roadmap creada
• Vistas adicionales creadas (4 vistas)
• Issues importados (147 tareas)
• Automation configurada
• Permisos asignados
• Documentación compartida con equipo
• First sprint planning scheduled

---

Próximos Pasos:

1. Crear el GitHub Project siguiendo esta guía
2. Importar las primeras 20-30 tareas del EPIC 1
3. Asignar responsables
4. Programar primera reunión de sprint planning
5. Configurar integración con Notion (ver NOTION_INTEGRATION_GUIDE.md)

---

Contacto:
Director: @dawnsystem
Fecha: 2025-11-09