Skip to content

1.0 has no written definition; make it three decisions written down, not a feature list #256

Description

@vyncint

Today — 0.9.0 is the twelfth release in four weeks, and nothing says what 1.0 would mean. Measured against 0.9.0: #[non_exhaustive] is on every public enum, cargo-semver-checks runs in release.yml, and the README says Windows is "planned" while two closed milestones called it "out of scope as inherent". Three questions decide the shape of the API and none has a written answer: whether termlens runs on Windows (#149), whether the emulator backend stays vt100 (#150), and whether history carries styles (#146).

Why it is worth fixing — consumers pin 0.x, and every minor is a chance to break them; a 1.0 that means "we stopped changing things" has to know what is settled. Each of the three questions is one where the honest answer might be no — "screen assertions on Windows, frame assertions not", "the backend stays, the shadow parser stays", "history stays text" — and an honest no written down is a 1.0 that means something, while a feature list is a 1.0 that never arrives.

Fix — a short docs/STABILITY.md (name open) that defines 1.0 as three decisions written down with measurements, not three features shipped:

  1. Windows — the outcome of Unix only: what Windows support would actually take #149's investigation into what ConPTY does to the byte stream, and therefore which of wait_until, wait_frame and the query responder are supported there. The README's "planned" is replaced by whatever the document says.
  2. Backend — the outcome of Three SGR attributes cost a second full parse: the shadow parser and what would retire it #150's comparison of vt100, wezterm-term and alacritty_terminal against the Emulator trait: coverage of SGR attributes, grapheme handling, mouse-mode fidelity, dependency weight, MSRV, maintenance cadence. The decision is to swap or to keep the shadow parser on purpose.
  3. Styled history — the shape decision in A styled row loses every style when it scrolls off — and the masked-password assertion with it #146: what a history row is, what it costs per snapshot, and whether the masked-password assertion survives a scroll.

The same document names which pub items are covered by the 1.0 promise and which stay behind features (decode, serde, regex) or are documented as heuristics (wait_idle, wait_stable). Each of the three decisions is maintainer work with a measurement in it — the opposite of a good-first-issue — and the document is what lets contributors see why.

Done when — the document exists, is linked from the README's contributing section, and names the three decisions with the issue each is decided in; #146, #149 and #150 link back to it; and docs/RELEASING.md says a 1.0 tag requires all three sections to be filled in.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationquestionFurther information is requested

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions