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
7 changes: 3 additions & 4 deletions docs/docs/proposals/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).*

Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down
17 changes: 7 additions & 10 deletions docs/docs/proposals/use-paths-and-groups/import-formatting.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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

Expand Down
56 changes: 22 additions & 34 deletions docs/docs/proposals/use-paths-and-groups/index.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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 = "<name>"` 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

Expand All @@ -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
Expand All @@ -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
Expand Down
14 changes: 9 additions & 5 deletions docs/docs/proposals/use-paths-and-groups/provenance.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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.
24 changes: 10 additions & 14 deletions docs/docs/proposals/use-paths-and-groups/relative-use.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -71,29 +71,25 @@ 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
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

Expand Down
Loading