Home / Learn / 19 Editions
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:
- Change the edition in
una.toml, and only that line. - Run
una check .and read every diagnostic. Each one is a place the new edition reads differently. - Run
una fix --dry-run ., thenuna fix ., to apply the repairs that are exact. - Repair the rest by hand, guided by each diagnostic's repairs.
- Run
una test ., and compare the output ofuna 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:
una fix --dry-run .$ una fix --dry-run .
fixed src/restock.una:14:36 U3025 remove the clauseuna 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:
--- 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() -> Unituna run . prints the same as before the move:
LAMP-01: order 6
SHELF-03: enough
DESK-02: order 1
7 units to orderThe 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:
$ una fix --dry-run .Step 4 is the rename by hand. before says what the count is:
--- 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:
6 units arrived19.4.6 How a move behaves
- One edition per package. Every module moves at once. A program is one package, so it has one edition: up to edition
0.3, a package does not depend on other packages (section 11.3). - Moving back fails where the code uses the later edition. A construct of a later edition is usually a syntax error (U0101), a reserved word (U0103) or an unknown table (U7002) in an earlier one: Moving a package back shows it. A prelude function or a type rule of a later edition gives a type error, such as U1001, U2001 or U2002.
- Read a rename before you apply it. In edition
0.1, a reserved word gets a rename repair, which is right for a name and wrong for a construct of a later edition: Lettinguna fixrename a keyword shows the second case. - The output is the test of a move. A move changes the language, not the program's behavior: the tests pass, and
una run .prints what it printed before.
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:
--- 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:
[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
───╯$ 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.