contribution-workflow-research.md

Investigación de Flujo de Trabajo de Contribución Externa

🌐 EN | PT | ES

---

Historia: COLLAB-1 Fecha: 2025-12-30 Autor: @dev (Dex) + @devops (Gage) Estado: Completo

---

Resumen Ejecutivo

Este documento consolida los hallazgos de investigación sobre mejores prácticas para flujos de trabajo de contribuidores externos en proyectos de código abierto, específicamente para habilitar contribuciones seguras de la comunidad a agentes y tareas de AIOX.

---

1. Mejores Prácticas de Protección de Ramas en GitHub

1.1 Recomendaciones de la Industria

Basado en investigación de GitHub Docs, DEV Community, y Legit Security:

Regla de Protección	Recomendación	Justificación
Revisiones de PR requeridas	Habilitar con 1-2 revisores	Previene código sin revisar de hacer merge
Requerir revisiones de code owner	Habilitar	Asegura que expertos del dominio revisen cambios
Descartar revisiones obsoletas	Habilitar	Fuerza re-revisión después de nuevos cambios
Status checks requeridos	CI debe pasar	Detecta fallos de build/test antes del merge
Requerir resolución de conversación	Habilitar	Asegura que todo feedback sea atendido
Restringir force pushes	Deshabilitar force push	Previene reescritura del historial
Requerir historial lineal	Opcional	Historial git más limpio (considerar para monorepos)

1.2 Hallazgos Clave

"Los colaboradores con acceso de escritura a un repositorio tienen permisos completos de escritura en todos sus archivos e historial. Aunque esto es bueno para la colaboración, no siempre es deseable."

Punto Crítico: La protección de ramas es una de las consideraciones de seguridad más importantes. Puede prevenir que código no deseado sea pusheado a producción.

1.3 Configuración Recomendada para Open Source

branch_protection:
  require_pull_request_reviews:
    required_approving_review_count: 1 # Al menos 1 aprobación
    dismiss_stale_reviews: true # Re-revisar después de cambios
    require_code_owner_reviews: true # Aprobación de experto del dominio
    require_last_push_approval: false # Opcional para OSS

  required_status_checks:
    strict: true # Rama debe estar actualizada
    contexts:
      - lint
      - typecheck
      - build
      - test # Crítico para calidad

  restrictions:
    users: []
    teams: ['maintainers']

  allow_force_pushes: false
  allow_deletions: false
  required_conversation_resolution: true # Atender todo feedback

---

2. Mejores Prácticas de Configuración CodeRabbit

2.1 Documentación Oficial

De CodeRabbit Docs y awesome-coderabbit:

Elementos Clave de Configuración:

Elemento	Propósito	Recomendación
language	Idioma de respuesta	Coincidir con idioma del proyecto (pt-BR o en-US)
reviews.auto_review	Revisiones automáticas de PR	Habilitar para OSS
reviews.path_instructions	Reglas de revisión por ruta	Esencial para validación de agentes/tareas
chat.auto_reply	Responder a comentarios	Habilitar para mejor experiencia del contribuidor

2.2 Ejemplos del Mundo Real

TEN Framework (.coderabbit.yaml):

language: 'en-US'
reviews:
  profile: 'chill'
  high_level_summary: true
  auto_review:
    enabled: true
tools:
  ruff:
    enabled: true
  gitleaks:
    enabled: true

Proyecto PHARE:

path_instructions:
  '**/*.cpp':
    - 'Verificar fugas de memoria'
    - 'Verificar seguridad de hilos'
tools:
  shellcheck:
    enabled: true
  markdownlint:
    enabled: true

NVIDIA NeMo RL:

auto_title_instructions: |
  Formato: "<categoría>: <título>"
  Categorías: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
  Título debe ser <= 80 caracteres

2.3 Recomendaciones Específicas para AIOX

Para contribuciones de agentes/tareas, CodeRabbit debe validar:

1. Estructura YAML de agentes - persona_profile, commands, dependencies
2. Formato de tareas - puntos de elicitación, entregables
3. Documentación - Actualizaciones de README, referencias a guías
4. Seguridad - Sin secretos hardcodeados, permisos apropiados

---

3. Mejores Prácticas de CODEOWNERS

3.1 Patrones de la Industria

De Harness Blog, Satellytes, y GitHub Docs:

Principios Clave:

Principio	Descripción
Última coincidencia gana	Patrones posteriores sobrescriben anteriores
Usar comodines	Consolidar entradas con * y **
Equipos sobre usuarios	Más fácil mantener cuando personas cambian
Granularidad	Balance entre muy amplio y muy específico

3.2 Patrones de Monorepo

# Propietario por defecto (fallback)
* @org/maintainers

# Propiedad de directorio (más específico)
/src/auth/ @org/security-team
/src/api/ @org/backend-team
/src/ui/ @org/frontend-team

# Propiedad por tipo de archivo
*.sql @org/dba-team
Dockerfile @org/devops-team

# Archivos críticos (requieren revisión senior)
/.github/ @org/core-team
/security/ @org/security-team

3.3 Estructura Específica de AIOX

# Por defecto - requiere revisión de maintainer
* @SynkraAI/maintainers

# Definiciones de agentes - requiere equipo core
.aiox-core/development/agents/ @SynkraAI/core-team

# Definiciones de tareas - requiere equipo core
.aiox-core/development/tasks/ @SynkraAI/core-team

