---
title: "19.4 Moving a package forward"
url: https://una-lang.org/en/learn/editions/moving-a-package-forward/
release: v0.4.0
edition: "0.1, 0.2, 0.3, 0.4"
---

# 19.4 Moving a package forward

## 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:

:::steps
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](https://una-lang.org/en/learn/editions/edition-0-3-a-preview/#what-03-reports-u3025-and-u3026), and step 3 shows one exact repair:

```sh
una fix --dry-run .
```

```text include="steps/15-restock-0-3/expected/commands/fix.txt"
$ 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:

```diff include="steps/14-restock..steps/17-restock-moved:src/restock.una" title="src/restock.una"
--- 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:

```text include="steps/17-restock-moved/expected/output.txt"
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](https://una-lang.org/en/learn/editions/an-edition-is-part-of-the-package/#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:

```text include="steps/02-arrived-0-2/expected/commands/fix.txt"
$ una fix --dry-run .
```

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

```diff include="steps/01-arrived..steps/18-arrived-moved:src/restock.una" title="src/restock.una"
--- 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`:

```text include="steps/18-arrived-moved/expected/output.txt"
6 units arrived
```

## 19.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](https://una-lang.org/en/learn/packages/the-manifest-and-the-lock/#s11-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](https://una-lang.org/en/learn/editions/common-mistakes/#moving-a-package-back-u0101-u7002) 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: [Letting `una fix` rename a keyword](https://una-lang.org/en/learn/editions/common-mistakes/#letting-una-fix-rename-a-keyword-u0103) 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:

:::decide
**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](https://una-lang.org/en/learn/editions/edition-0-4-a-preview/#s19-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](https://una-lang.org/en/learn/editions/an-edition-is-part-of-the-package/#check-yourself-a-word-reserved-for-later), and move it to `0.2` without renaming anything:

```diff include="steps/06-take..steps/19-take-0-2:una.toml" title="una.toml"
--- 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?

:::answer Show the answer
Two syntax errors, and no repair:

```text include="steps/19-take-0-2/expected/rendered.txt"
[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
───╯
```

```text include="steps/19-take-0-2/expected/commands/fix.txt"
$ 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](https://una-lang.org/en/learn/memory/giving-a-value-up-take/#s16-3)). 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.
:::
