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.tslists 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 fixand 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 --coresays 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
```pythonor TypeScript body is not renamed: the action language's bodies and the test lines are.