---
title: "19.1 An edition is part of the package"
url: https://una-lang.org/en/learn/editions/an-edition-is-part-of-the-package/
release: v0.4.0
edition: "0.1, 0.2, 0.3, 0.4"
---

# 19.1 An edition is part of the package

## 19.1.1 What an edition is

A board game sold for many years often comes in editions. The second edition adds new cards and fixes a rule that players found unfair, and the box says which edition it is. Friends who own the first edition still play by its rules, and their game still works; nobody comes to their house to change the cards.

Una works the same way, with two words that are easy to mix up:

- A **release** is a version of the `una` program itself, such as una 0.4.0. You install a release, and a newer one replaces it.
- An **edition** is a version of the Una language: its keywords, its constructs and its rules. Una 0.4.0 serves five, `0.1` to `0.5`, and this chapter uses the first four.

A **keyword** is a word the language keeps for itself, such as `if`, `for` or `uses`: it starts a piece of syntax, so it cannot name a value, a parameter or a field. A **construct** is one form of code with its own syntax and meaning, such as a `for` loop, a kind or a `uses` clause.

Each package names its edition in `una.toml`, and a release checks each package by the rules of the edition it names. One release serves several editions at once, so installing a newer release does not change the language your packages are written in. Only you change that, by editing one line.

Each example of this chapter is a package, made as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains, and the chapter's download, `19-editions.tar.gz`, holds them all.

## 19.1.2 Why a language needs editions

Here is a small package in edition `0.1`. It counts how many units arrived on a shelf, and names its parameters `old` and `new`:

```toml include="steps/01-arrived/una.toml" title="steps/01-arrived/una.toml"
[package]
name = "restock"
version = "0.1.0"
edition = "0.1"

[run]
entry = "restock"
grants = ["console"]
```

```una include="steps/01-arrived/src/restock.una" title="steps/01-arrived/src/restock.una" verified="check, run"
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

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("{arrived(4, new: 10)} units arrived")
```

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

