Skip to content

feat(site[erlang]) Add Erlang API and guides - #292

Draft
tony wants to merge 16 commits into
erlang-app-manifestsfrom
erlang-site-registration
Draft

tony wants to merge 16 commits into
erlang-app-manifestsfrom
erlang-site-registration

Conversation

@tony

@tony tony commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add versioned Erlang API pages with native signatures, records, types and source links.
  • Stage installation, graph, querying, ownership, diagnostics and architecture guides from qualified core source.
  • Add Erlang navigation, branding, command attribution and complete-program entry points.
  • Exclude Erlang MCP destinations and describe the workspace application as unpublished.
  • Stage model-pinned Erlang sources and validate publication prefixes in CI.
  • Verify OTP API links by native module, kind and arity, with reviewed manual links.
  • Align cached package provenance with the existing API pins without changing versions.
  • Render native record names, language glossary entries, highlighting and BEAM navigation.
  • Name Erlang badges and glossary headings as records, types, callbacks and applications while preserving their link anchors.
  • Describe the available workspace source loader separately from its unfinished execution and release work.
  • Build native docs from exact selected OTP/Rebar3 pins with a checksum-verified producer.
  • Keep audits active while the no-preview label holds publication.
  • Recheck current draft status and preview opt-out labels inside the publisher.

Stacked on the application-manifest reader in #284. The API model and native guides use the qualified core source; the exporter has its own source identity. The home program retains its original execution receipt and source pin.

Installation uses a Rebar3 Git subdirectory dependency. The requirements state OTP 29.1.2 and continuous tmux 3.3a–3.8 support. The port's CI samples the tmux endpoints on both supported architectures. Source-guide links retain their version when opened from native API documentation.

Test plan

  • Export native documentation from a clean source checkout and verify source provenance.
  • Check cross-language concept mappings and excluded-product navigation regressions.
  • Build the Erlang static site with search and audit its internal links and fragments.
  • Inspect desktop and phone rendering, mobile navigation and copied installation payloads.
  • Run workspace TypeScript, Astro and Python type checks.
  • Check source-checkout and publication-prefix workflow contracts.
  • Check independently refreshed evidence dates and the fixed-clock negative cases.
  • Run registration-focused unit checks and recheck the corrected home-page card contract.
  • Verify all 19 OTP destinations, native identity regressions and the complete negative verifier.
  • Compare cached package provenance with the pinned source manifests.
  • Pass source-unit suites, corrected producer controls, lint and type checks.
  • Qualify the owning Erlang docs caller with publication disabled.
  • Exercise late preview opt-outs in the publisher's current-state shell gate.
  • Pass the required whole-site inner, medium and outer gates.
  • Qualify full multi-port assembly and deployed documentation.

The whole-site outer gate remains FAIL at its 60-second cutoff (60.776 seconds for the complete admitted command). API/type-check work was unfinished. Standalone type checks pass in 97.163 seconds; the Erlang static build passes in 58.307 seconds. The focused registration command first found a home-card contract mismatch; the final home-card suite passes in 8.948 seconds after linking the populated Examples overview. Its other focused suites passed unchanged. The build and browser checks precede that final card-link adjustment. These scoped passes leave the whole-site gate open. The checked-in budgets remain unchanged, and incremental Erlang cost remains unmeasured. Timing coordination continues in #271.

The first hosted run failed before the audit because guide staging lacked the Erlang checkout. The workflow now checks out the model-pinned revision and passes it to staging; the local workflow contract suite passes. The follow-up run reached the audit and exposed a committed-evidence fixture using the bundle's older date as its clock. The fixture now checks committed records against today; its complete negative suite passes in 13.162 seconds. The third run then exposed missing OTP destination evidence. The reader now admits Erlang, checks native module names, kinds and arities, and records all 19 destinations. Current source refresh checks pass for 119 native inputs and 25 guide bodies. Four focused suites pass 231 tests in 22.028 seconds; the complete API-link negative verifier passes in 199.844 seconds. The package-cache freshness check also found an older Elixir revision: a separate commit aligns its two revision fields with the existing API model while preserving the identical manifest bytes and version. That full freshness check passes in 1.318 seconds. These checks do not establish a whole-site or deployment pass; the combined release checks now own hosted qualification.

The latest source-unit audit passes in 507.190 seconds admitted (507.586 including resource admission); assembled-output suites remain explicitly skipped in this source-only run. The corrected producer suite passes in 10.127 seconds, lint in 4.236 seconds and workspace type checks in 114.576 seconds. Independent review has no outstanding findings. These audit timings do not change the development-loop budgets or establish incremental Erlang cost.

The draft's no-preview label holds preview publication while audits and artifact generation continue. The owning Erlang caller now exists on master, uses one immutable shared producer pin for both reusable workflows, and requires manual dispatch with publication disabled by default. Its hosted build passes with publication skipped. Full local publication auditing still fails on different Python API-model and protocol-snapshot source pins sharing one checkout override; the docs coordinator has the evidence. Whole-site assembly and deployment remain unqualified.

