registrystack / registrystack/registry-stack

behavioral-guarantee-claims.md: 13 rows link source files retired with Relay V1

Open Beginner friendly
#917 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

Description

`release/notes/behavioral-guarantee-claims.md` links each claim to the source file it was quoted from. Thirteen of those repository-relative links point at files that Relay V1's retirement removed, so they resolve to nothing on `main`.

## The rows

| Target | Rows | Line(s) |
| --- | --- | --- |
| `docs/site/src/content/docs/explanation/consultation-flow.mdx` | 7 | 25-31 |
| `crates/registry-relay/docs/api.md` | 2 | 67, 68 |
| `crates/registry-relay/docs/configuration.md` | 1 | 69 |
| `crates/registry-relay/docs/ops.md` | 1 | 66 |
| `crates/registry-relay/docs/xlsx-readiness-contract.md` | 1 | 70 |
| `docs/site/src/content/docs/tutorials/deploy-standalone-with-own-data.mdx` | 1 | 71 |

All six were last shipped at `v0.19.0`.

## Suggested fix

The file already has a convention for this. The retired Notary rows link their pages at `v0.16.3`, the last release that shipped them, and the preamble says why. The retired `start/when-to-use` chooser row was pinned the same way at `v0.27.0` in #916.

Applying it here means rewriting each of the thirteen links to `https://github.com/registrystack/registry-stack/blob/v0.19.0/` and adding one preamble sentence covering the Relay V1 retirement.

Worth deciding alongside: whether these rows should be pinned at all, or dropped. The Notary preamble says its rows are kept as the historical record and are "not verification work for a maintained product." Relay V1's rows are in the same position, since Relay V2 is a different runtime with its own contracts under `products/relay-v2`. Pinning preserves the record; dropping shrinks an inventory whose remaining verification value is only in the rows for maintained products.

## Notes

- Found while retargeting the `start/when-to-use` row in #916. These six predate that branch and were left alone as out of scope.
- Nothing currently validates repository-relative links under `release/notes/`, which is why thirteen of them could go stale unnoticed across two product retirements. A check there would catch the next one, but it is a separate call from fixing these rows.

Contributor guide

Open the contributing guide

Research direction

Open release/notes/behavioral-guarantee-claims.md and compare the thirteen Relay V1 rows with the retired Notary convention and the preamble. Decide whether to preserve the historical rows or remove them; done means the chosen treatment is applied consistently and the preamble explains it, with all affected links no longer broken.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.