registrystack / registrystack/registry-stack

Docs site: the OpenFn adaptors explanation is published in draft with an unresolved evidence TODO

Open
#1,096 0 comments 0 reactions 0 assignees View on GitHub
area:docs documentation
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

Description

## What

`docs/site/src/content/docs/explanation/openfn-adaptors.mdx` is published with `status: draft` and carries an unresolved `TODO[evidence]` comment saying its claims cannot be anchored from this repository because the adaptor source lives elsewhere. The page nevertheless makes concrete statements about adaptor operations, configuration, failure branches and a pilot topology. A reader has no way to tell which of those statements are current, and the draft marker is the only signal.

## Evidence

- `docs/site/src/content/docs/explanation/openfn-adaptors.mdx` frontmatter, line 5: `status: draft`.
- The same file, lines 22 to 27: `{/* TODO[evidence]: adaptor behaviour, operation lists, result branches, and pilot topology live in the separate registrystack/openfn-language-registry-stack repository and cannot be anchored from this one. ... Re-verify them when that repository changes. */}`
- The page's own text says the preserved pilot "is not a runnable current-source example" and that the 0.1.0 beta packages only two of the three adaptors.

## Proposed fix

Decide one of two paths. Either give the page a checkable anchor (a pinned tag or digest of the adaptor repository plus a replayable check that the operation lists still match) and graduate it to `current`, or take it out of the published navigation until the adaptor repository can be gated from here. Related but distinct: #940 and #236.

## Found while

Extracting reusable App Kit skills against Registry Stack v0.32.0.

Contributor guide

Open the contributing guide

Research direction

Start by reading docs/site/src/content/docs/explanation/openfn-adaptors.mdx, including its frontmatter and TODO[evidence] comment. Verify the adaptor claims against a pinned tag or digest in registrystack/openfn-language-registry-stack, then choose whether to add a checkable anchor and replayable operation-list check or remove the page from published navigation. Done means the page is current and verifiable, or no longer published until it can be gated.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.