Una decisión solo queda registrada
si alguien puede saber que sigue en pie.
La carpeta está llena. Veinte ADR, nueve especificaciones, cuatro de ellas sustituidas por una decisión registrada en otro sitio, y al menos una que describe un servicio que se eliminó el año pasado. Nada en la carpeta dice cuál es cuál.
Así que las preguntas que de verdad tiene un ingeniero nuevo (¿está aprobado?, ¿está construido?, ¿sigue siendo cierto?) se hacen en el chat, se responden de memoria y de forma distinta según quién esté conectado. Los documentos se escribieron precisamente para que eso dejara de pasar.
La solución habitual es un campo de estado en el front matter, un campo que alguien tiene que acordarse de cambiar. Es exacto el día en que se escribe y decorativo al cabo de un mes, porque nada lo conecta con el documento sobre el que está.
Un estado que no se da cuenta de que el documento cambió debajo de él es peor que no tener estado: es una afirmación caducada con una insignia.
Las partes que importan aquí
No toda la lista de funciones, sino las de las que depende este problema concreto.
Dos ejes, no uno
El estado de revisión y el de implementación avanzan por separado, porque una especificación que todos aprobaron y nadie construyó es una situación distinta de una a medio construir y discutida. Reducirlos a un único estado pierde la distinción que más importa.
La desviación se mide contra el contenido
Un estado recuerda la versión exacta sobre la que se fijó. Edita el documento y pasa a indicar validado · desviado, en lugar de mantener una insignia que ha dejado de ser cierta en silencio. Una marca de tiempo saltaría cada vez que un worker tocara una fila.
Ninguna fila hasta que alguien decide
Un documento sin clasificar no tiene estado y no muestra etiqueta. Una carpeta que nadie ha revisado se ve como lo que es, en lugar de un muro de borradores que sugiere un proceso que nunca ocurrió.
Rechazado es un estado real
«No construir esto» es una decisión que merece registrarse, y exige un motivo, escrito como nota en la misma transacción que el estado, para que el rechazo y su argumento no puedan separarse.
Las objeciones viven en el encabezado
Una nota se ancla a la sección que discute. Si ese encabezado se elimina, la nota falla de forma visible en lugar de trasladarse a un texto que dice otra cosa.
El tablero de todo un proyecto
Cada documento con estado, en columnas entre las que puedes arrastrar, filtrado por una URL que puedes pegar en un canal antes de una revisión de diseño.
Qué pasa de verdad
- 01Se fusiona un ADR y aparece, sin estadoEstá en el árbol en cuanto se lee la branch. Nadie lo ha clasificado, así que no lleva etiqueta, que es la representación honesta de un documento que nadie ha mirado todavía.
- 02Un revisor lo lee y discrepa de una secciónDeja una nota en ese encabezado en lugar de un comentario en una pull request ya cerrada. La nota está unida al texto, así que seguirá ahí dentro de seis meses cuando alguien pregunte por qué se hizo esto.
- 03El autor revisa y el revisor validaEl estado de revisión pasa a validado, sobre esta versión exacta del texto. El estado de implementación se queda donde está, porque aprobar no es construir.
- 04Un agente lee la especificación y empieza a trabajarEncuentra el documento con la búsqueda, lo lee e informa de que ha empezado, con pruebas guardadas como nota. Registra una afirmación, nunca una finalización.
- 05Alguien edita la especificación tres semanas despuésLa insignia pasa a validado · desviado en cuanto cambia el contenido. Nadie tiene que darse cuenta; el propio documento lo dice, y el agente puede pedir el diff entre la versión validada y el texto actual.
- 06Una persona cierra el ciclo, o noUn agente puede decir que un comentario está atendido. Solo una persona puede cerrarlo. Esa asimetría es toda la razón de ser de esta capa, y se aplica en una sola función con una prueba.
Qué no resuelve esto
Cada página de este sitio lleva una, por lo mismo: una página de caso de uso sin límites es un folleto.
- No escribirá el ADR
- Es un lector. Escribes en tu editor y haces commit, exactamente como ahora: no hay superficie de redacción y no la habrá.
- No modela las sustituciones
- «ADR-014 sustituye a ADR-009» es una relación entre documentos y no la seguimos. Un enlace y un estado rechazado es lo más parecido que tendrás.
- Una errata activa la desviación
- La identidad del contenido es todo el mecanismo, así que corregir una coma marca un documento validado como desviado. Se acepta a propósito: la alternativa es una regla que adivina qué cambios cuentan.