Plantilla de Gestión de Cambios

Visión General

Los cambios en producción son riesgosos. Una migración de base de datos, una actualización de configuración o un cambio de feature flag pueden desencadenar una interrupción, y el postmortem suele encontrar la misma causa raíz: nadie escribió qué podía salir mal ni cómo volver atrás. Esta plantilla documenta el flujo de revisión, aprobación y reversión para cualquier cambio que toque producción, para que las personas correctas vean el riesgo antes del despliegue y la ruta de reversión esté probada antes de necesitarla. Si también necesitas una checklist para el despliegue en sí, combínala con la plantilla de checklist de despliegue.

Cuándo Usar

Usa este recurso cuando:

• Introduces un cambio en infraestructura de producción, bases de datos o configuración
• Tu marco de cumplimiento (SOC 2, ISO 27001) requiere aprobación documentada de cambios
• Una interrupción reciente fue causada por un cambio no revisado o no probado
• Estás formalizando un proceso de aprobación que hoy vive en hilos de Slack

No la uses para trabajo rutinario y completamente reversible. Una plantilla de triaje de bugs encaja mejor con el trabajo diario de incidentes, y las correcciones pequeñas de texto o documentación no necesitan revisión de CAB.

Solución

# Solicitud de Cambio: `<Título>`

## 1. Resumen del Cambio

| Campo | Valor |
|-------|-------|
| ID de Cambio | `CHG-AAAA-NNNN` |
| Título | `descripción` |
| Solicitante | `@nombre` |
| Equipo | `equipo` |
| Entorno | `staging / producción` |
| Fecha / Hora Programada | `AAAA-MM-DD HH:MM UTC` |
| Duración (esperada) | `X minutos / horas` |
| Nivel de Riesgo | `Bajo / Medio / Alto / Crítico` |

## 2. Descripción del Cambio

**¿Qué está cambiando?**
[Describe el cambio técnico en un párrafo.]

**¿Por qué se necesita?**
[Enlace al ticket, incidente o justificación de negocio.]

**¿Cuáles son los resultados esperados?**
[Resultado medible: latencia reducida en X%, característica habilitada para Y% de usuarios.]

## 3. Análisis de Impacto

| Sistema / Servicio | Impacto | Método de Validación |
|--------------------|---------|----------------------|
| | | |

### Dependencias
- [ ] No hay servicios dependientes afectados
- [ ] Servicios dependientes notificados: `lista`
- [ ] Socios externos / clientes notificados: `lista`

### Evaluación de Riesgo

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|--------------|---------|------------|
| | | | |

## 4. Plan de Reversión

| Condición | Acción de Reversión | Tiempo para Completar | Responsable |
|-----------|--------------------|-----------------------|-------------|
| El cambio falla durante el despliegue | `git revert` / `terraform destroy -target` / rollback de config | 10 min | `@nombre` |
| Degradación de rendimiento > 20% | Rollback a imagen anterior / revertir migración | 15 min | `@nombre` |
| Inconsistencia de datos detectada | Restaurar desde snapshot pre-cambio | 30 min | `@nombre` |
| Modo de fallo desconocido | Avisar a guardia; ejecutar runbook de reversión de emergencia | 5 min | `@guardia` |

- [ ] La reversión se ha probado en staging
- [ ] El comando de reversión está documentado en el runbook
- [ ] Snapshot / copia de seguridad de base de datos tomada antes del cambio
- [ ] El kill switch de feature flag está listo (si aplica)

## 5. Aprobación

| Rol | Nombre | Aprobado | Fecha |
|-----|--------|----------|-------|
| Solicitante | | | |
| Revisor Técnico | | | |
| Product Owner (si afecta usuarios) | | | |
| Seguridad (si involucra datos / acceso) | | | |
| CAB / Manager (riesgo Alto+) | | | |

## 6. Registro de Ejecución

| Hora (UTC) | Paso | Resultado | Notas |
|------------|------|-----------|-------|
| | | | |

## 7. Revisión Post-Cambio

