Contributing

Colaboración controlada — Cómo contribuir código generado por IA al repositorio institucional

Estrategia de branching

main        ← Producción (solo merges aprobados)
  ↑
staging     ← Validación antes de producción
  ↑
develop     ← Integración de features completados
  ↑
feature/*   ← Trabajo individual con IA

Ramas principales

Flujo de trabajo

1. Crear rama feature

git checkout develop
git pull origin develop
git checkout -b feature/descripcion-breve

2. Trabajar con IA

Al trabajar con herramientas de IA:

• Usar commits frecuentes para rastrear cambios
• Documentar prompts usados en commit messages
• Revisar cada sugerencia antes de aplicar

# Commit con referencia al prompt usado
git commit -m "feat: agregar endpoint de usuarios

- Prompt: 'crear endpoint GET /users que retorne lista con paginación'
- Constraints aplicados: auth required, pagination params"

3. Push y abrir PR

git push origin feature/descripcion-breve

En GitLab: New Merge Request → a rama staging

4. Template de PR

## Descripción

<!-- Qué hace este cambio y por qué es necesario -->

## Tipo de cambio

- [ ] Nueva funcionalidad
- [ ] Corrección de bug
- [ ] Refactor
- [ ] Documentación

## Prompt utilizado

<!-- Copiar el prompt que generó el código principal -->

## Constraints aplicados

<!-- Lista de constraints de seguridad/organización considerados -->

## Screenshots (si aplica)

<!-- Agregar evidencia visual si hay cambios de UI -->

## Checklist

- [ ] Tests agregados/actualizados
- [ ] Documentación actualizada
- [ ] No hay credenciales hardcodeadas
- [ ] Código sigue lineamientos DTI
- [ ] Revisión de seguridad básica realizada

## Notas adicionales

<!-- Cualquier contexto relevante para el reviewer -->

5. Revisión técnica

El reviewer debe verificar:

1. Lógica de negocio — ¿El código hace lo que dice?
2. Seguridad — ¿Credenciales expuestas? ¿Input validation? ¿SQL injection?
3. Patrones — ¿Código consistente con el resto del proyecto?
4. Tests — ¿Hay tests? ¿cubren el comportamiento?
5. Documentación — ¿Código documentado? ¿README actualizado?

# Aprobar PR en GitLab después de revisión satisfactoria
# El merge puede ser automático si todos los checks pasan

6. Merge a staging

# Una vez PR aprobado y checks pasando
# GitLab hace merge automático a staging
# Pipeline ejecuta deploy a ambiente staging

7. Validación en staging

Probar cambios en staging antes de solicitar merge a producción.

8. Merge a producción

Crear PR de staging a main para deployment final.

Template de prompts con constraints

Al pedir a la IA que genere código, incluir:

Genera [tipo de funcionalidad] siguiendo estos constraints:

SEGURIDAD:
- No hardcodear credenciales; usar variables de entorno
- Validar y sanitizar todo input de usuario
- Usar prepared statements para queries SQL
- Implementar rate limiting en endpoints públicos

ORGANIZACIÓN:
- Estructura: routes/, services/, models/, schemas/
- Nombrar archivos en kebab-case: user-routes.py
- Funciones: verbos + sustantivos: get_user_by_id()
- Typing: usar type hints en todas las funciones

CALIDAD:
- Tests unitarios para lógica de negocio
- Docstrings en funciones públicas
- Manejo de errores con mensajes descriptivos
- Logging para operaciones críticas

OUTPUT:
- Código completo y funcional
- Sin placeholders o TODOs
- Ejemplos de uso en comentarios

Buenas prácticas

• Commits atómicos — Un commit = un cambio pequeño y completo
• Mensajes descriptivos — Explicar el “por qué” no solo el “qué”
• Revisiones pequeñas — PRs grandes son difíciles de revisar; preferir features pequeños
• Tests primero — Si la IA sugiere tests, revisarlos cuidadosamente

Referencias

• Herramientas — Configuración de VS Code y Git
• Docker y CI/CD — Pipeline de deployment