Versión 1.0.0-alpha.1 más reciente
Capítulo 2.28
Lanzamiento de su extensión
Cómo pasa un complemento o paquete de una compilación validada a las unidades que lo ejecutan, y cómo vuelve a retirarse. Versiones, revisión de lanzamiento, canales e instalaciones, firma, aprobaciones de cambios, el registro de identidad de entrega, migraciones, reversión y retirada de una versión.
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

Cold chain 0.4.0 fue la primera versión nuestra que pedía más que la anterior. Añadía el envío de correo y una dirección externa, para las alertas de contenedores refrigerados. La compilación estaba en verde, las pruebas pasaron en las tres ramas sintéticas, y aun así permaneció en el espacio de desarrollo dos días mientras dos personas leían lo que pedía y una tercera aprobaba la dirección. Así es como debe sentirse publicar una versión en Nexus: el código es la parte fácil, y las evidencias y las aprobaciones son la versión.
Este capítulo abarca todo lo que hay entre una compilación en verde y una versión que se ejecuta para todas las unidades, y las formas de dar marcha atrás. La ruta de promoción en sí, del espacio de desarrollo a staging, a una unidad piloto y a todas las unidades, se presenta en el capítulo 2.24, Crear un vertical personalizado de principio a fin, y no repetiré aquí sus controles. Una regla enmarca todo ello. El despliegue se realiza únicamente a través de los canales de versiones de la instalación. No hay una puerta lateral para una corrección urgente, y nadie edita a mano una imagen en ejecución.
Versiones
En una versión de un pack se mueven tres números de versión, y conviene mantenerlos separados mentalmente.
| Qué | Dónde se encuentra | Ejemplo | Regla |
|---|---|---|---|
| El plugin | version en nexus.manifest.json |
0.4.0 |
Versión semántica; se permite un sufijo de versión preliminar como -rc.1 |
| El pack | version en pack.json |
0.4.0 |
Cambia con las lentes, los términos y los clústeres del pack |
| El modelo de conocimiento | La versión propia del modelo | 1.3 a 1.4 |
Cambia solo mediante una solicitud de cambio del grafo |
Una compilación de desarrollo lleva un sufijo, 0.4.0-dev, hasta que llega a staging. Mantenga iguales las versiones del plugin y del pack cuando se publiquen juntos; así se ahorra una discusión en cada revisión de versión sobre a qué número pertenecen las evidencias.
Otras dos versiones se fijan en lugar de elegirse. La versión de plantilla del pack (domain-pack@1.6.0 para Cold chain) se fija cuando se crea el pack y solo cambia como un cambio revisado. El SDK (kit de desarrollo de software) se instala en una versión exacta, nunca en un rango, de modo que la misma compilación dé el mismo resultado el mes siguiente:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Las skills de Skills Engine también tienen versiones, y se comportan de forma distinta. Cada versión publicada es fija, y live, canary y shadow son etiquetas sobre las versiones. Volver atrás mueve una etiqueta, y las ejecuciones ya en curso terminan con la versión con la que empezaron.
Antes de solicitar la revisión: el manifiesto
La página Manifiesto y permisos compara lo que declara esta versión con la versión anterior: sus ámbitos, sus almacenes, sus direcciones salientes y su perfil de sandbox. Léala antes de pedir a nadie que la revise, porque le indica exactamente qué se pedirá aceptar a los revisores.
Una versión que pide más de lo que declaraba antes su manifiesto queda retenida donde está, con MANIFEST_SCOPE_WIDENED, hasta que dos revisores acepten el manifiesto ampliado. Una dirección externa también necesita la aprobación de quien sea responsable de las direcciones externas en el cliente; esa aprobación se concede por un plazo fijo, y la nuestra fue por 12 meses. Tiene dos formas de avanzar: eliminar las líneas o solicitar una revisión. La página ofrece ambos botones.
Cada línea de esa página se aplica en tiempo de ejecución, no solo se revisa. Cada llamada a una herramienta se comprueba frente a los ámbitos declarados, una dirección externa se bloquea salvo que figure en la lista, y el perfil de sandbox no permite ninguna otra red. Un plugin que intenta acceder a algo que no declaró es rechazado, y la única solución es una nueva versión que lo declare.
Revisión de lanzamiento
La página Revisión de versión reúne las evidencias de una versión en una sola tabla, para un revisor que no sea el autor.
| Evidencia | Lo que mostró para 0.4.0 |
|---|---|
| Pruebas | 66 de 66, en tres ramas sintéticas |
| Comprobaciones de calidad | La documentación y el código coinciden |
| Política | Cada lente solo restringe; campos personales desactivados por defecto |
| Firmas | Imagen y paquete firmados por el pipeline |
| Diferencia de ámbitos | Añade el envío de correo y una dirección externa, con su aprobación |
| Compatibilidad | La versión de la plataforma y la versión del pack base con las que se probó |
| Cambio del modelo | La ejecución de prueba de la solicitud de cambio del grafo: 1,284 vínculos renombrados, nada eliminado |
Debajo de la tabla se encuentran los comentarios sobre el cambio y la procedencia: qué pipeline lo compiló, a partir de qué cambio, el digest de la imagen y la plantilla. Los revisores aprueban con su passkey. Dos revisores que no sean el autor aprueban, y el pipeline mueve entonces la versión a staging. El autor nunca cuenta como revisor, y un intento se rechaza con NEEDS_SECOND_PERSON. Una solicitud de revisión caduca a los 3 días.
Responda a las preguntas de los revisores en los comentarios, no en una ventana de chat. Durante nuestra revisión, nuestra responsable de cumplimiento preguntó por qué el importe de la reclamación estaba clasificado como comercial, y el segundo revisor pidió el plan de reversión del cambio del modelo. Ambas respuestas forman ahora parte del registro de la versión, que es donde mirará el próximo revisor.
Aprobaciones de la política de cambios
La revisión de versión abarca la versión en su conjunto. El bloque changePolicy del manifiesto va más allá: indica qué clases de cambio en los elementos desplegables de su plugin necesitan aprobación, y de cuántas personas.
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Las tres clases son website (la aplicación web), bff (el backend for frontend) y migration (una migración de base de datos). Cada clase indicada en classes debe tener su propio recuento en approvals, de 1 a 10. Una clase que omita queda sin gobernar, y el esquema le obliga a escribirlo como una decisión en lugar de llegar a ello por omisión. Pedimos dos aprobaciones para las migraciones porque una migración es el único cambio difícil de revertir.
Las aprobaciones se cuentan en personas distintas, y quien propone nunca es una de ellas. Conviene conocer las reglas que lo sostienen, porque cada una tiene un rechazo:
- Una aprobación de la persona que propuso el cambio se rechaza con
TRUST_APPROVAL_SELF_APPROVAL. - Una persona que no puede realizar en absoluto un cambio de esa clase es rechazada con
CHANGE_CLASS_NOT_PERMITTED. - Cuando cualquier commit del cambio está firmado por la identidad de agente de la organización, el quórum es el mínimo habitual más uno, y el voto propio del agente no cuenta.
- Cada aprobación registra el diff y el head que vio. Si el cambio se modifica después de la última aprobación, su fusión se rechaza con
HASH_MISMATCH, y las aprobaciones deben recabarse de nuevo para el nuevo contenido.
Esa tercera regla importa si desarrolla con una herramienta de programación de IA (inteligencia artificial), como describe el capítulo 2.26, Desarrollar con herramientas de programación de IA. El trabajo escrito por un agente necesita una aprobación humana más que el trabajo escrito por una persona. Téngalo previsto.
Firma y verificación
Cada imagen y cada paquete se firman por el pipeline que los compiló, y una imagen firmada es uno de los controles de entrada a staging. Un espacio de desarrollo ejecuta solo imágenes firmadas desde el principio. En Enterprise, un administrador configura cada namespace para registrar las imágenes sin firmar o para rechazarlas, y pasa los namespaces al rechazo de uno en uno, de modo que producción acabe ejecutando solo imágenes que el pipeline compiló y firmó. La firma forma parte de la compilación, no es algo que se añade antes de una versión.
La regla que lo recorre todo es que una firma que falla es un rechazo, nunca una advertencia. Una comprobación que recibe SIG_INVALID se detiene. No recurre a la versión sin firmar ni continúa con una nota en un registro, porque una advertencia en un registro de compilación es un aprobado para todos los que no la leyeron.
La misma regla se aplica a todo lo que entregue en soportes físicos. Un paquete sellado para un cliente aislado de la red se verifica con su clave pública antes de desempaquetar nada, y el capítulo 2.25, Desarrollar para cada edición, muestra el comando.
Identidad de entrega
Un plugin se entrega a través de varios elementos que tienen cada uno un nombre: sus repositorios, una clave de firma, un namespace de despliegue, un prefijo de registro, un esquema de base de datos, un conjunto de dominios y una política de cambios. Cualquiera de ellos es un punto donde dos plugins podrían colisionar, o un plugin podría desviarse. La identidad de entrega es un registro firmado por plugin que los contiene todos, de modo que cada comprobación de la ruta de versión lee la misma respuesta y rechaza ante una discrepancia.
Usted aporta su parte a través del manifiesto y de nada más: schema, db, domains, changePolicy y la URL del repositorio. La plataforma completa el registro con el resto y lo firma. Nunca indica su propio namespace, prefijo de registro ni clave de firma. Estos se le asignan, y un manifiesto que intentara declararlos estaría haciendo una afirmación que las comprobaciones tendrían luego que descartar.
El registro firmado contiene once campos: el slug del plugin, la organización propietaria, la organización que lo compila, sus repositorios, el nombre de su clave de firma, su namespace de despliegue, su prefijo de registro, su esquema de base de datos, sus dominios, su política de cambios y una breve lista de nombres de imagen antiguos que usaba antes de que existiera su prefijo de registro. Esa última lista solo puede reducirse. Como está firmada, una nueva firma puede eliminar una entrada y nada puede añadir una discretamente. La firma es Ed25519 sobre la forma JSON canónica estándar de esos once campos, de modo que un registro con "Tomás" o "Sinéad" se verifica igual en todas partes.
Cuando una versión no coincide con su registro, prevalece el primer rechazo:
| Código | Cuándo | HTTP |
|---|---|---|
DELIVERY_IDENTITY_MISSING |
No hay registro para el plugin | 403 |
DELIVERY_PATH_REFUSED |
Una subida de imagen fuera del prefijo de registro que no está en la lista firmada de nombres antiguos | 403 |
NAMESPACE_MISMATCH |
Un despliegue dirigido a otro namespace | 403 |
IMAGE_NAME_COLLISION |
Un nombre de imagen que ya reclama otro plugin | 409 |
CHANGE_CLASS_NOT_PERMITTED |
Una clase de cambio que la política no gobierna | 403 |
IMAGE_NAME_COLLISION es el que sorprende a la gente. Elija otro nombre y nunca reutilice uno: un nombre de imagen compartido significa que la promoción de un plugin puede mover los pods de otro plugin.
Migraciones, confirmadas y con ámbito definido
Una migración se entrega dentro de la imagen de su plugin y se ejecuta antes de que arranque la nueva versión, mediante el único ejecutor de migraciones del SDK, nexus-migrate. Usted no escribe su propio aplicador. Antes de que ninguna versión pueda avanzar, el mismo ejecutor aplica sus migraciones archivo por archivo sobre una base de datos desechable, de modo que una migración que falla, falla ahí. La compilación shadow de la plantilla llama al ejecutor una vez por archivo, en orden, y registra cada archivo como lo hará producción.
Las reglas del ejecutor son las que comprueban los controles, escritas como código:
- Se conecta con el rol de migrador de su esquema y ejecuta cada archivo como propietario del esquema. Cualquier otro inicio de sesión, y en primer lugar un superusuario, se rechaza. Un archivo que intenta cambiar de rol por sí mismo se rechaza antes de que se ejecute nada.
- El archivo de tenencia, numerado 0, nunca se edita después de aplicarse. Un cambio en la tenencia tiene su propio archivo de revisión,
000_tenancy_r<N>.sql, quenexus-tenancy render --revision <N>escribe por usted. - Normalmente el ejecutor controla la transacción de cada archivo y rechaza un
BEGINoCOMMITdentro de ella. Un archivo que gestiona sus propias transacciones declara que se ejecuta por sentencia, y entonces cadaBEGINque abra debe tener su correspondencia. - Mantiene un libro de registro, una fila por archivo, con el SHA-256 del archivo y cómo se ejecutó. Un archivo aplicado nunca se modifica en su lugar; un cambio es un nuevo archivo numerado.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sqlCon ámbito significa que cada tabla nueva lleva organization_id, owner_user_id y business_unit_id, además de la columna de marca is_demo salvo que gates/demo-exempt.json exima a la tabla con un motivo, con una clave primaria que empieza por la organización y claves foráneas que la incluyen, y con la seguridad a nivel de fila forzada. El control migrations-are-scoped comprueba esas reglas en cada archivo, y migrations-commit-what-they-open cuenta que cada archivo confirma lo que abre. El segundo control existe porque una migración que se revirtió silenciosamente terminó una vez con 0, y la tabla que debía haber creado nunca existió.
Un archivo más pertenece a cada versión. scripts/ci/required-env imprime las variables de entorno que su servicio necesita para arrancar, como un array JSON tomado de su cargador de configuración. La ruta de versión lo ejecuta y rechaza una versión cuyo despliegue no defina todas ellas, de modo que una variable que falta se detecta antes de la versión, no por un pod que no arranca.
node scripts/ci/required-envLanzamiento de habilidades
Los dos tipos de skill llegan a las personas por rutas diferentes, así que publíquelos de forma diferente.
Una skill de manifiesto, una fila tipada en el skills[] de su plugin, se entrega con el plugin y pasa por la misma promoción que el resto. La incorporación sincroniza todo el conjunto de skills con el registro en cada versión. Si deja una skill fuera del conjunto, queda desactivada, y en Enterprise una sincronización con una skill defectuosa no aplica ninguna, de modo que la versión anterior sigue ejecutándose en lugar de la mitad de la nueva.
Una skill de Skills Engine se publica desde la biblioteca. En Enterprise, una que añade una herramienta de escritura espera a que dos personas designadas la aprueben con sus passkeys, y quien la propone no puede ser una de ellas. Una versión aprobada se ejecuta después en modo shadow, luego en canary para una unidad tras controles designados y luego para todos, y se detiene por sí misma si no se cumple un control. Si su plugin y una skill de Skills Engine dependen uno de otro, publique primero la skill y deje que llegue a todos antes de que la versión del plugin que la invoca salga del piloto.
Canales e instalaciones
Una vez que una versión ha superado el piloto y ha llegado a todas las unidades, se ofrece en un canal, y cada unidad elige su canal. Su administrador acepta cada cambio. La página Canales e instalaciones muestra qué unidades ejecutan qué versión, con las tasas de error solo como recuentos: usted ve cómo se comporta su extensión, nunca lo que alguien hizo con ella.
Nuestro plugin carrier-sync ejecuta tres versiones a la vez, y eso es normal. La mayoría de las unidades están en la versión actual, una unidad permanece en una versión anterior en un canal que se mantiene hasta una fecha indicada, y una versión candidata está en un canal que nadie ha elegido todavía. No luche contra ello; una unidad que necesita estabilidad para una auditoría tiene derecho a ella.
Registros y métricas de su extensión
La página de registros y métricas de su paquete está limitada a sus propias cargas de trabajo, en las unidades donde puede consultar. Puede filtrar por unidad y entorno, y ve recuentos, tiempos y estados.
Los campos personales se sustituyen antes de escribir una línea, y el contenido de los clientes, como el texto de las reclamaciones, el correo o el contenido de los documentos, nunca se escribe en los registros. Los registros se conservan 14 días. La organización la establece la pasarela, nunca su consulta, por lo que una consulta que nombra otra organización se rechaza con TENANT_BOUNDARY. El asistente del panel puede leer los mismos registros con usted, y solo estos: cuando le pregunté por qué los registros de desviaciones llegaron tarde una mañana, atribuyó 18 minutos de reintentos a lecturas duplicadas de la alimentación eléctrica de un muelle.
Reversión
Hay dos tipos de reversión, y ambos son cambios revisados, no interruptores.
Revertir un entorno utiliza la versión anterior. Cada entorno la conserva durante 30 días. La reversión se prepara como un cambio en la versión, muestra una vista previa de lo que hará y requiere una segunda persona; una vez aprobada, el pipeline revierte en aproximadamente un minuto. Cada reversión se cronometra, y también cada simulacro, así que practique una antes de necesitarla. Revertir una unidad utiliza la página Canales e instalaciones. El cuadro de diálogo de reversión indica qué cambia (esa unidad vuelve a ejecutar la versión anterior y su tasa de error se supervisa durante una hora), qué se mantiene (las demás unidades, y la configuración y los registros de la unidad), el motivo y quién es la segunda persona: el administrador de esa unidad.
La configuración y los registros se conservan tras una reversión, así que planifique cada versión suponiendo que la versión anterior puede volver a ejecutarse sobre los datos que escribió la más reciente. Esa es la razón práctica para mantener las migraciones aditivas dentro de una versión que podría revertir, y la razón por la que pedimos que dos personas aprueben cada una. Un cambio de modelo es igual: un revisor puede, y debe, solicitar el plan de reversión de una solicitud de cambio del grafo antes de aprobarla.
Las skills se revierten con más suavidad. Devolver la etiqueta activa a una versión anterior es un solo paso, y las ejecuciones ya en curso terminan con la versión con la que empezaron.
Retirada de una versión
Una versión, una vez publicada, nunca se edita. Una versión que ya no debe usarse se retira, y una corrección se publica con un nuevo número de versión. Los propios canales de publicación del SDK siguen el mismo hábito: una versión defectuosa del SDK se retira, nunca se sustituye por un contenido diferente con el mismo número. Cópielo, porque un número de versión que puede significar dos compilaciones diferentes hace que toda prueba sobre él carezca de valor.
Retirar un plugin o paquete detiene las nuevas instalaciones. Las unidades conservan la versión que ejecutan hasta que cambian, por lo que retirarlo es una señal y un plazo, no un interruptor de apagado. Indique a los administradores de las unidades a qué versión deben pasar y para cuándo.
Retirar una skill sigue la misma idea con un paso más. Skills Engine traslada a todos los llamadores restantes a un sustituto después de ejecutar los casos del sustituto, detiene las nuevas ejecuciones y conserva las versiones, los casos y los registros de ejecución sellados, de modo que la skill pueda restablecerse si el sustituto resulta erróneo.
Lista de comprobación de lanzamiento
Esta es la lista que leemos antes de cada versión de Cold chain. Es breve porque la plataforma comprueba la mayor parte por nosotros.
- Las versiones coinciden: el manifiesto,
pack.jsony el modelo de conocimiento si cambió. - Todos los controles están en verde localmente, desde cero, y se ha demostrado que cada prueba nueva fallaba primero.
- La página Manifiesto y permisos no muestra ninguna ampliación, o la ampliación es la que pretendíamos y los revisores saben por qué.
- Cada migración es un nuevo archivo numerado, con alcance definido, y se aplica sin errores sobre una base de datos desechable.
scripts/ci/required-envenumera todas las variables que necesita el servicio, y la implementación establece cada una.- El plan de reversión está escrito en el cambio, también para cualquier cambio de modelo.
- Dos revisores que no son el autor están disponibles esta semana.
El último punto parece trivial. Es el que ha retrasado más versiones nuestras que todos los controles juntos.



