Home / Docs / Specification / 30. Packages and dependencies
30.8 Migration: una migrate
una --json migrate --dry-run of a package hello of edition 0.3, with a module and no verification.lock, prints one una.migrate/1 document (rule 8):
{
"schema": "una.migrate/1",
"dry_run": true,
"written": [],
"removed": [],
"name": {"from": "hello", "to": "hello"},
"edition": {"from": "0.3", "to": "0.4"},
"default_lock": true,
"comments_not_carried": [],
"ita_una": "ita hello\n version 0.1.0\n edition 0.4\n",
"ita_lock": "-- Written by `una ita`; do not edit.\nlock 1\n\nsolver\n encoding \"una-smt-1\"\n name \"z3\"\n version \"5.1.0\"\n logic \"QF_UFLIA\"\n steps 5000000\n seed 0\n",
"diagnostics": []
}-
Edition 0.4 and later are not written in
una.toml.una.tomlnamingedition = "0.4", or (ADR 0139)edition = "0.5", is U7002 at the value, with the repairuna migrate; the package is still checked in the edition it names. No releasedunaaccepted that form, so this changes no released form (ADR 0122 Question 8.1). -
una migrate [path] [--dry-run] [--name <name>]moves the package atpath,.by default, fromuna.tomlandverification.lock, of any edition from0.1to0.5, toita.unaandita.lockof edition0.4, or of edition0.5whenuna.tomlnames it, since no migration lowers an edition, and nothing else: a directory that already hasita.una, or that is not a package withuna.tomlandsrc/, is a usage error (exit code 2). -
What it maps.
una.toml/verification.lockita.una/ita.lock[package] name = "events-example"ita events_example:-becomes_; a name that is still not a package name needs--nameversion,edition,profilehead lines; editionbecomes0.4, or stays0.5; a version that is notMAJOR.MINOR.PATCHis refused;profileis written when it issystems[labels] categorieslabels, one per line[trusted] modulestrusted[escape_budget] checked_per_moduleescapes,checked per module <n>, when not 0[boundaries]boundaries, withmaylines[contracts]contracts, the clause strings as lines[run] entry,grantsrun,entry,grantswith one line per spec, asfiles "data/" read, write[run] max_memorymax_memory, inrunafterentryverification.lockthe solversection ofita.lock; the release's default when the package has noneA text is written with
",\,{and}escaped, and every control or bidirectional character as\u{…}. -
Comments. A run of comment lines of
una.tomldirectly before a table header or a key is carried, as--comments, above the line it becomes. Every other comment is listed in the output, with its line. -
Refusals. An invalid
una.toml, other than its edition0.4or0.5, or an invalidverification.lockis refused, with each problem printed, and nothing is written (exit code 2). -
Writing. It writes
ita.unaandita.lock, each through a temporary file and a rename, rewrites each module in the canonical form of edition0.4(spec/15 §2), which edition0.5keeps, reading it with the keywords of the edition it writes (#1744), then removesuna.tomlandverification.lock. The canonical form of edition0.4wraps long lines, which earlier editions never do (ADR 0125, amendment of 2026-10-25): a module that differs from that form is written through a temporary file and a rename, and listed inwrittenby its path. For a module that was canonical in its own edition, the rewrite changes only white space. A module with a syntax error in that edition has no canonical form and is left as it is. The rewrite is one check of the package, asuna fmtdoes. -
The clashes of the edition. It then checks the package, with its modules rewritten, at tier 0 in the edition of the
ita.unait wrote, and prints every diagnostic the change of edition causes, those the package has in that edition and not in its own, with their repairs, such as a function namedwithin(U0103). It applies none:una fixdoes that. Its exit code is 0: the diagnostics are the next steps of the migration. -
Output.
--dry-runprints the two files and the diagnostics, and writes nothing.--jsonprints one document,una.migrate/1:schemafirst, thendry_run,written,removed,name(from,to),edition(from,to),default_lock,comments_not_carried(line,text),ita_unaandita_lock(the files' texts with--dry-run,nullotherwise), anddiagnostics.