From 8c1448ed74c896a337dbdbd3061268839267eeb7 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 15 Nov 2026 06:14:15 +0800 Subject: [PATCH 1/2] Own schemas, provenance and groups: accepted, with the open questions answered --- .../use-paths-and-groups/dependency-groups.md | 2 +- .../use-paths-and-groups/import-formatting.md | 17 +++--- .../proposals/use-paths-and-groups/index.md | 56 ++++++++----------- .../use-paths-and-groups/provenance.md | 14 +++-- .../use-paths-and-groups/relative-use.md | 24 ++++---- 5 files changed, 49 insertions(+), 64 deletions(-) diff --git a/docs/docs/proposals/use-paths-and-groups/dependency-groups.md b/docs/docs/proposals/use-paths-and-groups/dependency-groups.md index 3c00a77..77d3a78 100644 --- a/docs/docs/proposals/use-paths-and-groups/dependency-groups.md +++ b/docs/docs/proposals/use-paths-and-groups/dependency-groups.md @@ -1,6 +1,6 @@ # Dependency groups -Status: **draft** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency +Status: **accepted** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency groups](index.md) **The question.** `dependencies` in `config.idp` is a flat table, and a package with a dozen of them has no way to say diff --git a/docs/docs/proposals/use-paths-and-groups/import-formatting.md b/docs/docs/proposals/use-paths-and-groups/import-formatting.md index f5c0135..6776c2e 100644 --- a/docs/docs/proposals/use-paths-and-groups/import-formatting.md +++ b/docs/docs/proposals/use-paths-and-groups/import-formatting.md @@ -1,6 +1,6 @@ # Import formatting -Status: **draft** · decided with the user 2026-11-15, where the configuration lives open · part of [Own schemas, +Status: **accepted** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency groups](index.md) **The question.** A file's `use` lines have no set order, so each author orders them their own way, and a diff mixes @@ -38,8 +38,8 @@ use net::Client Here `logging` and `metrics` are in the group `platform`, declared first; `shared_types` is in `team`; `net` has no group. A blank line separates tiers, and separates groups inside the dependencies tier, the way the example shows. -Whether a group can also order `std`, so that, say, a group sorts before it or between the tiers, is -[an open question](index.md#open-questions); today a group orders dependencies among themselves only. +**Decided: a group orders dependencies only.** `std` is always a tier of its own, placed by `imports.order`; a group +can't sort before it or between the tiers. The formatter doesn't change what an import means: it only reorders `use` statements. @@ -59,7 +59,7 @@ an error, so a typo doesn't quietly reorder every file. ### Where the configuration lives -**Recommendation, to be confirmed: [`comline.toml`](../../reference/package/comline-toml.md), not `config.idp`.** +**Decided: [`comline.toml`](../../reference/package/comline-toml.md), not `config.idp`.** - `config.idp` is **frozen into every build and hashed**. It holds what a package *is*: its identity, what it depends on, how it is put on the wire. An import order is how a file is *written*; putting it there would make @@ -71,18 +71,15 @@ an error, so a typo doesn't quietly reorder every file. never see it. The alternative, a `format` key in `config.idp`, would be read by the same tools and would travel with a published -package. It is the user's to decide; this page is written as if `comline.toml` is chosen, and the cost of the other is a -change to where the table is read from. +package. It was not taken. ### Precedence **Decided:** the project's `comline.toml`, then the defaults. Each is applied key by key, like [`[generate]`](../../reference/package/comline-toml.md#precedence). -**Open:** whether a per-user configuration, outside the project, can override the project's. The case for it: an -author who reads imports in another order and doesn't want to change everyone's. The case against: a formatter's point -is that every author's editor produces the same file, and a per-user override means a save in one editor makes a diff -in the next. If it exists, it is the highest in the chain: defaults, the project's `[format]`, the user's. +**Decided: no per-user override.** `comline.toml` is the project's, committed beside the package, so the project's +`[format]` is what every author's editor formats with, and a save in one editor never makes a diff in the next. ## Who reads it diff --git a/docs/docs/proposals/use-paths-and-groups/index.md b/docs/docs/proposals/use-paths-and-groups/index.md index 28d101b..69cc351 100644 --- a/docs/docs/proposals/use-paths-and-groups/index.md +++ b/docs/docs/proposals/use-paths-and-groups/index.md @@ -1,6 +1,6 @@ # Own schemas, provenance and dependency groups -Status: **draft** · written 2026-11-15 · related: +Status: **accepted** · written and decided 2026-11-15 · related: [core#277](https://github.com/ComlineProject/core/issues/277) (a dependency's protocols on a connection: reach and numbers recorded in the facts) and [core#268](https://github.com/ComlineProject/core/issues/268) (IR migrations, which a change to the frozen IR has to go through) · builds on @@ -36,8 +36,8 @@ and imported in a consistent order?** ## What this proposes 1. **[Own schemas only through relative paths](relative-use.md).** Within a package, its own schemas are reached as - `package::…`, `parent::…` or `self::…`. An absolute first segment always means `std` or a dependency. Introduced - by a language edition: a warning with a quick fix now, an error in the next edition. + `package::…`, `parent::…` or `self::…`. An absolute first segment always means `std` or a dependency. A bare path + to an own schema is an error at once, with a quick fix: Comline is before 1.0, so there is no deprecation period. 2. **[Provenance, not names](provenance.md).** Each compiled schema records the package it came from: the package itself, a named dependency, or `std`. The frozen IR, the generation request and the facts carry it, so nothing infers "dependency" from a namespace's spelling. This is a frozen IR change, so it goes through the @@ -56,46 +56,35 @@ imports in a tier of their own. ## Decided -Settled with the user while drafting (2026-11-15), and written into the pages as decided: +Settled with the user (2026-11-15), while drafting and in answer to the open questions: | | Decision | |---|---| | Own schemas | reached only as `package::…`, `parent::…` or `self::…`; an absolute first segment is `std` or a dependency | | The word for one level up | `parent`, as it is; no `super` synonym | -| Rollout | a language edition: a warning with a language-server quick fix (rewriting to `package::…`) in the current edition, an error in the next | +| Rollout | an error at once, with a language-server quick fix and `comline fix` (rewriting to `package::…`); no edition and no deprecation period, since Comline is before 1.0 | | Reserved dependency names | `std`, `package`, `parent`, `self` | | Provenance | recorded per compiled schema (the package, a named dependency, or `std`) in the frozen IR, the generation request and the facts; one canonical namespace form in requests and facts | -| IR format | a bump under the IR migrations framework | +| IR format | a bump under the IR migrations framework; it can ride with format 4 or come after it as format 5, whichever is ready | | Groups | an optional `group = ""` field on each dependency entry; the table stays flat and names unique; never in a `use` path | | Rejected group shapes | nested group tables, and a separate `dependency_groups` list | | Groups and hashes | excluded from the frozen config's hash, from dependency pins and from compat and config diffs | | CLI | `comline deps add` and `comline deps pin` take `--group` | | Import order | `std`, then the package's own, then dependencies: groups in first-declared order, then ungrouped dependencies; alphabetical within a tier | -| Configuration | a `[format]` table, for example `imports.order = ["std", "package", "dependencies"]`; the project's configuration, then the defaults; read by the language server's formatter and any `comline fmt` | +| Configuration | a `[format]` table in `comline.toml` (not `config.idp`), for example `imports.order = ["std", "package", "dependencies"]`; the project's configuration, then the defaults, with no per-user override; read by the language server's formatter and any `comline fmt` | +| Groups and `std` | a group orders dependencies only; `std` is always a tier of its own | +| The shadowing guard | stays as it is: a package's own schema named like a dependency, or `std`, is still refused, which also keeps two schemas from compiling to one namespace and one generated file | ## Open questions -1. **Provenance's IR format.** Does provenance ride with format 4 (the first migration step, the - [granular `@unverified`](../shared-vocabulary/granular-unverified.md) chains of - [core#222](https://github.com/ComlineProject/core/issues/222)), or come right after it as format 5? See - [the IR format](provenance.md#which-format). -2. **Where `[format]` lives.** The recommendation is `comline.toml`, the tooling configuration, and not `config.idp`, - which is frozen into every build and hashed. Left open for the user to confirm. See - [where it lives](import-formatting.md#where-the-configuration-lives). -3. **A per-user override.** Whether a per-user configuration (outside the project) can override the project's - `[format]`, or the project's is always what formats. See - [precedence](import-formatting.md#precedence). -4. **Groups and `std`.** Whether a group can also order `std`: today a group orders dependencies among themselves - only, and `std` is a tier of its own. See [how groups are ordered](import-formatting.md#the-default-order). -5. **The edition for the error.** Which edition makes a bare path to a package's own schema an error: the next one, - 2, which [dependency protocols](../dependency-protocols/index.md) also proposes for its new defaults, or a - later one. See [the rollout of the rule](relative-use.md#rollout-by-edition). -6. **Equal namespaces after provenance** (raised while drafting; not one of the questions settled with the user). Once - provenance tells a package's schema from a dependency's, the guard on a package's own schema named like a - dependency has nothing left to protect, but two schemas can still have the same compiled namespace (an own - `greeting/hello.ids` and the dependency's `hello`, as `greeting::hello`) and write the same generated file. Does the - guard stay, narrowed to equal namespaces, or do a dependency's schemas get their own output prefix? See - [what the guard becomes](provenance.md#what-the-guard-becomes). +None. The six left open in the draft were answered on 2026-11-15 and are in the table above: + +1. **Provenance's IR format:** either; it rides with format 4 or comes after it as format 5, whichever is ready. +2. **Where `[format]` lives:** `comline.toml`. +3. **A per-user override:** none. With `[format]` in `comline.toml`, the project's configuration is what formats. +4. **Groups and `std`:** a group doesn't order `std`. +5. **The edition for the error:** no edition. It is an error at once, since Comline is before 1.0. +6. **Equal namespaces:** the shadowing guard stays. ## Rollout @@ -104,14 +93,13 @@ turns the accepted proposal into issues. 1. **specification: conformance cases first.** New compiler cases in `compiler/src`, regenerated into `compiler/cases` by `specs/check.sh`, so every implementation reproduces them: a bare path to a package's own schema (the - warning in the current edition, the error in the next, the `package::` form clean); a package with a dependency and + error, and the `package::` form clean); a package with a dependency and an own schema of the same first word; reserved dependency names; a `group` on an entry, and the same package regrouped (the same outcome). A new kind of case for formatting: a schema's text, the configuration, and the text the formatter must produce, for the default order, a custom `imports.order`, and groups. New catalog entries for the diagnostic codes, per the [shared vocabulary](../shared-vocabulary/index.md). 2. **core: the rule.** The resolver reads an absolute first segment as `std` or a dependency only; a bare path that - would have reached the package's own schema is the deprecation warning, with the fix attached, in the current - edition, and the error in the edition chosen above; `comline fix` applies it. The reserved names stay as they are + would have reached the package's own schema is an error, with the fix attached; `comline fix` applies it. The reserved names stay as they are (`reserved_dependency_name` already refuses `std`, `package`, `parent` and `self`). 3. **core: provenance and the IR format.** Each compiled schema records its provenance; the frozen types, the migration step and its fixtures, and the format document, in one pull request as the @@ -125,13 +113,13 @@ turns the accepted proposal into issues. until the generators read provenance, then goes. 6. **CLI.** `comline deps add --group` and `comline deps pin --group`; `deps list` shows groups; `comline fix` applies the rewrite; `comline fmt`, if and when it exists, reads `[format]`. -7. **language server.** The deprecation warning with its quick fix to `package::…`; the formatter's import order; +7. **language server.** The error with its quick fix to `package::…`; the formatter's import order; `[format]` read from `comline.toml`; completion and hover for `group`. 8. **docs.** The [Imports](../../guides/idl/use.md) guide (own schemas, the relative forms, what an absolute path means), [Packages & dependencies](../../guides/packages/index.md#dependencies) (groups, `--group`), the [`config.idp`](../../reference/package/idp.md) and [`comline.toml`](../../reference/package/comline-toml.md) - references (`group`, `[format]`, and the JSON Schema `scripts/sync-comline-toml-schema.py` writes), - [Editions](../../reference/versioning.md#editions), the [CLI reference](../../reference/tools/cli/index.md), and this + references (`group`, `[format]`, and the JSON Schema `scripts/sync-comline-toml-schema.py` writes), the + [CLI reference](../../reference/tools/cli/index.md), and this proposal marked accepted. ## Related diff --git a/docs/docs/proposals/use-paths-and-groups/provenance.md b/docs/docs/proposals/use-paths-and-groups/provenance.md index 9bcdfbc..b1dfddd 100644 --- a/docs/docs/proposals/use-paths-and-groups/provenance.md +++ b/docs/docs/proposals/use-paths-and-groups/provenance.md @@ -1,6 +1,6 @@ # Provenance, not names -Status: **draft** · decided with the user 2026-11-15, the IR format open · part of [Own schemas, provenance and +Status: **accepted** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency groups](index.md) · needs an IR format bump under [core#268](https://github.com/ComlineProject/core/issues/268) **The question.** Whether a compiled schema is the package's own, a dependency's or `std`'s decides what is done with @@ -77,7 +77,7 @@ and is the first real client of the system. | **Hashes** | moved once: every object's address, a dependency pin and `schema_ir_hash` change at the same bump | moved twice | | **Timing** | provenance waits for #222, or #222 waits for it | independent; provenance can ship after 4, and the rest of this proposal doesn't wait on the IR | -Open: [which of the two](index.md#open-questions). Whichever is chosen, the 1.0 reset applies: stores in today's +**Decided: either.** It rides with format 4 if both are ready together, and is format 5 otherwise. Whichever it is, the 1.0 reset applies: stores in today's formats aren't migrated, and only the format that exists at 1.0 carries a guaranteed path. ## What the guard becomes @@ -88,6 +88,10 @@ tool. They can still *land on the same compiled namespace*: an own `src/greeting/hello.ids` and the dependency's `hello.ids` are both `greeting::hello`, and two files cannot be generated at one path -(`{{language}}/{{namespace}}.{{ext}}`). So the guard doesn't simply go. [Open](index.md#open-questions): whether it is -narrowed to **equal namespaces** (refused as a collision, with its own message, and no longer about classification), -or a dependency's schemas get their own prefix in the output, so that none can collide. +(`{{language}}/{{namespace}}.{{ext}}`). So the guard doesn't simply go. + +**Decided: the guard stays as it is.** A package's own schema named like a dependency, or `std`, is still refused. It +no longer protects classification, which provenance does, but it keeps every compiled namespace, and every generated +file, unique, with the message it has today. Narrowing it to equal namespaces, or prefixing a dependency's output, was +considered and not taken: either lets a package's own `greeting` sit beside a dependency `greeting`, which a reader of +the generated code would confuse as easily as the tools once did. diff --git a/docs/docs/proposals/use-paths-and-groups/relative-use.md b/docs/docs/proposals/use-paths-and-groups/relative-use.md index b3c09f4..15b8763 100644 --- a/docs/docs/proposals/use-paths-and-groups/relative-use.md +++ b/docs/docs/proposals/use-paths-and-groups/relative-use.md @@ -1,6 +1,6 @@ # Own schemas only through relative paths -Status: **draft** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency +Status: **accepted** · decided with the user 2026-11-15 · part of [Own schemas, provenance and dependency groups](index.md) **The question.** In `use greeting::hello::Greeting`, is `greeting` the package's own `src/greeting.ids`, a dependency @@ -71,7 +71,7 @@ Rust spells it `super`. One word is kept because: ## What the editor and the fix do -A bare path that reaches the package's own schema is a deprecation (below). The language server attaches a **quick fix** that +A bare path that reaches the package's own schema is an error (below). The language server attaches a **quick fix** that rewrites it to the `package::…` form. `package::` is chosen over the shortest relative form because it is the same wherever the file sits: moving a schema to another directory doesn't change what its imports say. The qualified references the import brought in, written with the old spelling, are rewritten with it. `comline fix` applies the @@ -79,21 +79,17 @@ same rewrite to every file. A path that matches nothing is the error it is today ([When nothing matches](../../guides/idl/use.md#when-nothing-matches)), with one addition: a bare path whose first segment is neither a -dependency nor `std`, but the name of one of the package's own schemas, is the deprecation, not "no schema matches". +dependency nor `std`, but the name of one of the package's own schemas, is this error, with the fix, not "no schema matches". -## Rollout by edition +## Rollout -This is the kind of change [editions](../../reference/versioning.md#editions) are for: a form that was valid is no -longer, and the package keeps the old behaviour until it moves. +**Decided: an error at once.** Comline is before 1.0, so the change doesn't go through an +[edition](../../reference/versioning.md#editions) or a deprecation period. -1. **In the current edition: a warning.** A bare path to the package's own schema warns, in the `deprecation::` family, - on every use, with the fix attached, and the editor shows it struck through like any deprecated word. Builds pass. -2. **In the next edition: an error.** The same use is `edition::removed`, and `comline fix --edition N` rewrites it - with the rest of what the edition moves. -3. **Dependencies are unaffected.** A dependency's compiled schemas are frozen with their `use`s already resolved, and - a package compiled under any edition can depend on one compiled under another. - -Which edition number the error lands in is [an open question](index.md#open-questions). +1. **A bare path to the package's own schema is an error**, with the fix attached, and `comline fix` rewrites every + file at once. +2. **Dependencies are unaffected.** A dependency's compiled schemas are frozen with their `use`s already resolved, + so a package can depend on one written before the change. ## What stays as it is From 41403f52eb6dcaefeaabc79fd2f5ee6b5ceba6d6 Mon Sep 17 00:00:00 2001 From: Kinflou Date: Sun, 15 Nov 2026 06:14:30 +0800 Subject: [PATCH 2/2] Proposals index: own schemas, provenance and groups accepted --- docs/docs/proposals/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/docs/proposals/index.md b/docs/docs/proposals/index.md index d8661b9..0137e7f 100755 --- a/docs/docs/proposals/index.md +++ b/docs/docs/proposals/index.md @@ -159,17 +159,16 @@ Seven parts, read in order: [the formats](ir-migrations/formats.md), How a `use` path says where a schema comes from, and how a package's dependencies are organised. A package's own schemas are reached only through `package::`, -`parent::` or `self::` (a warning with a quick fix now, an error in the next -edition), so an absolute first segment always means `std` or a dependency; each +`parent::` or `self::` (an error at once, with a quick fix), so an absolute first segment always means `std` or a dependency; each compiled schema records its provenance (the package, a named dependency, or `std`) instead of tools inferring it from the namespace's spelling, which is an IR format change; dependencies take an optional `group` that is presentation only and moves no hash; and a file's imports have a default order (`std`, the -package's own, dependencies by group) configurable in a `[format]` table. Four +package's own, dependencies by group) configurable in `comline.toml`'s `[format]` table. Four parts: [relative paths](use-paths-and-groups/relative-use.md), [provenance](use-paths-and-groups/provenance.md), [dependency groups](use-paths-and-groups/dependency-groups.md) and -[import formatting](use-paths-and-groups/import-formatting.md). *draft; related +[import formatting](use-paths-and-groups/import-formatting.md). *accepted 2026-11-15; related to [core#277](https://github.com/ComlineProject/core/issues/277) and [core#268](https://github.com/ComlineProject/core/issues/268).*