docs: consolidate contribution guides, fix broken doc links - #149
Merged
Conversation
AGENTS.md duplicated the Add a Test and Add a Framework guides for LLM consumption, and the two had drifted apart. Remove it and move the parts it carried that the site was missing into the guides themselves. Add a Framework gains the /cookie endpoint, the Dockerfile requirements (repo-root build context, bind 0.0.0.0, ENTRYPOINT over CMD), the language field in probe.json, the server documentation page step, and a verification section. Add a Test gains the RFC Requirement Dashboard step, the category folder table, and the WS-/CAP- prefixes. Its suite file paths were missing the Http11Probe/ segment, so anyone following it would not have found the files. Also fixes the relref links on both pages: the site generator expands them to /docs/docs/..., which 404s.
|
MDA2AV
changed the title
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
1 participant
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.
Two related commits, both about the contribution docs being wrong in ways that would bite anyone following them.
1. Fold
AGENTS.mdinto the on-site guidesAGENTS.mdduplicated the Add a Test and Add a Framework guides in a second, LLM-facing copy, and the two had drifted apart. This removes it and moves everything it carried that the site was missing into the guides themselves, so there is one source of truth that both humans and agents follow.Add a Framework was missing most of what
AGENTS.mddocumented:/cookieendpoint — spec, response format, and the Flask example (the page documented only/and/echo, so a contributor following it would fail the entire Cookies suite)0.0.0.0:8080,ENTRYPOINToverCMDprobe.jsonwithlanguage(the page showed{"name": "..."}only) plus the optionalrepositoryfielddocs/content/servers/page, using the current frontmatter shape rather than the stale template inAGENTS.mdAdd a Test gained the RFC Requirement Dashboard step, the category folder table, the
WS-/CAP-prefixes, and thectx.HostHeader/MakeRequestconventions. Fixes along the way:src/TestCases/Suites/…; the real path issrc/Http11Probe/TestCases/Suites/…. Anyone following it would not have found the files.{{< relref "docs/rfc-requirement-dashboard" >}}, whichweb/build.mjsexpands to/docs/docs/rfc-requirement-dashboard.html— a 404.hugo server→web/build.mjs.2. Fix server source links and
CAP-*docs mapping38 of the 39 server pages linked to
github.com/MDA2AV/tree/main/...— missing the repository segment, so every "View source on GitHub" 404s. All now point atgithub.com/MDA2AV/Http11Probe/tree/main/..., matching the one page that was already correct. Verified that every link target directory exists undersrc/Servers/.CAP-*was the only test prefix with no rule inDocsUrlMap, so the CLI printed those nine results without a docs link while every other category got one. The nine tests map 1:1 onto thecaching/pages, so this is a prefix rule rather than nine dictionary entries. The website was never affected —web/build.mjsbuilds its own slugmap from the doc pages and already covered all nine.Before / after, on the same run:
Verification
dotnet build Http11Probe.slnx -c Release— 0 warnings, 0 errorsnode build.mjs— 281 pages, noAGENTSreferences, no unexpanded shortcodes, no leftover broken server links indist/--test CAP-ETAG-304 --test CAP-IMS-FUTURE --test WS-UPGRADE-POST --test COMP-BASELINE; all four now print docs links/docs/rfc-requirement-dashboard.htmlThe only remaining
AGENTS.mdmentions are two dated CHANGELOG entries, left as history.