# CI/CD - requiere aprobación devops
.github/ @SynkraAI/devops

# Documentación - más permisivo para contribuidores
docs/ @SynkraAI/maintainers

# Plantillas - requiere revisión de arquitecto
templates/ @SynkraAI/core-team
.aiox-core/product/templates/ @SynkraAI/core-team

---

4. Checks Requeridos de GitHub Actions

4.1 Mejores Prácticas

De GitHub Docs y discusiones de la comunidad:

Hallazgo Crítico:

"Si un check falla, GitHub previene el merge del PR. Sin embargo, jobs omitidos reportan 'Success' y no previenen el merge."

Patrón de Solución (job alls-green):

jobs:
  lint:
    runs-on: ubuntu-latest
    # ...

  test:
    runs-on: ubuntu-latest
    # ...

  alls-green:
    name: Todos los Checks Pasaron
    runs-on: ubuntu-latest
    needs: [lint, test]
    if: always()
    steps:
      - name: Verificar que todos los jobs pasaron
        run: |
          if [ "${{ needs.lint.result }}" != "success" ]; then exit 1; fi
          if [ "${{ needs.test.result }}" != "success" ]; then exit 1; fi

4.2 Checks Requeridos Recomendados

Check	Tipo	Prioridad
lint	Requerido	ALTA
typecheck	Requerido	ALTA
build	Requerido	ALTA
test	Requerido	ALTA
story-validation	Opcional	MEDIA
ide-sync-validation	Opcional	BAJA
alls-green	Requerido	ALTA (job resumen)

---

5. Ejemplos de Flujo de Contribución OSS

5.1 Next.js

De Next.js Contribution Guide:

• Flujo de fork y PR
• Verificación automática de formateo Prettier
• Requiere revisión de PR de maintainers
• Usa Turborepo para gestión de monorepo

5.2 Prisma

De Prisma CONTRIBUTING.md:

Requisitos Clave:

• Firma de CLA requerida
• Mensajes de commit estructurados
• Tests deben cubrir cambios
• Tamaño de bundle monitoreado (<6MB)
• CI/CD debe pasar (lint, test, cross-platform)

Flujo de Trabajo:

1. Clonar repositorio
2. Crear rama de feature
3. Hacer cambios + tests
4. Enviar PR con descripción
5. Firmar CLA
6. Esperar revisión

5.3 Patrones Comunes

Patrón	Adopción	Recomendación
Flujo de fork	Muy común	Adoptar
Firma de CLA	Común en OSS corporativo	Opcional por ahora
Commits convencionales	Muy común	Ya adoptado
Aprobaciones requeridas	Universal	Adoptar (1 aprobación)
CODEOWNERS	Común	Adoptar (granular)
CodeRabbit/revisión IA	En crecimiento	Adoptar

---

6. Consideraciones de Seguridad

6.1 Flujo Fork vs Rama Directa

Aspecto	Flujo Fork	Rama Directa
Seguridad	Mayor (aislado)	Menor (repo compartido)
Acceso contribuidor	Sin escritura necesaria	Acceso escritura necesario
CI/CD	Corre en contexto fork	Corre en repo principal
Secretos	Protegidos	Accesibles
Complejidad	Ligeramente mayor	Menor

Recomendación: Flujo fork para contribuidores externos (ya documentado en CONTRIBUTING.md)

6.2 Protección de Secretos en PRs

• Nunca exponer secretos en logs de CI
• Usar pull_request_target con cuidado
• Limitar alcances de secretos
• Auditar autores de PR por patrones sospechosos

---

7. Recomendaciones para AIOX

7.1 Acciones Inmediatas (CRÍTICO)

1. Habilitar revisiones aprobatorias requeridas (required_approving_review_count: 1)
2. Habilitar revisiones de code owner (require_code_owner_reviews: true)
3. Agregar test a status checks requeridos

7.2 Acciones a Corto Plazo (ALTO)

1. Crear .coderabbit.yaml con instrucciones de ruta específicas de AIOX
2. Actualizar CODEOWNERS con propiedad granular
3. Habilitar resolución de conversación requerida

7.3 Acciones a Mediano Plazo (MEDIO)

1. Crear plantillas de PR especializadas para contribuciones de agentes/tareas
2. Mejorar CONTRIBUTING.md con checklist de contribución de agentes
3. Agregar guía de onboarding para contribuidores

7.4 Baja Prioridad (NICE TO HAVE)

1. Agregar bot de CLA para protección legal
2. Implementar automatización de PRs obsoletos
3. Agregar dashboard de métricas de contribución

---

8. Fuentes

Protección de Ramas

• GitHub Docs: Managing Branch Protection Rules
• DEV Community: Best Practices for Branch Protection
• Legit Security: GitHub Security Best Practices

CodeRabbit

• CodeRabbit YAML Configuration
• awesome-coderabbit Repository
• TEN Framework .coderabbit.yaml

CODEOWNERS

• Harness: Mastering CODEOWNERS
• GitHub Docs: About Code Owners
• Satellytes: Monorepo CODEOWNERS

GitHub Actions

• GitHub Docs: About Status Checks
• GitHub Blog: Required Workflows

Ejemplos OSS

• Next.js Contribution Guide
• Prisma CONTRIBUTING.md

---

Documento generado como parte de la Historia COLLAB-1 investigación.