- [ ] Cambio completado según lo planeado
- [ ] El monitoreo no muestra anomalías durante 1 hora post-cambio
- [ ] Plan de reversión archivado / actualizado basado en lecciones
- [ ] Ticket cerrado con resumen de resultado

Explicación

La plantilla impone tres compuertas antes de cualquier cambio en producción: una descripción que justifica el cambio, un análisis de impacto que revela dependencias ocultas, y un plan de reversión que está listo antes de que comience el cambio. El nivel de riesgo decide quién aprueba: los cambios de bajo riesgo pueden necesitar solo revisión por pares, mientras que los de alto riesgo requieren un Change Advisory Board (CAB) y aprobación explícita de seguridad. El registro de ejecución crea una trazabilidad de auditoría que resulta invaluable durante postmortems y auditorías de cumplimiento.

Matriz de Evaluación de Riesgo de Cambios

=== Evaluación de Riesgo de Cambios ===

Criterios de Nivel de Riesgo:

CRÍTICO:
  - Cambios en autenticación o autorización
  - Cambios de esquema de base de datos que afectan datos de producción
  - Cambios de infraestructura de red (VPC, firewall, DNS)
  - Cambios durante períodos de congelación (Black Friday, lanzamiento)
  - Cambios que afectan > 50% del tráfico de usuarios
  Aprobación: CAB + Seguridad + Director de Ingeniería

ALTO:
  - Cambios en configuración de producción
  - Cambios de contrato de API que afectan consumidores externos
  - Cambios de escalado de infraestructura
  - Adición/eliminación de índices de base de datos
  - Cambios que afectan 10-50% del tráfico de usuarios
  Aprobación: CAB + Líder de Equipo

MEDIO:
  - Activación/desactivación de feature flags en producción
  - Adiciones no-rompedoras de API
  - Actualizaciones de parámetros de configuración
  - Actualizaciones de versión de dependencias
  Aprobación: Líder de Equipo + Revisión de Par

BAJO:
  - Cambios de CSS/estilos
  - Actualizaciones de texto/copy
  - Actualizaciones de documentación
  - Cambios en entornos no productivos
  Aprobación: Revisión de Par

Calendario de Cambios y Detección de Colisiones

=== Calendario de Cambios (Semana del 2026-07-08) ===

Lunes     2026-07-08
  10:00  [MEDIO]   Desplegar API v2.3.1 (team-a)       Estado: Aprobado
  14:00  [BAJO]    Actualizar sitio docs (team-b)       Estado: Aprobado

Martes    2026-07-09
  09:00  [ALTO]    Migración DB: agregar índice (dba)   Estado: Pendiente CAB
  15:00  [MEDIO]   Feature flag: checkout-v2 (team-c)   Estado: Aprobado

Miércoles 2026-07-10
  --     DÍA DE CONGELACIÓN (lanzamiento)              No se permiten cambios

Jueves    2026-07-11
  10:00  [CRÍTICO] Upgrade servicio auth (sec)         Estado: Pendiente CAB
  11:00  [MEDIO]   Desplegar frontend v3.1 (team-d)     Estado: Pendiente
  COLISIÓN DETECTADA: Upgrade auth + deploy frontend al mismo tiempo
  RESOLUCIÓN: Mover deploy frontend a 14:00

Viernes   2026-07-12
  09:00  [BAJO]    Limpiar buckets S3 no usados (platform)  Estado: Aprobado
  --     No cambios ALTO/CRÍTICO después de 12:00 (seguridad fin de semana)

Plantilla de Revisión Post-Cambio

=== Revisión Post-Cambio ===

ID de Cambio: CHG-2026-07-11-001
Título: Desplegar API v2.3.1
Nivel de Riesgo: MEDIO
Responsable del Cambio: alice@example.com
Revisor: bob@example.com

Resumen de Ejecución:
  Inicio planificado:  10:00 UTC
  Inicio real:         10:02 UTC
  Fin planificado:     10:30 UTC
  Fin real:            10:35 UTC
  Varianza:            +5 minutos

