🌊 Flujo de Trabajo y Metodología

En Rial AI seguimos una metodología de desarrollo estructurada que combina las mejores prácticas de la industria con herramientas modernas para garantizar código de calidad y colaboración efectiva.

📋 Protocolo interno de planificación, desarrollo y cierre de tareas

Este protocolo establece un flujo común para planificar, desarrollar, revisar y cerrar tareas, con tiempos de referencia, comunicación oportuna y responsabilidades claras.

Flujo general

Cada tarea debe pasar por estas etapas:

1. Asignación y definición inicial.
2. Comprensión y resolución de dudas.
3. Elaboración y revisión de la propuesta.
4. Aprobación de la propuesta y fecha límite.
5. Implementación.
6. Creación y revisión de la PR.
7. Corrección de comentarios.
8. Validación final y cierre.

La fecha límite corresponde al cierre completo de la tarea, no solamente a la creación de la PR.

Definición inicial de la tarea

La tarjeta debe incluir, en la medida de lo posible:

• Objetivo.
• Problema que se busca resolver.
• Alcance.
• Resultado esperado.
• Criterios de aceptación.
• Restricciones o información relevante.
• Prioridad, cuando corresponda.

Si los criterios de aceptación no están claros, deben aclararse antes de comenzar la implementación.

Comprensión y planificación

La persona responsable debe:

• Leer y analizar la tarjeta.
• Explicar su comprensión del objetivo.
• Identificar dudas, riesgos y dependencias.
• Proponer subtareas ordenadas.
• Identificar las áreas, archivos o servicios posiblemente involucrados.
• Definir cómo validará la solución.
• Estimar el trabajo.
• Proponer una fecha de cierre.

Las dudas que puedan afectar el alcance, la solución o la estimación deben comunicarse durante la primera parte de la planificación. No se debe utilizar toda la ventana de planificación sin informar oportunamente una duda o bloqueo.

Tiempo de referencia para la primera propuesta

• Tarea baja: entre 60 y 90 minutos.
• Tarea media: entre 2 y 3 horas.
• Tarea alta: hasta 4 horas.

Estos tiempos corresponden a la preparación de la propuesta, no al tiempo de espera por respuestas o comentarios de revisión.

La propuesta debe quedar publicada en la misma tarjeta y debe solicitarse explícitamente su revisión. La implementación comienza solo cuando la propuesta y la fecha han sido aprobadas.

Clasificación de dificultad

La dificultad se determina considerando:

• Alcance.
• Número de capas o componentes involucrados.
• Incertidumbre técnica.
• Dependencias.
• Riesgo de regresiones.

Baja

Cambio acotado, con solución conocida, pocas dependencias y validación simple.

Media

Requiere investigación o afecta más de un componente, pero el resultado esperado sigue siendo claro.

Alta

Involucra varias capas, decisiones técnicas nuevas, dependencias relevantes o un riesgo considerable de regresiones.

La clasificación puede actualizarse si la planificación revela que el alcance o la complejidad son distintos de lo inicialmente previsto. En ese caso, también deben revisarse la estimación y la fecha.

Implementación y seguimiento

La implementación comienza después de aprobar la propuesta y la fecha de cierre.

Durante el desarrollo se debe:

• Trabajar siguiendo las subtareas aprobadas.
• Actualizar el estado de la tarjeta.
• Informar cambios de alcance o riesgos nuevos.
• Comunicar los bloqueos apenas se detecten.
• Mantener visible el avance.

Para tareas bajas, basta con actualizar al terminar, abrir la PR o detectar un bloqueo. Para tareas medias o altas, debe existir al menos una actualización al finalizar cada jornada de trabajo.

Cada actualización debe indicar:

• Qué se completó.
• Qué se realizará después.
• Qué dificultades aparecieron.
• Si se mantiene la fecha comprometida.

Tiempo de implementación

Como referencia inicial:

• Tarea baja: entre 2 y 4 horas.
• Tarea media: entre 1 y 2 jornadas asignadas.
• Tarea alta: entre 3 y 5 jornadas asignadas.

Estos tiempos incluyen implementación, pruebas y preparación de la PR. No incluyen esperas por respuestas, revisiones o dependencias externas previamente comunicadas.

Requisitos antes de abrir una PR

Antes de solicitar revisión, la PR debe:

• Cumplir los criterios de aceptación.
• Tener todos los checks automáticos aprobados.
• Contar con una prueba manual del flujo afectado.
• Haber sido revisada por su propio autor.
• Tener una descripción clara del problema, la solución y la validación realizada.
• Incluir capturas o evidencia cuando corresponda.
• No contener archivos, logs ni cambios innecesarios.

Comentarios de PR

Los comentarios se clasifican según su impacto:

Triviales

Renombrar una función, corregir formato, ajustar un texto o mover una línea sin cambiar el comportamiento.