An artifact browser check found dotted Erlang page headings after the hover-name correction. The qualified heading follow-up passes real-route naming checks, lint, types and desktop/mobile checks against its checksum-verified hosted artifact. The corrected artifact uses the shared branded assets; global analytics configuration, OS clipboard reads and the full root assembly remain outside that browser scope. This PR now includes that follow-up. Its earlier audit was cancelled when the head advanced. The subsequent standalone audit was cancelled after the coordinator made the combined audit authoritative.

The combined release in #291 owns the release audit and includes the coordinator's subsequent Erlang reference corrections. The earlier combined build failed on unresolved references, including Erlang record-field and receipt-metadata labels. Native-only builds skip the global dangling-reference gate, so the scoped build and browser passes above do not establish a zero-reference result. The combined branch contains Erlang's xref floor of 2919 and type-link ceiling of 0; those keys do not establish a fresh rendered measurement. Reference ceilings and development-loop budgets remain unchanged.

The glossary and workspace review adds native visible names while preserving canonical anchors and application names. Both rendered regression cases first failed for the intended label mismatch. The final seven focused suites pass 335 tests in 34.770 seconds; scoped type-aware lint passes in 2.060 seconds and Astro type checks pass in 77.400 seconds with 0 errors and 0 warnings. The default 2 GiB Node heap first exhausted memory; the successful retry uses 4 GiB inside the unchanged 8 GiB resource cap. The full outer loop remains FAIL at its cutoff, 60.915 seconds admitted. Independent review found the reference-card alias path; that path is corrected and has no remaining findings. These checks do not establish assembled-site or deployment qualification.

The workspace overview now links the existing source loader and normalized-document API at a pinned revision. Plan, apply, a standalone CLI and a registry release remain pending. Static inspection confirms the owning publication workflow matches the central dispatch inputs and pinned deploy contract; the expected environment and secret names exist. Deployment was not run. The new standalone audit was cancelled after verifying its exact branch and head because #291 remains the authorized combined gate.

The publisher now rejects a current draft PR or no-preview label immediately before credentials, including case variations of that label. This protects queued builds and partial reruns after a PR opts out. Positive coverage includes Erlang and ordinary labels; malformed draft or label data fails closed. These regressions first reproduced the accepted opt-outs and now pass with the full deployment suite. Erlang publication PR #5 remains draft pending the final combined docs pin, including this guard. The combined audit remains authoritative; the additional standalone audit was cancelled as redundant.

The guide-reference refresh aligns all four Erlang source-bound inputs with the corrected core source already used by the combined branch. Graph traversal names tmux_snapshot:related/3; relationship, receipt-metadata and unpublished workspace labels use prose. All 119 native input hashes and 25 guide bodies match the immutable source revision; all 88 qualified function/type mentions resolve to exported model declarations (0.363 seconds for the complete verification command including startup and setup). Staged-guide freshness passes in 0.419 seconds. These checks do not measure the full rendered dangling-reference count; #291 remains its gate.

The standalone audit at this refresh head failed before assembly on its stale mention index (82 seconds for the hosted job including setup). Its cancellation request arrived after failure. The combined commit already has a separate mention index recording 0 Erlang entries among 56 unresolved mentions; that committed index is not a new rendered-build measurement. No standalone retry or shared ceiling change was made.

tony added 2 commits November 8, 2026 18:21
why: Erlang callers need source-linked API documentation and tested
programs beside the other language ports.

what:
- Register native signatures, source guides and tmux command usage
- Add Git installation, branding and versioned language navigation
- Keep MCP excluded and workspace availability explicit
- Preserve unpublished product links while excluding absent products
why: Registered Erlang guides require their exact source checkout on
GitHub runners before publication audits can stage them.

what:
- Check out Erlang at the API model revision for guide staging
- Admit its version prefix through publisher validation
- Include Erlang in the source-checkout workflow assertions
why: Independently refreshed destination records can be newer than the
bundle date. Using that older date as today's clock rejects valid data.

what:
- Check committed records against the current UTC date
- Retain fixed clocks for synthetic age and future-date cases
tony added a commit that referenced this pull request Nov 9, 2026
why: Erlang's site registration adds its API, guides and registry entries; without it the port is not on the site.

what: Merge #292 at 9495e59, keeping main's productExcluded helper beside Erlang's productIncluded, one capability table for OTP lifecycles and Eio, and erlang in each port list.
tony added 3 commits November 8, 2026 19:34
why: Erlang registration reached the publication audit without language admission or native OTP destination evidence.

what:
- Read OTP ExDoc modules, qualifiers, kinds and arities
- Check predefined types and reject wrong owners and operand counts
- Verify OTP destinations and review the two manual guide links
- Refresh Erlang API, guides and provenance from qualified trunk
why: Source freshness rejects a cache pinned to an older revision than the selected API model, even when the owning manifest is unchanged.

what:
- Read the Elixir revision from its existing API model
- Preserve the package version and all other manifest entries
why: The compatibility clarification moves existing command-reference diagnostics by four lines, making their cached positions stale.

