diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 2ceab48..15ffa0f 100755 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -69,9 +69,11 @@ struct Greeting { comline build ``` -This compiles and validates the schemas, then freezes the result as version -`0.0.1` in a content-addressable store under `.comline/`. Later builds -[bump the version automatically](reference/versioning.md) by the largest change +This compiles and validates the schemas, then freezes the result as a build, +`0.1.0-dev.1`, in a content-addressable store under `.comline/`. Builds lead up +to a release; when you want a version consumers see, run `comline release` +(the first is `0.1.0`), and later releases +[take the bump automatically](reference/versioning.md) from the largest change since the last one. Validate without freezing — safe for editors and pre-commit hooks: diff --git a/docs/docs/guide/index.md b/docs/docs/guide/index.md index 905cd5e..319dcb1 100644 --- a/docs/docs/guide/index.md +++ b/docs/docs/guide/index.md @@ -27,8 +27,9 @@ and then **freezes** the result: the schema becomes a set of immutable [Intermed written into a Content Addressable Store, [`.comline/`](ir/cas.md), as a new commit in an append-only chain. -The package version bumps automatically on each build, by the largest change -since the last one — see [Versioning rules](../reference/versioning.md). +Each build is recorded under a pre-release version leading to the next release; +`comline release` creates that version, bumped by the largest change since the +last one — see [Versioning rules](../reference/versioning.md). ## 3. [Generate code](codegen/generating-code.md) diff --git a/docs/docs/proposals/schema-compatibility.md b/docs/docs/proposals/schema-compatibility.md index 0ea8304..2835088 100644 --- a/docs/docs/proposals/schema-compatibility.md +++ b/docs/docs/proposals/schema-compatibility.md @@ -407,6 +407,12 @@ Cargo's convention: ## Builds and releases +> **Built** ([core#133](https://github.com/ComlineProject/core/pull/133), +> [cli#90](https://github.com/ComlineProject/cli/pull/90)): builds carry +> `X.Y.Z-dev.N`, the release they lead to; `comline release` with `--raise` +> and `1.0`. Not yet: `--lower` (how consumers accept a package-wide loss of +> version honesty is open) and assigning `@id`s at 1.0 (core#127). + Decided 2026-10-20. Today every build that changes something creates a commit with a new version, so five edit-and-build cycles make five patch versions, and a commit records neither the computed bump nor a reason. Instead, **builds and diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index ecb4ab6..6c5f2c8 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -35,8 +35,9 @@ 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`](../guide/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`](../guide/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 build [--release] [--watch]` | Compile, validate, freeze a new immutable version into `.comline/`; print the changelog and the bump. `--release` is currently a no-op. | +| `comline build [--release] [--watch]` | 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. `--release` is currently a no-op (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. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. | +| `comline release [1.0] [--raise --reason ] [--yes]` | Build, then release: create the version from the highest bump since the last release ([builds and releases](versioning.md#builds-and-releases)). `--raise patch\|minor\|major` goes higher, with a `--reason` recorded with the release; it never lowers. `1.0` makes a `0.x` package stable after showing what that commits to (its protocols, and what's worth settling first). Raising to major and `1.0` ask on a terminal; without one they refuse (exit `2`) unless `--yes` (`-y`). | | `comline diff []` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`` default). | | `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. | | `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.0.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. | @@ -77,7 +78,7 @@ everything else goes to stderr. |---|---| | `0` | success | | `1` | ran but failed — invalid schema, unresolved `diff` argument, generator or filesystem error | -| `2` | precondition not met — not a Comline project, nothing built yet, `reset` not confirmed, or unverified protocols not accepted (also `clap` usage errors) | +| `2` | precondition not met — not a Comline project, nothing built yet, `reset` / a release not confirmed, or unverified protocols not accepted (also `clap` usage errors) | ## Versioning diff --git a/docs/docs/reference/congregation/comline-toml.md b/docs/docs/reference/congregation/comline-toml.md index 16e248a..31f7868 100644 --- a/docs/docs/reference/congregation/comline-toml.md +++ b/docs/docs/reference/congregation/comline-toml.md @@ -155,8 +155,8 @@ you want fewer. | Value | Effect | |---|---| | `"latest"` (default) | The working tree only. No `.comline/` read. `{{package_version}}` is the last committed version (empty if never built). | -| `"all"` | Every committed version in the project's history. | -| `["0.3.0", "0.4.0"]` | Exactly those versions (version strings or commit hashes). | +| `"all"` | Every release in the project's history (not the builds between them). | +| `["0.3.0", "0.4.0"]` | Exactly those versions: releases, builds (`0.3.0-dev.2`) or commit hashes. | Anything but `"latest"` reads the content-addressable store, so the project must have been built at least once. Selecting more than one version **requires** diff --git a/docs/docs/reference/versioning.md b/docs/docs/reference/versioning.md index fca978d..b4edd1a 100644 --- a/docs/docs/reference/versioning.md +++ b/docs/docs/reference/versioning.md @@ -1,16 +1,46 @@ # Versioning rules -Comline versions a package **automatically**. Every `comline build` compares the -new schemas against the previous frozen version and bumps the package version by -the largest change it finds. You never write a version by hand — there is no -version field in the manifest; it comes from the -[content-addressable store](../guide/ir/cas.md). - -Versions follow [SemVer](https://semver.org/). The first build is `0.0.1`. A -build that changes nothing keeps the version and adds no commit. A change that -takes no bump, such as to `code_generation`, adds a commit at the same version. +Comline versions a package **automatically**: the version comes from what +changed, not from a field you write. There is no version in the manifest; it +lives in the [content-addressable store](../guide/ir/cas.md). + +## Builds and releases + +**Builds** record history; **releases** are the versions consumers see. + +- **`comline build`** compares the schemas against the last *release* and + records a build under a pre-release version: the release it leads to, plus + a count of builds since the last release. After `0.1.0`, a build adding a + feature is `0.1.1-dev.1`; a breaking change in the next build makes it + `0.2.0-dev.2`. The build reports the next release and what calls for it. + Changes that cancel out between releases cancel out in the bump too. A build + that changes nothing adds no commit. +- **`comline release`** builds, then creates the version from the **highest + bump since the last release**. It records the computed bump, the applied + one and any reason with the release. The first release is `0.1.0`. +- **`--raise --reason "…"`** releases a higher bump than the schema + shows, for a behaviour change it can't express. A raise the changes already + reach is recorded as covered, its reason kept as a note. The bump is never + lowered. +- **`comline release 1.0`** makes a `0.x` package stable, after saying what + that commits to. + `comline diff ` runs the same comparison between any two stored -versions on demand. +versions, builds or releases, on demand. + +## Before 1.0 + +Versions follow [SemVer](https://semver.org/), with Cargo's convention before +1.0: while the version is `0.x`, the minor plays the part of the major. + +| Change | `0.x` | `1.0` and later | +|---|---|---| +| breaking | `0.3.2` → `0.4.0` | `1.3.2` → `2.0.0` | +| new feature | `0.3.2` → `0.3.3` | `1.3.2` → `1.4.0` | +| modification | `0.3.2` → `0.3.3` | `1.3.2` → `1.3.3` | + +Histories from before builds and releases were separate keep their versions, +which all count as releases; from a `0.0.z` release the next one is `0.1.0`. ## Schema changes @@ -59,7 +89,7 @@ git-inspired, no branches, never rewritten — so any past version stays reproducible. Nothing else holds this history — there is no `publish` yet — so losing -`.comline/` means the next build starts over at `0.0.1`, with no undo. +`.comline/` means the next build starts over at `0.1.0-dev.1`, with no undo. `comline clean` leaves it alone; only **`comline reset`** deletes it, behind a typed confirmation (or `--force`). See [the `clean` / `reset` split](../design/ir-generation.md#the-clean-reset-split).