# Stability

- **Status:** accepted by the project owner on 2026-11-06. It applies from the release of version 1.0. The edition `2026` is frozen.
- **Related documents:** [limits of version 0](https://surface.solenovis.com/docs/limits.md), [language spec](https://surface.solenovis.com/docs/language.md), [PLAN.md](https://git.solenovis.com/henning.liemant/surface/src/branch/main/PLAN.md) (section 13)

This page says what an app can rely on after version 1.0. Version 0 has no such promise.

## What stays stable

Each release of version 1 keeps these parts:

- The syntax and the rules of the language spec.
- The built-in components, their attributes and their events.
- The utilities of the layout spec, and their results.
- The functions of the standard library.
- The commands of `surf` and their options.
- The format of `surf.toml` and `surf.lock`.
- The texts of the run-time errors in section 15.2 of the language spec. An app gets these texts in `on error`.

A project that builds with version 1.0 builds with each later version 1 release.

## What can change

- The generated code, the file names in a build, and the code of the runtime. These are not an API.
- The text of a message of the compiler, of `surf lint` and of `surf`.
- A new finding of `surf lint`. A CI job that fails on a finding can then fail after an update.
- A bug fix can change a result that the specs do not promise.
- A size or a speed, within the budgets of `PLAN.md`.
- A minimum version of a system or of a browser, for example Windows 10 version 1903 or the ICU of the system. Only a minor release can raise a minimum, and its release notes say so.

## Editions

A change that breaks a project waits for a new edition (ADR-0123). A project names its edition in `surf.toml`:

```toml
edition = "2026"
```

- The first edition is `2026`. `surf new` writes the newest edition.
- A project with no `edition` has the first edition, and `surf lint` gives the finding `edition`. So a project never moves to a newer edition without a change of its file.
- An edition that this `surf` does not know stops each command. The message names the editions that it knows.
- Each release of `surf` builds each edition that it knows, so an old project keeps working.
- An edition gets this support for at least two years after the release of the next edition. After that time, a release can remove the edition. Its release notes then say so.
- `surf migrate` will update a project to a new edition. This command does not exist yet, because version 1 has one edition.
- Each package keeps its edition in its own `surf.toml`. Packages of different editions work together in one project.

## Releases

- Version numbers follow Semantic Versioning.
- A release lists its changes and its new lint rules.
- A feature that is not stable has a name with `experimental`, or it stays out of the specs.