Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/docs/conduct/phases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/reference/congregation/config-id.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 = { <language>#<version> = {} ... } }` | 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). |
Expand Down
1 change: 1 addition & 0 deletions docs/docs/reference/tools/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate
| `comline add <name> <dir>` / `comline add <name> --git <uri> --commit <sha> --version <v>` | Add a dependency to `config.idp`, imported as `use <name>::…`: 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 <name>[::<protocol>] [--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 <n>] [--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 <n>` 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 <hash>]` | 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 <hash>` 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 <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--external-std] [--no-external-std] [--validate-on-decode <when>] [--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 = "<path>"`) and map [encodings](../../developer/extending/encodings.md#5-map-it-to-a-type). |
Expand Down
29 changes: 28 additions & 1 deletion docs/docs/reference/versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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::<word>`, 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
Expand Down
Loading