In edition `0.1`, `old` is an ordinary word. Edition `0.2` made it a keyword: inside an `ensures` clause, `old(x)` names the value an `edit` parameter had when the call began ([chapter 5](https://una-lang.org/en/learn/contracts/postconditions-ensures-and-counterexamples/#s5-2)). Check the same code under edition `0.2`, with only the edition line changed:

```diff include="steps/01-arrived..steps/02-arrived-0-2:una.toml" title="una.toml"
--- a/una.toml
+++ b/una.toml
@@ -1,7 +1,7 @@
 [package]
 name = "restock"
 version = "0.1.0"
-edition = "0.1"
+edition = "0.2"
 
 [run]
 entry = "restock"
```

```text include="steps/02-arrived-0-2/expected/rendered.txt"
[U0101] Error: `old` is a reserved keyword, so it cannot name a binding
   ╭─[ src/restock.una:4:9 ]
   │
 4 │ arrived(old: Int, new: Int) -> Int = new - old
   │         ─┬─
   │          ╰─── `old` is a reserved keyword, so it cannot name a binding
   │
   │ Help: repair 1: choose another name, such as `old_value`
   │
   │ Note: run `una explain U0101` for an explanation
───╯
```

U0101: a keyword cannot name a binding. The code did not change; the language did. In a language without editions, that would happen to this package on the day una was upgraded, whether or not anyone was ready.

With editions, nothing happens to it. The package says `edition = "0.1"`, and every release that serves edition `0.1` checks it by the rules of `0.1`, where `old` is a name. It moves to `0.2` only when someone changes that line, and [section 19.4](https://una-lang.org/en/learn/editions/moving-a-package-forward/#s19-4) shows how.

## 19.1.3 How to write the edition

`[package] edition` names the edition, as a text in quotes. It is a required key of `una.toml`, with `name` and `version`.

### 19.1.3.1 `edition = "0.1"`, `"0.2"` or `"0.3"`

Each of the three editions is written the same way:

- `edition = "0.1"` is the first edition. It has kinds, functions, lists, contracts, capabilities and labels.
- `edition = "0.2"` is the edition of most of this tutorial. It adds loops ([chapter 9](https://una-lang.org/en/learn/loops/)), the `edit` and `take` parameter modes ([chapter 16](https://una-lang.org/en/learn/memory/passing-a-value-in-and-out-edit/#s16-2) teaches `edit`, and [section 16.3](https://una-lang.org/en/learn/memory/giving-a-value-up-take/#s16-3) `take`), `together` ([chapter 15](https://una-lang.org/en/learn/concurrency/running-work-at-the-same-time-together/#s15-1)), maps and more ([section 19.2](https://una-lang.org/en/learn/editions/what-edition-0-2-adds/#s19-2)).
- `edition = "0.3"` is a preview, with stricter rules and a few constructs that narrow what a program may do ([section 19.3](https://una-lang.org/en/learn/editions/edition-0-3-a-preview/#s19-3)).

Edition `0.4`, also a preview, is not written in `una.toml`: a package of edition `0.4` describes itself in a file of its own, `ita.una` ([section 19.5](https://una-lang.org/en/learn/editions/edition-0-4-a-preview/#s19-5)), so `edition = "0.4"` in `una.toml` is U7002, whose message says to run `una migrate`. Edition `0.5`, a later preview, is described in `ita.una` too; this book does not use it yet.

### 19.1.3.2 An edition una does not know

An edition this release does not serve is U7002, the code for a problem in `una.toml`:

```diff include="steps/01-arrived..steps/03-edition-unknown:una.toml" title="una.toml"
--- a/una.toml
+++ b/una.toml
@@ -1,7 +1,7 @@
 [package]
 name = "restock"
 version = "0.1.0"
-edition = "0.1"
+edition = "0.9"
 
 [run]
 entry = "restock"
```

```text include="steps/03-edition-unknown/expected/rendered.txt"
[U7002] Error: edition `0.9` is not supported; the editions are "0.1", "0.2", "0.3", "0.4" and "0.5"
   ╭─[ una.toml:4:11 ]
   │
 4 │ edition = "0.9"
   │           ──┬──
   │             ╰──── edition `0.9` is not supported; the editions are "0.1", "0.2", "0.3", "0.4" and "0.5"
   │
   │ Note: run `una explain U7002` for an explanation
───╯
```

The mark is on the value, and the message lists the editions this release serves, `0.4` and `0.5` included.

### 19.1.3.3 A manifest without an edition

Leaving the line out is U7002 too, at the `[package]` table that lacks it:

```text include="steps/04-no-edition/expected/rendered.txt"
[U7002] Error: [package] has no `edition`
   ╭─[ una.toml:1:2 ]
   │
 1 │ [package]
   │  ───┬───
   │     ╰───── [package] has no `edition`
   │
   │ Note: run `una explain U7002` for an explanation
───╯
```

A package has no default edition: its manifest must state one.

### 19.1.3.4 A single file

A single `.una` file checked on its own, outside a package, as in `una check shelf.una`, has no `una.toml`. It has edition `0.1`.

## 19.1.4 A stock list in edition `0.1`

This step is a stock list in edition `0.1`. It has a record kind, a function and a list, and its total is computed with `fold` ([chapter 10](https://una-lang.org/en/learn/collections/functions-over-lists-map-filter-and-fold/#s10-3)), since edition `0.1` has no loops:

```toml include="steps/05-edition-0-1/una.toml" title="steps/05-edition-0-1/una.toml"
[package]
name = "shelf"
version = "0.1.0"
edition = "0.1"

[run]
entry = "shelf"
grants = ["console"]
```

```una include="steps/05-edition-0-1/src/shelf.una" title="steps/05-edition-0-1/src/shelf.una" verified="check, run"
module shelf

--- A line of a stock list: a SKU and the units on hand.
kind Line
  sku: Text
  units: Int

--- The units of every line, added up.
total(lines: List[Line]) -> Int = lines.fold(initial: 0, step: fn(sum, line) -> sum + line.units)

pub main() -> Unit
  uses @console: Console[print]
=
  let lines = [Line(sku: "LAMP-01", units: 4), Line(sku: "DESK-02", units: 1)]
  @console.print("{lines.len} lines, {total(lines)} units")
```

`una run .` prints:

```text include="steps/05-edition-0-1/expected/output.txt"
2 lines, 5 units
```

## 19.1.5 How editions behave

### 19.1.5.1 One binary serves every edition

`una --version` prints the version of `una`, the editions it serves, which of them are previews, and the version of Z3 built into it. At this release it lists the editions `0.1` to `0.5`, of which `0.3`, `0.4` and `0.5` are previews. Every one of them is checked by the same binary, so one machine can check, test and build packages of different editions side by side.

### 19.1.5.2 Stable editions and previews

An edition is either **stable** or a **preview**:

| Edition | Status | What it promises |
| --- | --- | --- |
| `0.1` | Stable | A later release does not change what it accepts or rejects, except to fix a soundness or security error |
| `0.2` | Stable | The same promise |
| `0.3` | Preview | It may still get stricter in a later release, never looser for the programs `0.2` can express |
| `0.4` | Preview | It may change in a later release, never in silence: a construct that changes or leaves gives a diagnostic; described in `ita.una` ([section 19.5](https://una-lang.org/en/learn/editions/edition-0-4-a-preview/#s19-5)) |
| `0.5` | Preview | A later preview, also described in `ita.una`; this book does not use it yet |

A package on a stable edition can stay there for as long as it likes.

Release 0.4.0 serves edition `0.4` as a preview: a later release makes it stable. Edition `0.5`, also a preview, holds what comes after it.

### 19.1.5.3 Words reserved for later editions

Some words were set aside before the editions that use them existed. In edition `0.1`, `edit`, `take` and `together` are **reserved**: not keywords yet, and not names either. Using one gives U0103, whose message names the edition that has it, written with a `v`, such as `` `edit` is reserved for v0.2 (memory model) ``, or says `a later edition` for a word that no edition has yet. Reserving a word early keeps it free: no `0.1` package can use `edit` as a name, so no `0.1` package breaks when `0.2` makes it a keyword. `old` was not reserved in `0.1`, which is why the package of [Why a language needs editions](#why-a-language-needs-editions) could use it. Nor was `weak`, a name in `0.1` that edition `0.2` reserves for a later edition ([The keywords `0.2` adds](https://una-lang.org/en/learn/editions/what-edition-0-2-adds/#the-keywords-02-adds)).

### 19.1.5.4 What an edition fixes, and what improves with every release

What an edition fixes is the language a package is written in: its keywords, its constructs, its rules and the headers of the prelude, the functions every module has without an import ([chapter 3](https://una-lang.org/en/learn/text-and-conditions/working-with-text-the-preludes-functions-and-method-calls/#s3-2)). For example, `min`, `max` and `sum` work on `Int` in edition `0.1`, and a later release keeps those headers for it, while edition `0.2` makes them generic: they work on any type with the right constraint, such as `Ord` for `min` ([chapter 4](https://una-lang.org/en/learn/kinds/generic-kinds-and-constraints/#s4-4)). What improves with every release, for every edition, is everything around the language: the wording of messages, the explanations of `una explain`, the repairs, the speed of the checks and the tools of [chapter 18](https://una-lang.org/en/learn/tools/).

## 19.1.6 Check yourself: a word reserved for later

This package is in edition `0.1`, and names a parameter `take`:

```una include="steps/06-take/src/shelf.una" title="steps/06-take/src/shelf.una"
module shelf

--- The units left after a customer takes `take` of `units`.
left(units: Int, take: Int) -> Int = units - take

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("{left(10, take: 3)} left")
```

Does it check? If not, what does `una fix --dry-run .` offer?

:::answer Show the answer
It does not check. `take` is reserved in edition `0.1`, so each of its three uses is U0103; the first:

```text include="steps/06-take/expected/rendered.txt#L1-L10"
[U0103] Error: `take` is reserved for v0.2 (memory model)
   ╭─[ src/shelf.una:4:18 ]
   │
 4 │ left(units: Int, take: Int) -> Int = units - take
   │                  ──┬─
   │                    ╰─── `take` is reserved for v0.2 (memory model)
   │
   │ Help: repair 1: rename it to `the_take`; edit src/shelf.una:4:18..4:22 to "the_take"
   │
   │ Note: run `una explain U0103` for an explanation
```

`una fix --dry-run .` would rename every use:

```text include="steps/06-take/expected/commands/fix.txt"
$ una fix --dry-run .
fixed src/shelf.una:4:18 U0103 rename it to `the_take`
fixed src/shelf.una:4:46 U0103 rename it to `the_take`
fixed src/shelf.una:9:29 U0103 rename it to `the_take`
```

Here the rename is right, since `take` is meant as a name: `the_take` works, and a better name, such as `taken`, works too. When a reserved word is meant as the construct of a later edition, the rename is wrong; [Letting `una fix` rename a keyword](https://una-lang.org/en/learn/editions/common-mistakes/#letting-una-fix-rename-a-keyword-u0103) shows that case.
:::