what:
- Regenerate the mention index against the current staged guide
- Preserve backlink targets and all other ports
@tony tony added the no-preview Run CI without publishing a PR preview. label Nov 9, 2026
tony added 6 commits November 8, 2026 20:08
why: Erlang exposes snapshot listings and relationships through module functions, so entity-class assumptions miss its public API.

what:
- Exercise module functions and arity-bearing names
- Check all four snapshot listings before utility members
- Preserve existing ordering bounds for other ports
why: Review and CI validation can precede permission to publish a shared-site preview.

what:
- Hold preview publication when the triggering PR has no-preview
- Keep audit, artifact upload and publisher dry-run jobs active
- Document applying the label before the triggering push
why: Destinations verified on different days remain valid even when the bundle has an older date.

what:
- Check committed evidence against the current clock
- Use fixed synthetic dates for age and future boundaries
- Preserve mixed-date coverage and the production verifier
why: Erlang reference pages must preserve the language's syntax and appear alongside its BEAM companion.

what:
- Highlight Erlang examples and define native reference labels
- Render qualified native records and group Erlang under BEAM
- Exercise module identities, source links and installation-first guides
- Preserve the existing source-link fixtures for every other port
why: Documentation assembly needs compiled Erlang documentation from the revision it is publishing.

what:
- Validate exact OTP and Rebar3 source pins before setup
- Verify the Rebar3 artifact and clean failed installations
- Run the pinned shared exporter in the selected core checkout
- Catalogue the caller and retain independent Elixir toolchain checks
why: A dotted parent prefix misrepresents Erlang functions, types and exported records.

what:
- Reuse native names for Erlang declaration headings
- Check actual record, function, type and module routes
- Preserve hierarchical breadcrumbs and other languages' headings
tony added a commit that referenced this pull request Nov 9, 2026
why: Erlang's registration stack gained its own destination-link verification, reference integration, member-order checks and the port-docs toolchain steps; the earlier merge of #292 is superseded and the combined tree carried duplicate Erlang registrations of its own.

what: Merge #292 at f4c5cf6, taking its Erlang glossary, link verification, command-reference and ordering changes and the Erlang toolchain and export steps in port-docs.yml, keeping every other port's lines, and setting OCaml's xref floor to OCaml's own 4584.
tony added a commit that referenced this pull request Nov 9, 2026
why: Erlang's agent moved its declaration headings to the native spelling; the combined tree carries that reference change beside Haskell's, Clojure's and Lisp's.

what: Merge #292's erlang-docs-caller-e7740d9a7 at e7740d9, adding Erlang to the ports whose page heading uses the short native name and keeping the Lisp heading check beside Erlang's.
tony added 3 commits November 8, 2026 23:56
why: Erlang reference badges should name the declarations readers use.

what:
- Render record, type, callback and application labels from native definitions
- Preserve glossary anchors, symbol palettes and application names
- Keep glossary headings, previews and exports aligned
- Cover native badges and reference-card labels in rendered components
why: The availability page hid the validated loader API that source users can use.

what:
- Link the load and normalized-document functions at a pinned revision
- Point readers to the tested workspace example
- Distinguish the loader from unfinished plan, apply and CLI work
why: A ready pull request can become draft or opt out while its preview build is queued.

what:
- Check current draft status and label data before requesting publication credentials
- Honor case variations of the no-preview label
- Exercise Erlang publication and late opt-out responses in the actual shell gate
why: Relationship and metadata labels must not appear as nonexistent APIs.
what:
- Align Erlang API, path, guide and command inputs with the corrected source
- Name graph traversal through the public tmux_snapshot:related/3 function
- Describe metadata and unpublished workspace operations in prose
tony added a commit that referenced this pull request Nov 9, 2026
…ts (#291)

why: Six ports had docs branches ready but no published site, and
three shared fixes were waiting behind them. Releasing them together
gives one docs commit to trust for deployment and one set of caller
pins to move, instead of six separate waves.

what:
- Add OCaml (#264), Haskell (#265), Erlang (#266, #278, #279, #280,
  #284, #292), Common Lisp (#268), Perl (#274) and Clojure (#276):
  native API pages, tested guides, navigation, landing and switcher
  entries, and cross-reference data for each
- Keep browser checks from loading third-party resources, and pass
  the check origin to the three scripts that named an undefined base
  (#287)
- Render guide badges at build time instead of hotlinking shields
  (#288)
- Size the reference sidebar and member bars from the viewport, so
  the Chrome iOS keyboard no longer shrinks them (#290)
- Make the OCaml model producer verify its native build inputs in
  their checkout and reject stale ones, with controls run in CI
- Offer one switcher page per port, and title Perl's workspace guide
  "Workspace guide"
- Regenerate the registry, mention index and cross-reference counts
  for the combined port set

Base main 2593131, head dabe59b. Port heads: #264 7d4f88f
and 73fb1ad, #265 dc024e3, #268 947da1f, #274 818fa2e,
#276 a134503, #287 a437e97, #292 e7740d9.

This branch has not been deployed

No deployments
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