Referencia: entre 5 y 15 minutos por comentario, o hasta 30 minutos si se agrupan varios. Se debe revisar el diff y ejecutar solo los checks afectados, cuando corresponda.

Menores

Ajustes localizados que no cambian de manera relevante el comportamiento.

Referencia: hasta una hora agrupada, con validaciones específicas del área afectada.

Funcionales

Cambios de lógica, correcciones de errores o ajustes relacionados con los criterios de aceptación.

Requieren una estimación explícita, checks y una prueba manual relacionada.

Estructurales

Cambios de diseño, arquitectura o alcance.

Requieren conversar el enfoque y actualizar la estimación antes de continuar.

Las PR deben mantenerse activas y priorizadas. Los comentarios deben revisarse y responderse oportunamente. Si no es posible atenderlos por otra prioridad, se debe comunicar el motivo y acordar el orden de trabajo.

Ningún comentario debe quedar ignorado. Si existe desacuerdo técnico, debe explicarse y conversarse.

Bloqueos

Los riesgos previsibles deben identificarse durante la planificación.

Los bloqueos nuevos deben comunicarse apenas se detecten, indicando:

• Qué ocurrió.
• Qué se intentó.
• Qué se necesita.
• Cómo afecta la estimación o la fecha.

No se debe esperar hasta el vencimiento para informar un bloqueo ni consumir una parte significativa del tiempo disponible sin comunicarlo.

Cierre de la tarea

La tarea se considera cerrada cuando:

• La implementación está terminada.
• La PR fue revisada.
• Todos los comentarios fueron atendidos.
• Los checks finales pasan.
• La prueba manual está validada.
• La tarjeta está actualizada.
• La solución cuenta con la aprobación correspondiente.

📋 Estructura de Repositorios

Repositorios Principales

• Backend: github.com/Rial-Cenia/rial-backend 
• Frontend: github.com/Rial-Cenia/rial-frontend 

Ramas Principales

🌳 Estructura de Ramas

production     # Código en producción (rial-ai.com)
    ↑
develop       # Código en staging (staging.rial-ai.com)
    ↑
