Skip to content

Add OCaml workspace interruption guidance after the release - #294

Merged
tony merged 3 commits into
mainfrom
followup/ocaml-workspace-docs-3935b3a
Nov 11, 2026
Merged

tony merged 3 commits into
mainfrom
followup/ocaml-workspace-docs-3935b3a

Conversation

@tony

@tony tony commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add a complete workspace interruption guide and task-page navigation.
  • Refresh API contracts, package catalogs, example provenance, guide bodies and source citations.
  • Preserve partial workspace qualification and unresolved streaming failures.

Applications need to retain the execution journal outside cancellation and client cleanup, inspect reported creations, and check compensation without assuming program effects were undone. The guide uses the installed, independently exercised native example. The updated backend contracts state the compensation default and the journal's in-memory lifetime.

Integration

This draft targets main after the combined new-port release in #291. API and source caches follow the published native source, with separate exporter provenance. The deferred constructor-parser change remains a separate follow-up. The no-preview label holds preview publication.

Test plan

  • Real selected-source export and isolated rejection controls, including unchanged-output assertions.
  • OCaml and Clojure adapter suites (2.023 s).
  • OCaml documentation, navigation, source-staging and package suites (5.557 s).
  • API model, staged guides and mention freshness (combined checks: 4.806 s).
  • Revision-bound package inventory and example caches (included in the combined freshness checks).
  • Source-link destinations (0.148 s).
  • Selected-port render (73.452 s) and owned-link/fragment audit (23.323 s).
  • Rendered navigation, compensation defaults, compatibility rows and unchanged example blocks.
  • Package-scoped type-aware lint for the guide catalog (0.795 s).
  • Existing OCaml cross-reference floor and type-link ceiling, with tracked thresholds unchanged.
  • Complete assembled-site audit, cross-port browser/search checks and hosted CI for this follow-up.

The render is a qualification build, not evidence that the development-loop budget passed. The latest local outer check fails on the resolver corpus test's five-second timeout (39.809 s for the command); broader type checking was interrupted. Earlier independent source review found no remaining findings. The complete example and its displayed commands retain their installed-consumer evidence; no new local real-tmux run was performed for this documentation refresh.

Qualification limits

The latest native master CI passed quality and tmux 3.3a, but failed the tmux 3.8 installed stream-gap walkthrough after gap and fresh-coverage output with outcome unknown: disconnected: bound daemon exited. The later documentation step was skipped. The daemon's exit cause remains unresolved.

The published native source CI passed quality and both tmux endpoints. That positive sample does not resolve the later streaming failure or earlier findings. The guide preserves the earlier workspace readiness finding, installed stream-gap FAIL/FAIL and final-suite UNVERIFIED/UNVERIFIED. Full native qualification and package adoption remain on hold. This draft leaves producer/publisher pins and production publication to the shared-docs owner.

why: Workspace callers need a complete interruption example with
retained evidence, compensation limits and navigation from task pages.

what:
- Add the source-owned workspace recovery route and overview links
- Refresh native contracts, guide bodies, source links and mentions
- Preserve partial qualification and unresolved streaming results

Native source: 3be232388ec28a260bb87c20e410af2dfa7b1fa2
@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 9, 2026
why: Revision-bound package and example catalogs must describe the
same native source as the refreshed API model and guides.

what:
- Regenerate the OCaml manifest inventory at the selected source
- Align embedded example provenance without changing source bytes
- Preserve every sibling catalog entry
@tony
tony changed the base branch from release/combined to main November 10, 2026 01:33
why: The interruption guide needs public contracts, examples and source
citations from one native revision. The released builder validates its
compiled inputs and native exporter separately.

what:
- Integrate the released docs baseline without rewriting branch history
- Regenerate OCaml API, guide, example and package provenance
- Keep recovery navigation and unresolved qualification limits
@tony
tony merged commit 13c4d6c into main Nov 11, 2026
3 checks passed
tony added a commit that referenced this pull request Nov 11, 2026
why: Four kinds of failure reached the ports only when a port built its
own docs, never in docs CI: an unmapped README badge, a checkout path a
wrapper library could not derive, a tmux-usage citation pinned to a line
the port had moved, and a Haskell exporter gap at the port head. The six
new ports' pages also lagged their repositories, and the Haskell front
page described entity IDs instead of the client.

what:
- Resolve every port checkout through one helper, so a wrapper such as
  Clojure derives its parent's checkout (scripts/lib/port-checkout.mjs)
- Fail on any README badge the badge renderer cannot map
  (scripts/check-port-badges.mjs)
- Build every port's head against docs main weekly and on dispatch,
  without publishing (.github/workflows/port-heads.yml); port-docs.yml
  gains an optional source-repository input, so callers are unchanged
- Locate tmux-usage citations by their text within their body instead of
  a stored line (scripts/lib/tmux-usage-locate.mjs, claims.json)
- Bring the Haskell (#293, #300), OCaml (#294, #295), Clojure (#299),
  Erlang, Common Lisp and Perl pages up to each port's source, with
  examples indexes of their tested programs
- Describe a staged guide without a catalog description by its first
  sentence, and title a link to a staged guide instead of naming its file
- List a port's API roots in llms.txt, and mention MCP only for ports
  that ship an MCP server
- Give every language's Core Library card on the front page the same
  one line, and drop the MCP aside from the new ports' landing pages
- Remove two 5-second test timeouts and record Common Lisp's type-link
  baseline at libtmux-lisp e6f319c42

Base main 856211d, head e36e62b. CI run 43009353757.
@tony
tony temporarily deployed to docs-preview-cleanup November 11, 2026 22:49 — with GitHub Actions Inactive

This branch was previously deployed

1 inactive deployment
docs-preview-cleanup — ab35dc4f Deployed Nov 11, 2026 by tony via cleanup #233
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-preview Run CI without publishing a PR preview.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant