More › editions

More

Editions and the stability promise

An edition is the version of the language a project is written in, as go.mod names a Go version. Edition 1.0 starts the stability promise: a model written with the core keeps building in every 1.x edition, and a name that changes is read for one more edition, with a warning and an automatic fix, before it becomes an error.

Writing the edition#

project Kettle "Kettle" {
  version "0.1.0"
  edition "1.0"
}

Without an edition, a project is read as it always was: every old form is a warning. An edition archec does not know, or a newer one, is an error: update archec, or it would read the project wrongly.

archec fmt --edition 1.0 --write main.arche writes the standard spellings and sets the edition. Then archec fix main.arche rewrites the old names the warnings point at.

The editions#

Edition What it changes
0.10, 0.11 nothing: they read a model as it always was
0.12 an old spelling of a keyword or a property is an error (msg, porttype, mode for a state)
0.13 a second way of writing a thing is an error: a case's step blocks, a stimulus, a link to a requirement written from its far end (satisfied-by, trace satisfies)
1.0 nothing breaks: it reads a model as 0.13 does, and starts the promise below

A test case's lines are read the same way in every edition: the action language where a line is one, Python where it is not (spec.md, "Test lines"). A Python line keeps working; it is the codegen extension, and archec fix writes the common ones in the action language.

Each edition after 1.0 will say here what it turns from a warning into an error. Existing projects on 0.12 or 0.13 keep working: their edition says how they are read.

The promise#

From edition 1.0 on:

  • The core keeps its meaning. Every declaration, property, action-language statement and test-case form of core.md means the same in every 1.x edition. src/core.ts lists them, and the tests check that the tutorials, examples/greenhouse, every example and every template still build.
  • A change goes through one edition. A name that is renamed or removed (a keyword, a property, a declaration of a library) is still read in the edition that changes it, with a warning and its fix. It is an error only from the edition after.
  • The fix is automatic. archec fix and the quick fix in the editor rewrite the old name. The warning says which edition stops reading it.
  • Extensions follow the same rule when they change, but they may change in any edition: they have no promise of staying as they are. archec check --core says which parts of a model are extensions.

What the promise does not cover: the generated code and files (they may improve between releases; their meaning is kept), the text of messages, and the commands' output layout.

Renamed names#

A library renames one of its declarations in its library.arche. It gives the edition the rename is made for, then the old names and the new ones:

library arche-hw-store "Arche board store" {
  version "0.1.0"
  renamed "1.0", {
    Led: GpioLed, Button: GpioButton, Relay: GpioRelay, Buzzer: GpioBuzzer, RgbLed: GpioRgbLed,
    Servo: HobbyServo, Stepper: GpioStepper, TemperatureSensor: Thermistor
  }
}

A model that still writes part led: Led builds as if it wrote part led: GpioLed. In a project of edition 1.0 or older (or with no edition), it is a warning:

main.arche:3:22 warning 'Led' is now 'GpioLed' (arche-hw-store, edition 1.0): read until the next edition — `archec fix` rewrites it [renamed]

From the next edition on, the same line is an error, with the same fix. An old name is read only where it is declared nowhere: a model's own Led component is its own. The renamed names are those of types (a part's component, a port's interface, a field's type), of references in properties (sends LAMP_ON), and of the names in code: a ```arche body (LampState { on: true }, var s: LampState, Colour.Red, send cmd LAMP_ON { … }) and a test case's lines, in Python or in the action language (do send(b.press, LAMP_ON(on=True))). In code, only a whole name that names the declaration is: not a field (x.LampState, { LampState: 1 }), a local, a parameter, a member of the part or a part, nor a word in a string or a comment.

The language's own renamed keywords and properties work the same way, from a table in archec (alias-keyword): msg was read with a warning until 0.12.

Limits#

  • A rename names one declaration at a time. A declaration split in two, or whose ports changed, needs a note for the people who use it.
  • An old name in a ```python or TypeScript body is not renamed: the action language's bodies and the test lines are.