Solicitudes de cambio de arquitectura: Pull Requests para su modelo C4
El mes pasado, un ingeniero de un equipo que asesoro renombro un servicio central en su diagrama de arquitectura. Sin discusion. Sin revision. El cambio estaba en produccion al instante, y tres equipos pasaron el siguiente standup confundidos sobre si el servicio real habia sido renombrado o solo el diagrama. No lo habia sido. Alguien simplemente penso que la etiqueta no era clara y la "corrigio".
Ese incidente cristalizo algo en lo que veniamos pensando desde hace tiempo. El codigo tiene pull requests. La infraestructura tiene plan/apply. Los esquemas de base de datos tienen migraciones. Pero los diagramas de arquitectura? Cualquier persona con acceso de edicion puede cambiar cualquier cosa, en cualquier momento, y el resto del equipo se entera... eventualmente.
Hoy eso cambia. Las Solicitudes de Cambio de Arquitectura traen el flujo de trabajo de pull request a su modelo C4.
Como funciona
El concepto es deliberadamente familiar. Si alguna vez ha abierto un pull request en GitHub, ya sabe como funciona esto.
Empiece creando una solicitud de cambio. Dele un titulo, describa lo que propone y por que. Luego agregue sus cambios: crear nuevos sistemas, actualizar contenedores existentes, eliminar componentes sin uso, modificar relaciones. Cada cambio es una operacion discreta: crear, actualizar o eliminar sobre un elemento C4 especifico.
La solicitud de cambio comienza como borrador. Puede seguir agregando y refinando cambios hasta que este listo. Cuando la propuesta esta completa, la abre para revision.
Sus companeros ven la solicitud abierta en la lista de solicitudes de cambio del proyecto. Pueden examinar cada cambio propuesto, ver exactamente que se esta creando, modificando o eliminando. Dejan revisiones: aprobar, solicitar cambios o comentar. Una vez que se alcanza el numero requerido de aprobaciones, la solicitud puede ser fusionada, aplicando todos los cambios al modelo C4 en vivo en una sola operacion atomica.
Vista previa visual
Algo que no queriamos era una vista de diferencias que se lea como un blob JSON. La arquitectura es visual, y revisar cambios de arquitectura deberia serlo tambien.
Cada solicitud de cambio incluye una vista previa en vivo del diagrama. La vista previa renderiza el modelo C4 actual con todos los cambios propuestos superpuestos. Los nuevos elementos aparecen con un resaltado verde. Los elementos modificados reciben un anillo ambar. Los elementos eliminados muestran un indicador rojo. Puede navegar por los niveles C4 — sistema, contenedor, componente, codigo — y ver el impacto completo de la propuesta en cada profundidad.
Es el mismo lienzo interactivo de React Flow que usa para el diagrama en vivo, con el mismo drill-down, zoom y panoramica. La unica diferencia son los datos: es una proyeccion calculada de como se vera la arquitectura despues de la fusion.
El proceso de revision
Las revisiones siguen un modelo directo. Un revisor puede:
- Aprobar — "Se ve bien, fusionar cuando este listo."
- Solicitar cambios — "Tengo inquietudes, discutamos antes de que entre."
- Comentar — "Sin objeciones, pero aqui hay algo de contexto."
Cada revision incluye un campo de texto libre para comentarios detallados. La solicitud de cambio rastrea su conteo de aprobaciones contra el umbral requerido del proyecto. Por defecto, se necesita una aprobacion, pero puede configurar esto por proyecto: cero aprobaciones para equipos pequenos que quieren un seguimiento ligero, dos o tres para organizaciones mas grandes que necesitan una aprobacion formal.
Modo solo solicitudes
Para equipos que quieren ir mas lejos, hemos agregado un Modo solo solicitudes en la configuracion del proyecto. Cuando esta habilitado, las ediciones directas al modelo C4 estan bloqueadas. La unica forma de modificar la arquitectura es a traves de una solicitud de cambio.
Esto no significa que el diagrama se vuelva de solo lectura. Puede seguir navegando, explorando, vinculando ADR y documentacion a elementos, agregando comentarios. Simplemente no puede mover, renombrar, crear o eliminar elementos sin pasar por el flujo de trabajo de solicitud de cambio.
Construimos esto para organizaciones donde la gobernanza de la arquitectura importa: industrias reguladas, grandes equipos de ingenieria, equipos de plataforma que gestionan infraestructura compartida. La arquitectura se convierte en un artefacto controlado, con cada cambio rastreable y revisado.
Seguimiento de actividad
Cada evento del ciclo de vida de una solicitud de cambio aparece en la pestana de Actividad del proyecto. Cuando una solicitud se abre, cierra, reabre o fusiona, se registra una entrada de historial con el autor, la marca de tiempo y el titulo de la solicitud. Esto le da una linea de tiempo de como evoluciono la arquitectura, no solo como se ve hoy, sino la secuencia de propuestas y decisiones que la moldearon.
Combinado con ADR y enlaces de documentacion, obtiene una narrativa completa: que cambio (la solicitud de cambio), por que cambio (el ADR) y como encaja en el contexto mas amplio (la documentacion).
Construyendo cambios
El constructor de cambios le permite armar propuestas elemento por elemento. Para cada cambio, especifica:
- Operacion: crear, actualizar o eliminar
- Tipo de elemento: sistema, contenedor, componente, elemento de codigo, relacion u overlay
- Datos del elemento: la especificacion completa del elemento — nombre, descripcion, tecnologia, tipo y todos los campos que completaria al crearlo directamente
Para las actualizaciones, el sistema captura tanto el estado actual como el estado propuesto, para que los revisores vean exactamente que esta cambiando. Para las eliminaciones, los datos del elemento existente se conservan en la solicitud como referencia.
Puede mezclar operaciones libremente. Una sola solicitud de cambio puede crear dos nuevos contenedores, actualizar una relacion y eliminar un componente obsoleto. Al fusionar, todos los cambios se aplican juntos.
Que significa esto para los equipos
Las solicitudes de cambio de arquitectura no son para agregar burocracia. Son para hacer que la evolucion arquitectonica sea intencional.
En un codebase, el pull request no es solo una barrera, es una herramienta de comunicacion. Dice "esto es lo que propongo, esto es por que, que opinan?" Crea un momento natural para compartir conocimiento, para detectar errores temprano, para construir un entendimiento compartido.
La arquitectura merece el mismo tratamiento. Cuando alguien propone agregar un nuevo servicio, esa es una conversacion que vale la pena tener antes de que aparezca en el diagrama. Cuando alguien quiere reestructurar la jerarquia de componentes, el equipo deberia ver el panorama completo antes de que se convierta en la nueva realidad.
La solicitud de cambio es esa conversacion, hecha estructurada y rastreable.
Para empezar
Las Solicitudes de Cambio de Arquitectura estan disponibles ahora en todos los planes de equipo. Navegue a cualquier proyecto, y encontrara la seccion "Solicitudes" en la barra lateral. Cree su primera solicitud, agregue algunos cambios y abrala para revision.
Si quiere imponer el flujo de trabajo, habilite el Modo solo solicitudes en la configuracion de su proyecto. Configure el numero requerido de aprobaciones segun las necesidades de gobernanza de su equipo.
Su arquitectura es una decision de equipo. Ahora sus herramientas lo hacen explicito.
Quiere saber mas sobre arquitectura colaborativa? Lea sobre la Colaboracion en tiempo real en diagramas C4, o aprenda como los Architecture Decision Records complementan las solicitudes de cambio capturando el "por que" detras de cada evolucion arquitectonica.