From 323d1712642c58cbc2593fcfc161cffcaf66b905 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 20 Oct 2026 16:44:21 +0800 Subject: [PATCH] docs: comline accept, and comline add asking about @unverified protocols --- docs/docs/guide/idl/protocol.md | 9 ++++++--- docs/docs/proposals/extensibility.md | 7 ++++--- docs/docs/reference/cli.md | 5 +++-- 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/docs/guide/idl/protocol.md b/docs/docs/guide/idl/protocol.md index c1bafc4..9847ea7 100755 --- a/docs/docs/guide/idl/protocol.md +++ b/docs/docs/guide/idl/protocol.md @@ -103,9 +103,12 @@ that out; the schema only says *that* something is unverified and *why*: } ``` - Until it does, the build fails, printing that entry. The list is a snapshot: - if a later version of the dependency gives up more, the build stops again - until it's accepted again. + Nobody writes this by hand: `comline add` shows what a new dependency gives + up and asks before writing it, and `comline accept billing` (or + `billing::Billing`) does the same for one already declared. Until it's + accepted, the build fails, printing the entry. The list is a snapshot: if a + later version of the dependency gives up more, the build stops again until + `comline accept` is run again. How a call travels between caller and implementation is the [runtime](../runtime/index.md)'s job, over a pluggable diff --git a/docs/docs/proposals/extensibility.md b/docs/docs/proposals/extensibility.md index f6c039a..efecf36 100644 --- a/docs/docs/proposals/extensibility.md +++ b/docs/docs/proposals/extensibility.md @@ -285,9 +285,10 @@ What decides a connection under `comline@2`: > **Built for handshakes** ([core#132](https://github.com/ComlineProject/core/pull/132)): > `@unverified`, the frozen set, its diagnostics, the version comparison and -> `accept_unverified`. Encodings without vectors and lowered bumps join when -> third-party encodings and releases exist; `comline accept` and the editor's -> quick fix follow. +> `accept_unverified`, and `comline accept` / `comline add` asking before they +> write it ([cli#89](https://github.com/ComlineProject/cli/pull/89)). +> Encodings without vectors and lowered bumps join when third-party encodings +> and releases exist; the editor's quick fix follows. Between peers, Comline gives four guarantees, each established by something specific: diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 439fd26..ecb4ab6 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -32,7 +32,8 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate | Command | What it does | |---|---| | `comline new [--git]` | Scaffold `/` with `config.idp`, `comline.toml`, `src/main.ids`, `.gitignore`. `--git` also runs `git init`. | -| `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. | +| `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 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`. | @@ -76,7 +77,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, or `reset` not confirmed (also `clap` usage errors) | +| `2` | precondition not met — not a Comline project, nothing built yet, `reset` not confirmed, or unverified protocols not accepted (also `clap` usage errors) | ## Versioning