Resultado:
  [x] Cambio completado como estaba planificado
  [x] Todos los pasos de despliegue tuvieron éxito
  [x] Smoke tests pasaron
  [x] Monitoreo no muestra anomalías (1h post-cambio)
  [x] No fue necesario rollback
  [x] Ticket cerrado con resumen de resultado

Problemas Encontrados:
  - La migración tardó 3 min más de lo esperado por tamaño de tabla
  - Sin impacto al usuario

Lecciones Aprendidas:
  - Actualizar estimación de tiempo de migración para tablas > 10M filas
  - Considerar pre-calentar caché después de migración

Acciones de Seguimiento:
  - Actualizar runbook con nueva estimación (alice, para 2026-07-18)
  - Agregar paso de cache warming al script (platform, para 2026-07-25)

Ejemplo: Una Solicitud de Cambio Real

Una plantilla vacía solo te lleva hasta cierto punto. Así se ve la solicitud de cambio completada para un cambio real de base de datos de riesgo Alto:

# Solicitud de Cambio: Agregar índice compuesto en tabla orders

## 1. Resumen del Cambio

| Campo | Valor |
|-------|-------|
| ID de Cambio | `CHG-2026-0142` |
| Título | Agregar índice compuesto `orders(user_id, created_at)` |
| Solicitante | `@maria.chen` |
| Equipo | `platform` |
| Entorno | `producción` |
| Fecha / Hora Programada | `2026-10-22 09:00 UTC` |
| Duración (esperada) | `20 minutos` |
| Nivel de Riesgo | `Alto` |

## 2. Descripción del Cambio

**¿Qué está cambiando?**
Agregar un índice compuesto en `orders(user_id, created_at)` para corregir el
p95 de 1.8s del endpoint de historial de pedidos. La migración ejecuta
`CREATE INDEX CONCURRENTLY` para que la tabla siga aceptando escrituras.

**¿Por qué se necesita?**
INC-3391 — las consultas de historial de pedidos expiran en cuentas con
> 2M de pedidos.

**¿Cuáles son los resultados esperados?**
La latencia p95 de `/orders/history` baja de 1.8s a menos de 300ms.
Verificado en staging con un dataset de tamaño productivo.

## 3. Análisis de Impacto

| Sistema / Servicio | Impacto | Método de Validación |
|--------------------|---------|----------------------|
| orders Postgres (primario) | Construcción de índice en tabla de 8GB, ~15 min | `pg_stat_progress_create_index` |
| API de historial de pedidos | Solo lectura; sin cambio de código | Smoke test + panel de latencia en Grafana |
| Réplica de reporting | Posible lag de replicación durante la construcción | Métrica de lag de `pg_stat_replication` |

### Dependencias
- [x] No hay servicios dependientes afectados
- [x] Servicios dependientes notificados: `#team-data` (consumidores de la réplica)
- [x] Socios externos / clientes notificados: n/a — no se espera downtime

### Evaluación de Riesgo

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|--------------|---------|------------|
| La construcción del índice bloquea escrituras | Baja | Alto | `CONCURRENTLY` evita el lock; probado en staging |
| Lag de replicación rompe dashboards | Media | Medio | Ejecutar en ventana de bajo tráfico 09:00 UTC; vigilar lag |
| Espacio en disco agotado | Baja | Medio | 40GB libres; el índice necesita ~6GB |

## 4. Plan de Reversión

| Condición | Acción de Reversión | Tiempo para Completar | Responsable |
|-----------|--------------------|-----------------------|-------------|
| Contención de locks bloquea escrituras > 60s | `pg_cancel_backend` sobre la construcción, reintentar fuera de pico | 2 min | `@maria.chen` |
| Lag de replicación > 5 min | Pausar construcción; reanudar cuando baje el lag | 10 min | `@maria.chen` |
| El plan de consultas empeora otras queries | `DROP INDEX CONCURRENTLY orders_user_created_idx` | 5 min | `@dba-guardia` |

