Home / Learn / 19 Editions

Release v0.4.0Edition 0.1, 0.2, 0.3, 0.4

19.4 Moving a package forward

Page 5 of 11

19.4.1 What a move is

Moving a package means changing the edition its una.toml names to a later one, and changing whatever code the new edition reads differently. The edition line is the whole decision; the rest is what the checker asks for.

19.4.2 A move is a change of its own

Make the move a change of its own, with the edition line and the repairs it needed and nothing else, so that a reviewer reads it as a move and not as new behavior. The edition belongs to the package, not to a module: every module of a package moves together, and a store whose code is split into several packages can move them one at a time, each on the day its own tests are ready.

19.4.3 The steps of a move

Moving a package to a later edition is a short loop. In the package's directory:

  1. Change the edition in una.toml, and only that line.
  2. Run una check . and read every diagnostic. Each one is a place the new edition reads differently.
  3. Run una fix --dry-run ., then una fix ., to apply the repairs that are exact.
  4. Repair the rest by hand, guided by each diagnostic's repairs.
  5. Run una test ., and compare the output of una run . with the output before the move.

19.4.4 Moving the restock list to 0.3

For the restock list, the check of step 2 is the output of What 0.3 reports, and step 3 shows one exact repair:

sh
una fix --dry-run .
Terminal
$ una fix --dry-run .
fixed src/restock.una:14:36 U3025 remove the clause

una fix . removes the clause. The attempt is left to you: remove it, and replace the when with the value it unwrapped. The package after both repairs:

src/restock.unadiff
--- a/src/restock.una
+++ b/src/restock.una
@@ -12,7 +12,6 @@
 order_text(line: Line) -> Text
 =
   let wanted = order_quantity(line)
-    if error use 0
   if wanted == 0 then "{line.sku}: enough" else "{line.sku}: order {wanted}"
 
 --- The total of every order quantity.
@@ -20,10 +19,7 @@
 =
   let edit sum = 0
   for line in lines
-    let outcome = attempt order_quantity(line)
-    sum = when outcome
-      is Ok(wanted) -> sum + wanted
-      is Err -> sum
+    sum = sum + order_quantity(line)
   sum
 
 pub main() -> Unit

una run . prints the same as before the move:

Output
LAMP-01: order 6
SHELF-03: enough
DESK-02: order 1
7 units to order

The move changed no output, removed a clause and an arm that never ran, and left a total that reads as what it is: a sum.

19.4.5 Moving a name that became a keyword

The package of Why a language needs editions moves to 0.2 the same way. Step 2 gives U0101 at old, with the repair "choose another name, such as old_value", which has no edit, since the right name is a choice. Step 3 shows that una fix has nothing to apply:

Terminal
$ una fix --dry-run .

Step 4 is the rename by hand. before says what the count is:

src/restock.unadiff
--- a/src/restock.una
+++ b/src/restock.una
@@ -1,7 +1,7 @@
 module restock
 
---- How many units arrived: the count `new` on the shelf now, less the count `old` from before.
-arrived(old: Int, new: Int) -> Int = new - old
+--- How many units arrived: the count `new` on the shelf now, less the count `before`.
+arrived(before: Int, new: Int) -> Int = new - before
 
 pub main() -> Unit
   uses @console: Console[print]

The package checks in 0.2, and prints what it printed in 0.1:

Output
6 units arrived

19.4.6 How a move behaves

19.4.7 Which edition to name

The table sums up which edition a package should name:

Which to use:

Your package… Edition
Is stable code that you do not want to touch Keep its edition: every release that lists it in una --version serves it
Uses loops, maps, together or any construct of this book outside chapter 13 and section 19.3 0.2
Needs a condition on an operation, a locked contract, a boundary, a narrowed rebinding or units 0.3, the preview
Needs another package, or the constructs of long-running programs 0.4, the preview, with ita.una (section 19.5)
Is new, and should follow the stable rules 0.2

19.4.8 Check yourself: a parameter named take, moved

Take the 0.1 package of Check yourself: a word reserved for later, and move it to 0.2 without renaming anything:

una.tomldiff
--- a/una.toml
+++ b/una.toml
@@ -1,7 +1,7 @@
 [package]
 name = "shelf"
 version = "0.1.0"
-edition = "0.1"
+edition = "0.2"
 
 [run]
 entry = "shelf"

In 0.1, each use of take was U0103, with a rename. What does una check . report in 0.2, and what does una fix --dry-run . offer?

Show the answer

Two syntax errors, and no repair:

Diagnostic
[U0101] Error: unexpected `:`, expected a parameter name
   ╭─[ src/shelf.una:4:22 ]
   │
 4 │ left(units: Int, take: Int) -> Int = units - take
   │                      ┬
   │                      ╰── unexpected `:`, expected a parameter name
   │
   │ Note: run `una explain U0101` for an explanation
───╯
[U0101] Error: unexpected `:`, expected an expression
   ╭─[ src/shelf.una:9:33 ]
   │
 9 │   @console.print("{left(10, take: 3)} left")
   │                                 ┬
   │                                 ╰── unexpected `:`, expected an expression
   │
   │ Note: run `una explain U0101` for an explanation
───╯
Terminal
$ una fix --dry-run .

From edition 0.2 on, take is a keyword that starts a parameter's mode, as in take items: List[Line] (chapter 16). So una reads take and expects the parameter's name after it, and finds :. The messages describe the syntax, not the word, which makes them harder to read: when a move gives a syntax error at a word that the new edition made a keyword, rename the word. Here, rename take to taken, by hand, before or after the move.

Next:19.5 Edition 0.4, a preview