description: Ramas, entornos y versiones en SCAFFOLD 0.1: cómo enlazar elementos de trabajo con cambios, promover un mismo artefacto entre entornos y publicar versiones trazables.¶
Ramas, entornos y versiones¶
Esta página explica cómo un proyecto que declara SCAFFOLD 0.1 lleva el trabajo desde un elemento planificado hasta una versión desplegada, y cómo vuelve de la versión al elemento. Es una explicación: la norma está en los requisitos y esta página no añade obligaciones. Los nombres de ramas, herramientas y entornos son ejemplos ficticios.
En breve¶
- Cada rama y cada solicitud de integración citan un elemento de trabajo o un lote (R-025).
- La rama principal está protegida; las ramas de trabajo son de vida corta y pertenecen a un solo lote (R-026).
- Cada entorno tiene propósito, valor máximo de datos admitido, origen de secretos y quién despliega (R-027).
- Se promueve el mismo artefacto, identificado por su huella; la configuración se inyecta aparte (R-028).
- Una versión tiene esquema declarado, etiqueta inmutable y notas obtenidas de sus elementos (R-029).
Estado: SCAFFOLD 0.1 es una edición aceptada (nivel de decisión humana registrada). Ninguna de estas prácticas se presenta aquí como probada por mediciones propias; lo que se diga sobre ahorro, estabilidad o seguridad exige medición (R-032).
Del elemento a la versión, y de vuelta¶
El ciclo tiene cinco eslabones. Cada uno guarda el identificador del anterior, de modo que una consulta pueda recorrer la cadena en cualquier sentido.
| Eslabón | Qué guarda | Cómo se enlaza |
|---|---|---|
| Elemento de trabajo | Identificador estable, por ejemplo TIE-12 |
Lista de lotes, ramas, cambios y versión que lo implementan |
| Rama | Nombre con el identificador | función/TIE-12-exportar-csv |
| Cambio confirmado | Mensaje con el identificador y la atribución en un campo legible por máquina | Trailers al final del mensaje |
| Solicitud de integración | Elemento o lote, rama, responsable, asistentes, comprobaciones y revisor | Texto de la solicitud |
| Versión | Etiqueta inmutable y nota de versión | Lista de elementos incluidos |
Con esos enlaces, el responsable técnico puede responder dos preguntas: «¿qué elementos incluye la versión 1.4.0?» y «¿qué cambios implementan TIE-12?». La evidencia esperada de R-025 es una consulta que liste elementos por versión; esta página no prescribe qué herramienta la ejecuta.
Convención de nombres de rama¶
Un proyecto ficticio, la tienda en línea de Ana, declara este patrón:
<tipo>/<identificador>-<resumen-corto>
función/TIE-12-exportar-csv
corrección/TIE-31-redondeo-de-totales
El tipo coincide con los tipos de lote de R-009. El
identificador nunca se reutiliza (R-021). Si el servicio de
alojamiento de código o el sistema de archivos del equipo no admite acentos o diagonales, el
proyecto declara una variante (funcion-TIE-12-exportar-csv); lo importante es que la convención
esté escrita y que una consulta pueda extraer el identificador.
Atribución en el mensaje del cambio¶
R-003 pide poder atribuir cada cambio a una persona responsable
y, si intervino, al asistente que lo produjo. R-025 pide que esa atribución esté en un campo
legible por máquina. Una opción es usar trailers de git: líneas clave: valor al final del
mensaje, tras una línea en blanco, que la herramienta
git-interpret-trailers (consultado el
14-oct-2026) puede leer y añadir.
Exportar pedidos a CSV con separador configurable
Refs: TIE-12
Lote: L-2026-014
Co-authored-by: asistente-de-codigo <asistente-de-codigo@ejemplo.invalid>
Responsable: Ana
Co-authored-by: es una convención difundida; no se afirma que todo servicio de alojamiento la
reconozca ni que la muestre igual. Las claves Refs, Lote y Responsable son nombres de este
ejemplo; el proyecto elige los suyos y los declara. Riesgo residual (R-003): la atribución
declarada puede ser falsa o incompleta; el trailer registra una declaración, no la verifica.
Modelo de ramas¶
R-026 pide que el repositorio declare su modelo: rama principal, tipos de rama, quién integra y con qué comprobaciones. El modelo del ejemplo:
| Elemento | Declaración del ejemplo |
|---|---|
| Rama principal | principal, protegida: sólo recibe cambios por solicitud de integración revisada por una persona |
| Ramas de trabajo | función/…, corrección/…; vida máxima declarada de 3 días hábiles (cifra ficticia) |
| Una rama por lote | La rama pertenece a un solo lote; un lote con varias ramas lo declara |
| Quién integra | El responsable técnico o la persona que él designe. Un asistente no escribe en la rama principal salvo mediante una solicitud de integración revisada por una persona; integrar lo catalogado como crítico lo decide una persona |
| Comprobaciones | Las del repositorio, antes de integrar (R-010) |
Dos asistentes no escriben a la vez en la misma rama, salvo un turno declarado. Esto se relaciona con las zonas de escritura (R-001), que reparten rutas, y con las ramas, que reparten líneas de historia. Son dos mapas distintos: una rama puede tocar varias zonas (entonces el lote nombra a sus dueños, R-002) y una zona puede recibir cambios de varias ramas. Un patrón posible es dar a cada asistente su propio espacio de trabajo separado (una copia de trabajo o árbol de trabajo distinto del mismo repositorio), de modo que su rama no se mezcle con la de otro. Es una opción de organización; no la exige el requisito ni garantiza por sí sola que no haya colisiones.
Fuentes y diferencias¶
Trunk Based Development, «Short-Lived Feature Branches» (consultado el 14-oct-2026) describe ramas de función que duran «un par de días» y se integran en la rama común al cerrarse. R-026 comparte la preferencia por ramas breves (como DEBERÍA, con vida máxima declarada), pero no adopta esa técnica completa: añade protección de la rama principal, revisión humana y la regla de un solo escritor por rama. Que SCAFFOLD y esa fuente coincidan en un punto no las hace equivalentes.
Comprobaciones antes de integrar¶
Antes de integrar un lote se ejecutan las comprobaciones que el repositorio declare (R-010). Ejemplos ficticios: pruebas automáticas, análisis de estilo, comprobación de que contrato y código declaran la misma versión (R-006) y el inventario de exclusión de la capa de ingeniería (véase más abajo). La definición de terminado incluye estas comprobaciones (R-023). Un asistente no integra ni despliega por sí mismo lo que el catálogo de efectos críticos del proyecto incluya; lo demás sigue las comprobaciones declaradas. Riesgo residual: las comprobaciones y la revisión humana pueden omitir errores.
Entornos¶
Un entorno es un lugar donde se ejecuta el software. R-027 pide declarar, por cada uno: propósito, clasificación máxima de datos, origen de sus secretos, quién puede desplegar y comprobaciones de entrada. La clasificación usa una escala con nombre y valores definidos que el proyecto declara (MILPA-R-003). Escala ficticia del ejemplo: pública, interna, confidencial, crítica (de menor a mayor). Los datos sintéticos o anonimizados son una práctica para los entornos de prueba, no niveles de la escala. Tabla de ejemplo (ficticia):
| Entorno | Propósito | Valor máximo admitido | Secretos | Quién despliega |
|---|---|---|---|---|
| Local | Desarrollar y probar en la máquina de quien trabaja | Pública (datos sintéticos) | Propios del entorno, sin valor real | Quien trabaja, incluido su asistente |
| Integración | Ejecutar comprobaciones automáticas de cada rama | Pública (datos sintéticos) | Propios, guardados en el almacén de secretos del proyecto | El proceso de integración continua |
| Preproducción | Probar la versión candidata | Interna (datos anonimizados) | Propios, distintos de producción | Responsable de entrega |
| Producción | Servir a las personas usuarias | Crítica | Propios, sólo accesibles al proceso de despliegue | Responsable de entrega, con confirmación humana informada |
Reglas que la tabla ilustra (R-027): un entorno que use secretos los tiene propios, no compartidos con otro entorno; un entorno que no es de producción no recibe datos reales por encima de su valor declarado salvo excepción registrada; desplegar en producción figura en el catálogo de efectos críticos. Ese tratamiento viene de ASILO-R-005 (revisión humana antes de efectos críticos) y los secretos de ASILO-R-006. Riesgo residual: una copia de datos puede salir de su entorno por una vía no declarada.
Promover el mismo artefacto¶
R-028 separa tres cosas: el artefacto (lo construido), su configuración (distinta por entorno) y su despliegue. Lo que llega a producción es el mismo artefacto que pasó las comprobaciones, identificado por su huella criptográfica, sin reconstruirlo por entorno. La configuración se inyecta aparte al desplegar.
- Se construye el artefacto una vez y se calcula su huella.
- Las comprobaciones se ejecutan sobre ese artefacto, no sobre una reconstrucción.
- Cada promoción registra la huella; si no coincide con la comprobada, no se promueve.
- Antes de desplegar en producción existe un plan de reversión.
- Al desplegar se registra versión, huella, entorno, persona que autorizó y resultado.
Una reversión (volver a un artefacto anterior) no deshace por sí sola cambios de datos; es el riesgo residual de R-028 y el plan lo menciona cuando aplica. El formato del registro está en las plantillas.
La fuente The Twelve-Factor App, «V. Build, release, run» (consultado el 14-oct-2026) separa construcción, publicación (construcción más configuración) y ejecución, y desaconseja cambiar el código en ejecución. R-028 coincide en esa separación, pero agrega la huella como identidad, el plan de reversión y el registro de despliegue, que esa fuente no prescribe en esos términos. SLSA (SLSA 1.2, la versión que la especificación presenta primero el 14-oct-2026; consultada ese día, sin citar secciones) es un marco de integridad de la cadena de suministro y de procedencia de construcciones. SCAFFOLD no lo exige; un proyecto puede adoptarlo como perfil propio, y esa adopción no se deduce de seguir R-028.
El despliegue a producción como efecto crítico¶
El proyecto incluye «desplegar en producción» en su catálogo de efectos críticos, que recoge la carta (R-019); R-027 exige que figure ahí. Un asistente puede preparar el artefacto, proponer el plan de reversión y rellenar el registro; la confirmación informada para desplegar la da una persona, normalmente el responsable de entrega, y el registro anota a la persona que autorizó (R-028). Pedir confirmación sólo para lo catalogado es deliberado: ASILO-R-005 advierte que pedirla para todo lleva a aprobar sin leer, y R-010 la retoma.
Versiones¶
R-029 pide cuatro cosas, que el ejemplo declara así:
- Esquema declarado. La tienda de Ana usa tres números (mayor.menor.parche) y declara qué cambio sube cada uno: incompatible con lo publicado, función añadida, corrección.
- Etiqueta inmutable. Cada versión publicada tiene una etiqueta en el control de versiones y esa etiqueta no se mueve a otro cambio; si hay un error, se publica una versión nueva.
- Notas desde los elementos. La nota de versión se obtiene de los elementos de trabajo incluidos, no se reescribe de memoria (véase la plantilla).
- Cambios incompatibles señalados, y la persona que autorizó la versión.
Fuentes, con sus diferencias:
| Fuente | Qué aporta | Diferencia con R-029 |
|---|---|---|
| Semantic Versioning 2.0.0 (consultado el 14-oct-2026) | Un esquema de versiones y reglas para subir mayor, menor y parche | Es un esquema posible; R-029 sólo pide declarar uno, sea éste u otro |
| Conventional Commits 1.0.0 (consultado el 14-oct-2026) | Convención de mensajes de cambio con tipos que se corresponden con subidas de versión | R-025 pide un campo legible por máquina para la atribución; la convención de mensajes es un formato opcional distinto |
| Keep a Changelog 1.1.0 (1.1.0, versión que declara su página; consultado el 14-oct-2026) | Formato de archivo de cambios escrito para personas, por versión | R-029 pide que las notas se obtengan de los elementos de trabajo; ese formato puede servir de presentación, no de fuente |
Ninguna de las tres es obligatoria. Elegir una no demuestra conformidad con SCAFFOLD.
Vía de urgencia¶
Cuando una corrección no puede esperar las comprobaciones normales, la vía de urgencia se define de antemano, deja registro al usarse y termina en una revisión posterior (R-013). No exonera la revisión humana de ASILO-R-005, que es previa o, si se aplica la excepción de emergencia definida de antemano, posterior. El artefacto desplegado es el mismo que pasó las comprobaciones; si es distinto, se registra su huella y lo omitido (R-028) y el despliegue entra en la revisión posterior. Ejemplo ficticio: el responsable de entrega autoriza el despliegue de una corrección de TIE-40 con pruebas reducidas; una persona confirma antes el efecto crítico (o, si rige la excepción de emergencia, lo revisa después); el mismo día se abre un elemento para la revisión posterior y se registra la huella del artefacto y qué comprobaciones se omitieron. Riesgo residual: la revisión posterior no deshace todos los efectos.
Exclusión de la capa de ingeniería¶
Zonas, notas de traspaso, lotes y configuración de los asistentes de programación pertenecen a la construcción, no al producto. R-011 pide que queden fuera del artefacto que se despliega, comprobado sobre el artefacto ya construido. Ejemplo: tras construir, una comprobación recorre el contenido del artefacto y falla si encuentra la carpeta de notas de traspaso. Riesgo residual: el inventario puede omitir archivos o datos incrustados. Esta comprobación forma parte de la entrada a integración o de la promoción, según decida el proyecto.
Entregar un cambio regional¶
Ejemplo ficticio: un elemento de trabajo actualiza un paquete regional usado por una biblioteca. Sus criterios de aceptación pueden incluir referencia y huella correctas, compatibilidad técnica y casos de ámbito no cubierto, contexto cambiado y revisión pendiente. El proyecto declara cuáles son sus comprobaciones; se registran resultados reales antes de integrar (R-010, R-023).
La entrega identifica el artefacto, el contenido regional y la configuración seleccionada. Según R-028, el artefacto promovido conserva su huella y la configuración por entorno se inyecta aparte. Si el contenido regional es una dependencia necesaria en ejecución, forma parte del producto según su diseño; la exclusión de R-011 corresponde a la configuración exclusiva de ingeniería, como zonas, notas y configuración de asistentes, no a todo contenido llamado «contexto».
Para actualizar o revertir, conserva versiones y referencias pertinentes, criterios de compatibilidad, resultados y la decisión de entrega. Revertir un paquete no revierte por sí solo efectos sobre datos ni hace vigente una fuente jurídica anterior. El plan explica esos límites y el tratamiento de cambios incompatibles. Las notas de versión se relacionan con el trabajo según R-029; un incidente o reversión conserva la revisión posterior de R-032. La guía común distingue esos registros de la aplicabilidad jurídica y la autorización.
Medir la entrega¶
R-032 pide declarar qué indicadores de entrega se miden, cómo y con qué periodicidad. No fija cuáles. Una opción son las cinco métricas de DORA (consultado el 14-oct-2026): tiempo de entrega de un cambio (change lead time), frecuencia de despliegue (deployment frequency), tiempo de recuperación tras un despliegue fallido (failed deployment recovery time), tasa de cambios fallidos (change fail rate) y tasa de retrabajo por despliegue (deployment rework rate). Elegirlas no prueba mejora: R-032 exige medición antes y después para afirmar una mejora, y advierte que un indicador puede mejorarse sin que mejore el resultado. Esta página no ofrece cifras de referencia.
Hypothesis y qué las promovería¶
| Afirmación | Estado | Verificación que la promovería |
|---|---|---|
| Un patrón de espacios de trabajo separados por asistente reduce colisiones entre ramas | Hypothesis (no medido) | Comparar colisiones de integración antes y después en un proyecto real, con datos fechados |
| El nombre de rama basta para extraer el identificador en las herramientas del equipo | Hypothesis (depende de la herramienta) | Ejecutar la consulta de R-025 sobre un repositorio de prueba |
Los servicios de alojamiento interpretan Co-authored-by: de forma uniforme |
No afirmado | Revisar la documentación vigente de cada servicio concreto |
Siguiente lectura: cuadrillas, plantillas y la página de SCAFFOLD.