- [x] Reversión probada en staging (el índice se eliminó sin problemas)
- [x] Comando de reversión documentado en `runbooks/postgres-index-ops.md`
- [x] Snapshot de esquema tomado el 2026-10-21
- [x] Kill switch de feature flag: n/a — no interviene ningún flag

## 5. Aprobación

| Rol | Nombre | Aprobado | Fecha |
|-----|--------|----------|-------|
| Solicitante | maria.chen | sí | 2026-10-20 |
| Revisor Técnico | j.okafor | sí | 2026-10-20 |
| CAB / Manager (riesgo Alto+) | s.ramirez | sí | 2026-10-21 |

## 6. Registro de Ejecución

| Hora (UTC) | Paso | Resultado | Notas |
|------------|------|-----------|-------|
| 09:02 | Migración iniciada | OK | `CREATE INDEX CONCURRENTLY` en ejecución |
| 09:17 | Construcción de índice completa | OK | 15 min; lag de replicación máximo 90s |
| 09:20 | Smoke tests | OK | p95 ahora 240ms |

## 7. Revisión Post-Cambio

- [x] Cambio completado según lo planeado
- [x] Monitoreo limpio durante 1 hora post-cambio
- [x] Seguimiento registrado: construir índices en tablas de 8GB toma ~15 min, no 10

Variantes

Contexto	Compuerta de Aprobación	Enfoque
Startup / equipo pequeño	Revisión por pares + líder de equipo	Velocidad; documentación ligera
Empresa / regulado	CAB + seguridad + cumplimiento	Trazabilidad completa; aprobación formal
Infraestructura (Terraform)	Revisión de IaC + diff del plan	Verificar que no haya cambios destructivos
Migración de base de datos	Revisión de DBA + script de reversión	La integridad de datos es la prioridad
Despliegue gradual de feature flag	Producto + ingeniería	Exposición gradual; reversión instantánea vía flag
Cambio de emergencia	Aprobación post-hoc dentro de 24 horas	Arreglar primero, documentar después—pero documentar

Cómo Adoptar Esta Plantilla

Implantar un proceso de cambios pesado de golpe suele fallar: los equipos se saltan cualquier cosa que los frene. Adóptala por nivel de riesgo:

• Semanas 1-2: usa solo las secciones 1-4 (resumen, descripción, impacto, reversión) y exige un revisor par para todo lo que supere riesgo Bajo. Olvida el CAB por ahora.
• Semanas 3-4: añade el calendario de cambios y la tabla de aprobación. Empieza a clasificar cambios con la matriz de riesgo para que el equipo calibre qué significa “Alto” de verdad.
• Mes 2: introduce revisión de CAB solo para cambios Alto y Crítico, y empieza a medir las métricas del FAQ (tasa de incidentes, tasa de rollback). Publica las ventanas de congelación del próximo trimestre.
• Continuo: revisa las revisiones post-cambio del mes anterior en la reunión de operaciones. Retira los campos que nadie rellena: una plantilla que cuesta 30 minutos completar termina ignorada.

La trampa a evitar es hacer que cada cambio siga la ruta más pesada. Si una corrección CSS de riesgo Bajo exige el mismo papeleo que una migración de esquema, los ingenieros clasificarán todo como Bajo y el proceso pierde sentido.

Lo que funciona

1. Clasifica el riesgo objetivamente; si el cambio toca facturación, autenticación o datos, es al menos Medio
2. Nunca apruebes tu propio cambio; exige al menos un revisor independiente
3. Prueba la reversión en staging, no solo el cambio hacia adelante
4. Programa los cambios de alto riesgo en ventanas de bajo tráfico con todo el equipo disponible
5. Mantén un calendario de cambios visible para todos los equipos: dos cambios riesgosos a la vez es como se encadenan los incidentes

Errores Comunes