feature/*     # Ramas de desarrollo de funcionalidades
hotfix/*      # Correcciones urgentes para producción

Descripción de Ramas

• production: Código que está ejecutándose en rial-ai.com 
• develop: Código en ambiente de pruebas staging.rial-ai.com 
• feature/*: Ramas temporales para desarrollar nuevas funcionalidades
• hotfix/*: Correcciones urgentes que van directo a producción

🔄 Flujo de Desarrollo

1. 📝 Planificación en Jira

Antes de escribir código, toda tarea debe estar documentada en nuestro tablero de Jira. Trabajamos en sprints — ciclos de una o dos semanas donde se define qué tareas se van a completar.

Estructura en Jira

• Epics: Agrupan funcionalidades grandes o proyectos estratégicos
• Stories / Tasks: Tareas específicas asociadas a un epic
• Sprints: Ciclos de trabajo con tareas planificadas para esa semana o quincena

¿Qué es un KANBAN?

Un KANBAN es un sistema visual para gestionar trabajo. Organiza tareas en columnas que representan diferentes estados:

📋 Esta Semana: Lo que se debe realizar en el sprint actual
🧠 Craneando: Proceso de investigación para ver como realizar la tarea, comprenderla y armar un plan de acción
🔄 Chambeando: Tarea se está realizando
🧪 Testeando: Se está revisando que la tarea funciones de acuerdo a las expectativas o se está creando la PR o haciendo un rebase
⏸️ Pausado: Se ha priorizado otra tarea por lo que se debe poner en pausa momentaneamente
👀 En revisión: Se ha asignado un revisor en GitHub y en los canales internos para revisar la PR
⚠️ Corrigiendo Embarrás: Se hicieron comentarios en la PR y se está corrigiendo los cambios solicitados
✅ Listo: La tarea se encuentra aprobada y se ha hecho exitosamente el merge a develop

2. 🌿 Creación de Rama

# Asegúrate de estar en develop y actualizado
git checkout develop
git pull origin develop
 
# Crear nueva rama para tu tarea
git checkout -b feature/nombre-descriptivo-de-la-tarea

Convención de Nombres de Ramas

feature/user-authentication     # Nueva funcionalidad
fix/login-error-handling    # Corrección de bug
hotfix/critical-security-patch # Corrección urgente
refactor/database-queries      # Refactorización
docs/api-documentation         # Documentación
chores/dependencies-update     # Actualización de dependencias

3. 💻 Desarrollo

Desarrolla tu funcionalidad siguiendo las mejores prácticas:

Commits Frecuentes

Haz commits pequeños y frecuentes con mensajes descriptivos:

git add .
git commit -m "feat: add user login validation"
git commit -m "test: add unit tests for login service"
git commit -m "docs: update API documentation"

Testea linters, formatter y errores de tipos

# Backend
yarn lint
yarn tsc --noEmit
 
# Frontend
yarn lint
yarn tsc --noEmit
yarn format

Testing Continuo

# Backend
yarn test          # Tests unitarios
yarn test:e2e      # Tests de integración
 
# Frontend
yarn test          # Tests

4. 📤 Pull Request

Cuando tu funcionalidad esté completa, crea un Pull Request.

Proceso de Pull Request

1. Push de tu rama:

git push origin feature/nombre-de-tu-rama

1. Crear PR en GitHub:
   • Ve al repositorio en GitHub
   • Click en “Compare & pull request”
   • Selecciona develop como rama base
   • Completa la descripción del PR

Template de Pull Request

A continuación se muestra un ejemplo de Pull Request. La idea es que sea descriptivo y claro para que el equipo pueda entender el cambio que se está haciendo.

## 📋 Descripción
 
Breve descripción de qué hace este PR y por qué es necesario.
 
## 🎯 Tipo de Cambio
 
- [ ] 🐛 Bug fix
- [ ] ✨ Nueva funcionalidad
- [ ] 💥 Breaking change
- [ ] 📚 Documentación
- [ ] 🔧 Refactoring
 
## 🧪 Testing
 
- [ ] Tests unitarios agregados/actualizados
- [ ] Tests de integración agregados/actualizados
- [ ] Tested manualmente
 
## 📸 Screenshots/Videos
 
(Si aplica, agregar capturas de pantalla o videos)
 
## 🔗 Enlaces Relacionados
 
- Link a la tarea en Notion
- Link a issues relacionados
- Link a documentación relevante
 
## ✅ Checklist
 
- [ ] El código sigue las convenciones del proyecto
- [ ] He realizado una auto-revisión de mi código
- [ ] He comentado mi código en áreas difíciles de entender
- [ ] He actualizado la documentación correspondiente
- [ ] Mis cambios no generan nuevas advertencias
- [ ] He agregado tests que prueban mi funcionalidad
- [ ] Tests nuevos y existentes pasan localmente

5. 👀 Code Review

Todo PR debe ser revisado por al menos un desarrollador del equipo. Puedes asignar el PR a un compañero para que lo revise a través de GitHub.

6. ✅ Merge y Deploy

Una vez aprobado el PR:

1. Merge a develop: El PR se fusiona automáticamente
2. Deploy automático: GitHub Actions despliega a staging
3. Testing en staging: Verificar que todo funciona
4. Merge a production: Esto se hace en las fechas de release por el encargado de releases

📝 Convención de Commits

Seguimos la Convención de Commits Convencionales  para mantener un historial limpio y automatizar releases.

Formato

<tipo>[scope opcional]: <descripción>

[cuerpo opcional]

[footer opcional]

Tipos de Commit

• feat: Nueva funcionalidad
• fix: Corrección de bug
• docs: Cambios en documentación
• style: Cambios de formato (espacios, comas, etc.)
• refactor: Refactorización de código
• test: Agregar o modificar tests
• chore: Tareas de mantenimiento

Ejemplos

# Nueva funcionalidad
git commit -m "feat(auth): add JWT token validation"
 
# Corrección de bug
git commit -m "fix(api): handle null values in user profile"
 
# Documentación
git commit -m "docs(readme): update installation instructions"
 
# Refactoring
git commit -m "refactor(database): optimize user queries"
 
# Tests
git commit -m "test(auth): add unit tests for login service"
 
# Breaking change
git commit -m "feat(api)!: change user endpoint structure
 
BREAKING CHANGE: user endpoint now returns different format"

🚀 CI/CD y Automatización

Pipeline Automático

Es un archivo YAML que define los pasos que se van a ejecutar cuando se haga un push a una rama.

Pasos del Pipeline

• Backend:

1. 🔍 Linting: ESLint revisa calidad de código
2. 📝 Type Check: TypeScript verifica tipos
3. 🧪 Tests: Jest ejecuta tests unitarios
4. 🐳 Build: Docker construye imagen
5. 📦 Push: Imagen se sube a Artifact Registry
6. 🚀 Deploy: Cloud Run despliega automáticamente

• Frontend:

1. 🔍 Linting: ESLint revisa calidad de código
2. 📝 Type Check: TypeScript verifica tipos
3. 🧪 Tests: Jest ejecuta tests unitarios

📚 Recursos Adicionales

Documentación Interna

• Stack Tecnológico - Herramientas y tecnologías
• Configuración - Setup del entorno de desarrollo
• Testing - Guías de testing

Recursos Externos

• Git Flow - Metodología de branching
• Conventional Commits - Convención de commits
• GitHub Flow - Flujo simplificado de GitHub

¿Tienes dudas sobre el flujo de trabajo? ¡Consulta el diccionario técnico o pregunta al equipo!