diff --git a/docs/docs/conduct/phases.md b/docs/docs/conduct/phases.md index 077cf46..a6ec00f 100644 --- a/docs/docs/conduct/phases.md +++ b/docs/docs/conduct/phases.md @@ -47,6 +47,11 @@ Until the 1.0 announcement. available, in at least one minor release before the major that removes it. The changelog says so both times. - A wire format's bytes never change again. A change is a new `@N`. +- A change to the schema language that would break schemas already written + ships in a new [edition](../reference/versioning.md#editions). A package + keeps its edition until it moves (`comline fix --edition N`), and a word + is deprecated, with a warning and a fix, in an edition before the one + that removes it. - The C ABI's structs are frozen within a major. Status codes and flags are append-only. - Packages go to registries (npm, crates.io, …) under ComlineProject-owned diff --git a/docs/docs/reference/congregation/config-id.md b/docs/docs/reference/congregation/config-id.md index fae7d23..009b139 100644 --- a/docs/docs/reference/congregation/config-id.md +++ b/docs/docs/reference/congregation/config-id.md @@ -55,7 +55,7 @@ settings = { |---|---|---| | `congregation` | the package's name | Renaming it is fine: `id` is what identifies the package. | | `id` | 32 lowercase hex digits, random | The package's identity. `comline new` writes it, and `comline build` adds one to a package without it. A copy of the package must change it. Changing it is a major change. See [Compatibility facts](../versioning.md#compatibility-facts). | -| `specification_version` | an integer, `1` | The edition of the schema language the files are written in. | +| `specification_version` | an integer: `1`, the only edition so far | **Required.** The [edition](../versioning.md#editions) of the schema language the files are written in. Leaving it out, or naming an edition this Comline doesn't know, is an error with a fix that `comline fix` applies. | | `code_generation` | `{ languages = { # = {} ... } }` | The languages the package can be generated as, each with the oldest toolchain its output must build on. `comline build` proves each one. See [Language versions](../../guides/codegen/generating-code.md#language-versions). | | `wire` | `{ format = "..." framing = "..." }` | The format and framing every protocol uses unless it says otherwise. Defaults: `packed@1` and `datagram@3`. See [Wire defaults](../../guides/packages/index.md#wire-defaults). | | `handshake` | `"comline@1"`, `"comline@2"` or `"none"`, or `{ name = "comline@2" scope = "package" }` to set [its parameters](../wire/handshakes/index.md#parameters) | What a protocol with no `@handshake` runs before its first call. Default `comline@2`, or `comline@1` in a package whose protocols aren't all on `datagram@3`. See [Giving up a guarantee](../../guides/idl/protocol.md#giving-up-a-guarantee). | diff --git a/docs/docs/reference/tools/cli.md b/docs/docs/reference/tools/cli.md index 439e593..808de36 100644 --- a/docs/docs/reference/tools/cli.md +++ b/docs/docs/reference/tools/cli.md @@ -35,6 +35,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate | `comline add ` / `comline add --git --commit --version ` | Add a dependency to `config.idp`, imported as `use ::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. If it has [`@unverified`](../../guides/idl/protocol.md#giving-up-a-guarantee) protocols, what each gives up is shown and, on a terminal, you're asked to accept it (default no); without a terminal it refuses (exit `2`) unless `--accept-unverified`. | | `comline accept [::] [--yes]` | Accept what a dependency's [`@unverified`](../../guides/idl/protocol.md#giving-up-a-guarantee) protocols give up: shows each one's given-up guarantees and reason, then writes `accept_unverified` into its `config.idp` entry, leaving the rest as written. Only protocols not already accepted for exactly their current set are asked about. On a terminal you're asked (default no); without one it refuses (exit `2`) unless `--yes` (`-y`). | | `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. | +| `comline fix [--edition ] [--dry-run]` | Apply the fixes Comline attaches to what it reports about the language: add a missing `specification_version` to `config.idp`, and replace each use of a keyword or type the package's [edition](../versioning.md#editions) deprecates or removes, when it has a replacement; uses without one are listed to change by hand. `--edition ` checks and fixes the schemas under edition `n` and moves `config.idp` to it, unless a removed word without a replacement is left (exit `1`). Moving back is refused. `--dry-run` lists the fixes and writes nothing. | | `comline inspect [--json]` | Show each protocol's format, framing and handshake, with their parameters and where each came from (`@framing`/`@handshake`, `config.idp`, or core's default), then every guarantee, held or given up, with the cause, the `@unverified` reason and whether it's accepted. No `.comline/` write. `--json` prints the same as JSON. See [comline inspect](cli/inspect.md). | | `comline build [--watch] [--reconcile ]` | Compile, validate, and freeze a build into `.comline/` under a pre-release version (`0.3.0-dev.2`); print the changelog, the bump, and the next release. `--reconcile ` puts a head dropped in a Git merge back beside the current one, so the build [reconciles the two](../../guides/ir/cas.md); the output says when a build reconciled. A project with [unbounded strings or lists](../../guides/idl/types.md#every-string-and-list-has-a-maximum) fails with each position listed and the `settings` block to add; on a terminal, the build offers to write it with maxima you type in. Before freezing, proves every declared `code_generation.languages` target against this binary's generators ([Language versions](../../guides/codegen/generating-code.md#language-versions)). Releasing is `comline release`. | | `comline generate [--target ] [--out ] [--layout ] [--mode ] [--external-std] [--no-external-std] [--validate-on-decode ] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Wire numbers and the rest of the [facts](../versioning.md#number) come from the last build when nothing changed since, else are worked out as the next build would assign them, provisional until a release; no build is needed. Location/layout from [`comline.toml`](../congregation/comline-toml.md); targets from there or `config.idp`. A target can use an [external generator](../../developer/extending/generators.md) (`generator = ""`) and map [encodings](../../developer/extending/encodings.md#5-map-it-to-a-type). | diff --git a/docs/docs/reference/versioning.md b/docs/docs/reference/versioning.md index 17c2dc7..db0f7ff 100644 --- a/docs/docs/reference/versioning.md +++ b/docs/docs/reference/versioning.md @@ -184,7 +184,7 @@ version — but only the parts that describe the schema API: |---|---|---| | `wire.format`, `wire.framing` | changed | **major** | | `id` | changed | **major**: it names another package. Adding one where there was none is no change | -| `SpecificationVersion` | changed | **major** | +| `SpecificationVersion` | changed | **none** by itself: the compiled schema doesn't depend on the [edition](#editions), so what a move changes in it carries its own bump | | `Dependency` | added, removed, or version changed | **patch** on its own: what the package uses of it is compared by reach (above) | | `CodeGeneration` | added / removed / `lang_version` changed | **none** — recorded, never diffed. It is a tooling-capability list, orthogonal to the wire format. | | `PublishRegistry` | any | **none** — publish metadata | @@ -193,6 +193,33 @@ version — but only the parts that describe the schema API: `comline build` and `comline diff` print every change: the package's own, each dependency's within reach, the config's, and the bump they call for. +## Editions + +A package's `config.idp` names the edition of the schema language its files +are written in: `specification_version = 1`. Edition 1 is the language at +1.0, and the only edition so far. + +- **Every package names one.** Leaving it out, or naming an edition this + Comline doesn't know, is an error (`edition::missing`, `edition::unknown`) + pointing at the line, with a fix. `comline new` writes the newest. +- **A change that would break schemas already written ships in a new + edition:** a keyword or type renamed or removed, a default changed. A + package keeps its edition's behaviour until it moves. +- **Editions mix.** Each package is compiled under its own edition, and the + compiled schema doesn't depend on it, so a package depends on packages + written in any edition, and its dependents never see which one it uses. +- **Deprecation comes first.** A word an edition deprecates is a warning, + `deprecation::`, on every use, with a fix when it has a replacement; + the editor shows it struck through. An edition that removes it makes the + use an error, `edition::removed`. +- **Moving is `comline fix --edition N`:** it fixes what edition N deprecates + or removes, and moves `config.idp` to N. Uses with no replacement are + listed to change by hand, and the package stays put until they're gone. + `comline fix` alone applies the fixes for the package's own edition. +- **No bump by itself.** Moving to another edition changes the version only + through what it changes in the compiled schema, such as a different + default framing. + ## Compatibility facts Each version provides what a compatibility-checking handshake