1. Tratar cambios “simples” como de bajo riesgo sin análisis de impacto
2. No notificar a equipos downstream que dependen del servicio cambiado
3. Omitir la prueba de reversión porque “probablemente funcionará”
4. Aprobar cambios por DM de Slack en lugar de un registro documentado
5. No revisar el cambio después de la ejecución: las lecciones se pierden si no cierras el ciclo

Troubleshooting

• Las reuniones del CAB se convierten en el cuello de botella: agrupa las revisiones Alto y Crítico en una sola sesión semanal y aprueba los cambios Medio de forma asíncrona en el ticket. Si cada cambio espera una reunión, la gente empieza a etiquetar su trabajo como emergencia.
• Los cambios salen sin reversión probada: bloquea la aprobación hasta que la sección de reversión esté completa, y verifica trimestralmente que una reversión documentada se ejecutó de verdad en staging. Un plan de reversión que nadie probó es decoración.
• Las colisiones aparecen durante el incidente, no antes: mantén un único calendario compartido con avisos automáticos de conflicto para dos cambios Alto+ en la misma ventana o cualquier cambio durante una congelación. Revísalo en la reunión semanal de operaciones, no de forma ad hoc.
• “Emergencia” se convierte en la vía por defecto: mide mensualmente el ratio de cambios de emergencia frente a planificados. Si se mantiene por encima del ~10%, el proceso de planificación es demasiado lento o los equipos lo están esquivando: arregla el proceso, no la etiqueta.
• Las aprobaciones ocurren en el chat y no dejan rastro: exige la tabla de aprobación dentro del propio ticket de cambio. Un pulgar hacia arriba en Slack no es auditable; un nombre y una fecha en la solicitud sí lo son.

Notas de Producción

• Programa los cambios Alto y Crítico en ventanas de bajo tráfico con el de guardia y el equipo propietario conectados; nunca un viernes por la tarde ni justo antes de una congelación.
• Vigila las señales doradas — tasa de errores, latencia p95/p99, saturación — durante al menos una hora post-cambio antes de cerrar el ticket.
• Ensaya la reversión una vez por trimestre: elige un cambio en staging, ejecuta su reversión documentada y actualiza el runbook con lo que falle.
• Anuncia inicio y fin en el canal compartido para que los equipos downstream correlacionen anomalías con la ventana de cambio en lugar de adivinar.

Puntos Clave

• El verdadero trabajo de la plantilla es el plan de reversión — todo lo demás existe para que nunca lo necesites a ciegas.
• El nivel de riesgo marca la ceremonia: Bajo recibe revisión por pares, Crítico recibe al CAB. Las aprobaciones iguales para todo enseñan a la gente a esquivarlas.
• Rellénala antes del cambio, no durante el incidente — una solicitud escrita a posteriori es un postmortem, no un control.
• Cierra el ciclo en la revisión post-cambio; las lecciones alimentan la evaluación de riesgo de la siguiente solicitud.

Errores Comunes en Producción

• Dejar campos requeridos vacíos o usar respuestas vagas de una palabra.
• Rellenar el documento una vez y no actualizarlo nunca cuando cambia el alcance o las decisiones.
• Guardar el documento donde el equipo no lo busca durante incidentes o revisiones.
• No asignar un responsable, fecha límite o cadencia de revisión.
• Copiar texto base sin eliminar secciones que no aplican.
• Saltarse el control de versiones, lo que hace imposible la reversión y la rendición de cuentas.
• No vincular el documento con decisiones relacionadas o acciones de seguimiento.
• Evitar las revisiones trimestrales que retirarían secciones obsoletas o sin uso.

Lectura Adicional

• Atlassian — guía de gestión de cambios ITIL — cómo una organización madura estructura el change enablement
• GitHub Docs — Acerca de las ramas protegidas — aplica reglas de aprobación por riesgo en el propio PR
• Documentación de Argo CD — seguimiento de despliegues GitOps para el flujo PR-como-solicitud-de-cambio
• Repositorio complementario — la plantilla de solicitud de cambio, la matriz de riesgo, la revisión post-cambio y un ejemplo completo como archivos descargables