Add clet implementation specification and release runbook#1
Merged
Conversation
Drops the v0.4 implementation spec into the repo as the source of truth for clet's design, companion to the PR/FAQ in gui-cs/Terminal.Gui#5155. Normalizes clipboard auto-link artifacts (e.g. [README.md](http://README.md) -> README.md) that crept in during paste.
Tightens the contract that AI agents will pin to once schemaVersion 1 ships,
removes a contradiction between the press release and the new spec, and
drafts the release-rollback runbook the spec was promising in §8.
specs/clet-spec.md:
§3.1: drop the "IValue<T>.Value still readable on cancel" parenthetical;
clet's wire contract no longer depends on TG's #5157 disposition
decision.
§4.3: drop the wire-format `type` field (CLR type names like
`System.String` shouldn't leak into a cross-language envelope);
result types are advertised once per alias by `clet list --json`.
Add normative envelopes including the cancel form
{"schemaVersion":1,"status":"cancelled"}.
§4.3.1 (new): schemaVersion bump policy — v1 covers all of clet 1.x,
v2 only at clet 2.0.0 with one minor-release parallel period.
§4.3.2 (new): per-clet `value` shapes table; resolves the open question
about the `range` clet's shape ({"low":<T>,"high":<T>}).
§5.3: process-level smoke gate uses gui-cs/TUIcast (PTY-based
keystroke injection, deterministic-script mode), not stdin
redirection — TG drivers don't read keystrokes from stdin.
Asciinema artifact uploaded on failure.
§6.1: update CletJsonOutput tests to reflect dropped `type`.
§6.2: in-process integration tests use TG's InputInjection (the
right tool when you have an IApplication instance, not a subprocess).
§6.3: process-level smoke tests use TUIcast — same driver as §5.3 so a
green CI run is byte-equivalent evidence the release gate will pass.
§8: risk row references the new runbook; add a new row for "first real
repository_dispatch release fails mid-publish."
§9: drop resolved open question #4 (range shape); trim #6 to just the
upstream PR/FAQ since this repo's README is now consistent.
README.md:
Line 70: input-clet envelope example dropped `type` field.
Line 80: same fix in the FAQ JSON example.
Line 148: rewrote the "why TG owns this" answer to match the spec —
clet is one binary in its own repo, abstractions internal to v1.0,
Clet.Abstractions is a v2 maybe.
docs/runbooks/release-rollback.md (new, draft):
Per-channel withdrawal procedures for Homebrew tap, WinGet, and NuGet.
Triage decision tree, fast-follow patch flow, post-incident loop, and
the things we explicitly will not do (no force-push, no NuGet
hard-delete, no auto-revert, no smoke-gate bypass). Open questions
inline for v0.9 resolution.
Lock in the in-process vs process-level split so it survives contact with future maintainers. Five additions, all in §6: §6.0 (new): explicit test tiering — when each layer runs (inner loop, PR CI, nightly, release gate). Names the two harnesses (InputInjection, TUIcast), what each one answers, and why we don't merge them. Calls out that #6.6 already covers the AOT-divergence worry so §6.2 doesn't need to route through TUIcast. §6.2: integration tests reuse TG's snapshot infrastructure (and #5156's golden-file work), do not fork it. §6.3: - Scope guardrail: one happy path per clet plus the cancellation case. Bug repros and option-matrix coverage stay in §6.2. Without this the release gate accretes integration cases and hits 30 minutes. - Scripts as data: per-clet keystroke scripts live in tests/Clet.SmokeTests/scripts/<alias>.txt, not embedded in C# string literals. Contributors add smoke cases by editing data; any script is re-runnable locally without rebuilding the test project. - Asciinema retention: failed runs upload .cast as workflow artifact; successful runs discard. GitHub Actions default 90-day retention.
17 tasks
8 tasks
14 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive specification and operational documentation for the
cletproject, establishing the design, architecture, testing strategy, and release procedures for the new Terminal.Gui input/viewer clet system.Changes
specs/clet-spec.md(831 lines): Complete implementation specification covering:gui-cs/cletrepo structure and project layoutdocs/runbooks/release-rollback.md(111 lines): Operational runbook for handling bad releases:README.md(minor): Updated to reflect that clet abstractions are internal-to-binary in v1.0 (not a published NuGet), aligning with the spec's deferred v2 scope.Notable Details
repository_dispatchfrom Terminal.Gui releases, with smoke-test gate (§5.3) that must pass before any channel publishThis specification is the design document for the entire clet v1.0 effort and serves as the source of truth for scope, architecture, and release procedures.
https://claude.ai/code/session_017Qy1g5Yrao4RZcWQR7puQg