Replace placeholder hosts in user-facing docs with RFC 2606 .example TLDs#734
Open
aram356 wants to merge 1 commit into
Open
Replace placeholder hosts in user-facing docs with RFC 2606 .example TLDs#734aram356 wants to merge 1 commit into
aram356 wants to merge 1 commit into
Conversation
…TLDs The docs in `docs/guide/` use ad-hoc placeholder hostnames like `your-domain.com`, `publisher.com`, `external.com`, `tracker.com`, `cdn.com`, etc. to illustrate URLs in curl examples, config snippets, and diagrams. These look real and risk being copy-pasted verbatim, and they fail the upcoming `ts dev lint domains` audit. RFC 2606 reserves `.example` (and `example.com`, `example.net`, `example.org`) specifically for documentation. Switch the placeholders in `docs/guide/` to `.example` equivalents that preserve the same semantic meaning: your-domain.com -> your-domain.example origin.publisher.com -> origin.publisher.example publisher.com -> publisher.example external.com -> external.example advertiser.com -> advertiser.example tracker.com -> tracker.example cdn.com -> cdn.example prebid-server.com -> prebid-server.example staging.publisher.com -> staging.publisher.example new-server.com -> new-server.example redirect1.com / .com -> redirect1.example / .example final.com -> final.example evil.com -> evil.example win-notification.com -> win-notification.example short.link -> short.example https://your-domain/ -> https://your-domain.example/ https://host/path -> https://example.com/path (URL-pattern table) Real third-party hosts that legitimately appear as examples (`ad.doubleclick.net`, `fonts.googleapis.com`, `aps.amazon.com`, the `192.168.1.1` local-server example) are left alone. They warrant a separate decision on whether to add them to the linter allowlist or keep documenting them as-is. No code or test changes; docs-only.
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.
Summary
Rewrites ad-hoc placeholder hostnames in
docs/guide/to RFC 2606 reserved.exampleTLDs. Pure docs change — no code, no tests, no behavior.Why
Docs in
docs/guide/use placeholders likeyour-domain.com,publisher.com,external.com,tracker.com,cdn.com, etc. in curl examples and config snippets. Two problems:https://publisher.com/...and treat it as a working URL.ts dev lint domains), which scopes its allowlist tightly. ~80 violations across these files would force per-line// allow-domain:markers on otherwise clean prose, polluting the docs.RFC 2606 reserves
.example,example.com,example.net, andexample.orgfor exactly this. The linter already allows any.examplehost.Mapping
your-domain.comyour-domain.exampleorigin.publisher.comorigin.publisher.examplepublisher.compublisher.exampleexternal.com/advertiser.com/tracker.com/cdn.com.exampleprebid-server.com/staging.publisher.com/new-server.com.exampleredirect1.com/redirect2.com/final.com.exampleevil.com/win-notification.com/short.link.examplehttps://your-domain/...https://your-domain.example/...https://host/path(URL-pattern table)https://example.com/pathOut of scope
Real third-party hosts in the docs (
ad.doubleclick.net,fonts.googleapis.com,aps.amazon.com, the192.168.1.1local-server example) are left as-is. They legitimately document real services and warrant a separate decision: add to the linter allowlist, or keep documenting them as-is. Six lint violations remain on this branch for that reason.Test plan
cd docs && npm run formatclean