Documentación / Integraciones / Modo de migración

Guía de migración

Una guía a partir del snapshot y luego una edición acotada de las cadenas de versión. No reescribe tu código fuente.

La guía

Un dry run la imprime antes del diff.

• Dónde está la dependencia, la versión que publica Stellar, el protocolo y la hora de observación. Si el snapshot no tiene número de protocolo, la guía lo indica.
• Pasos numerados: la cadena de versión que kedgeway va a cambiar, los comandos que ejecutas y una verificación de que tu Stellar CLI y la red donde haces deploy usen ese protocolo. kedgeway no lee ninguno de los dos.
• Para soroban-client y el stellar-sdk sin scope, los archivos y las líneas que los importan, hasta 20. La búsqueda usa la misma profundidad y los mismos directorios omitidos que el escaneo de manifiestos, y no sigue enlaces simbólicos.
• Resultados de documentación de Raven cuyo título o URL es un documento de migración. Se omite una página que solo menciona una migración dentro de un fragmento. Si ninguno califica, la guía dice que no se obtuvo ninguna guía de actualización.

Ejecútalo

kedgeway migrate [path]            # dry run (default): prints a guide and a diff, edits nothing
kedgeway migrate [path] --dry-run  # the same; cannot be combined with --write
kedgeway migrate [path] --write    # applies the edits
kedgeway migrate . --fixture snapshot.json
kedgeway migrate . --offline       # cached snapshot only (also --no-cache, --max-age)

Qué cambia

• Rust. Un soroban-sdk obsoleto o atrasado se actualiza a la versión actual exacta (por ejemplo 28.0.0). Solo cambia la cadena de versión entre comillas en esa línea, así que se conservan los comentarios, features y el formato. Los miembros con workspace = true no se tocan y, en su lugar, se actualiza la raíz del workspace. Se conservan los prefijos =, ~ y ^; los demás rangos (>=, <) pasan a ser pasos manuales.
• JavaScript. @stellar/stellar-sdk se actualiza a la versión actual y conserva ^ o ~ (las versiones fijadas siguen siendo exactas). package.json conserva el orden de sus claves y su sangría.
• Paquetes heredados. soroban-client y el stellar-sdk sin scope se reemplazan por @stellar/stellar-sdk en ^current, junto con un paso manual que lista patrones de rg para los imports que debes actualizar tú.
• Alias. Un miembro como "stellar-sdk": "npm:@stellar/stellar-sdk@^12.0.0" se lee como el paquete real. Una actualización reescribe el valor en su lugar a npm:@stellar/stellar-sdk@^<current> y conserva el prefijo. Un alias de un paquete heredado se reemplaza por completo por "@stellar/stellar-sdk": "^<current>". Un alias sin versión pasa a ser un paso manual.

Qué se niega a hacer

• @stellar/stellar-base es un paso manual, porque el snapshot no tiene una versión actual de base.
• Nunca ejecuta cargo ni npm. En su lugar, imprime los comandos que siguen: cargo update -p soroban-sdk y npm install.
• --write se rechaza si un archivo que tocaría tiene cambios sin commit en git. La verificación pasa en silencio solo cuando git no está instalado o la ruta no está en un repositorio. Cualquier otra falla de git también rechaza la escritura.
• Todo lo que no puede hacer de forma segura se lista como paso manual con su motivo. Solo se editan versiones simples: 12.x, 12 || 13 y los rangos con comas pasan a ser pasos manuales, y las dependencias en peerDependencies, optionalDependencies, overrides o resolutions no se tocan. kedgeway nunca adivina.
• Las ediciones son exactas a nivel de byte: en package.json solo cambian los fragmentos afectados, y las escrituras son atómicas. Nunca se editan manifiestos que sean enlaces simbólicos.

Lockfiles

• migrate decide a partir de la versión resuelta cuando existe un lockfile y luego edita solo el manifiesto. Nunca edita un lockfile.
• Cuando el manifiesto ya admite el major actual pero el lockfile fija una versión anterior, una actualización no cambiaría nada. En su lugar, kedgeway emite un paso manual para refrescar el lockfile: cargo update -p soroban-sdk, npm update <name>, pnpm update <name> o yarn upgrade <name>.
• Siempre que un archivo del plan tiene lockfile, el plan también te recuerda que las ediciones no lo actualizan.

Códigos de salida