Skip to content

docs(qdp): drop dead ADDING_INPUT_FORMATS.md links from readers README#1307

Open
bearomorphism wants to merge 1 commit into
apache:mainfrom
bearomorphism:fix/1285-readers-readme-links
Open

docs(qdp): drop dead ADDING_INPUT_FORMATS.md links from readers README#1307
bearomorphism wants to merge 1 commit into
apache:mainfrom
bearomorphism:fix/1285-readers-readme-links

Conversation

@bearomorphism
Copy link
Copy Markdown
Contributor

@bearomorphism bearomorphism commented May 10, 2026

What

Slice (A) from #1285 (per the status comment). qdp/docs/readers/README.md has two markdown links to ../ADDING_INPUT_FORMATS.md — a file that has never existed in the repo (see history below). lychee.toml carried an explicit exclude with a TODO: fix the links in this file note because of these.

Why

  • The link checker had to ignore the entire file to keep CI green, hiding any future link rot in this README.
  • Readers landing on the page see a 404-shaped reference for the "extension guide".
  • The published doc on the same topic (docs/qdp/readers.md) had already chosen the right pattern for this — a plain-text ADDING_INPUT_FORMATS.md (TODO) marker — so the in-source README was the inconsistent one.

History — did ADDING_INPUT_FORMATS.md ever exist?

No. The placeholder was committed without the target file ever being written, and was then propagated forward by routine docs work. Verified:

  • git log --all --full-history --diff-filter=AD -- "**/ADDING_INPUT_FORMATS*"0 commits: no commit ever added or deleted such a file.
  • git log --all -S "ADDING_INPUT_FORMATS" --reverse shows where the string entered the repo and how it spread:
Date Commit Author What
2025-12-30 9780d955a (PR #753) @ryankert01 Introduced qdp/docs/readers/README.md with the broken [../ADDING_INPUT_FORMATS.md](../ADDING_INPUT_FORMATS.md) references and a ADDING_INPUT_FORMATS.md # Extension guide entry in the file-organization tree. First and only origin of the string.
2026-01-26 b736eb90d (PR #914) @ryankert01 "[Docs] init docs effort" copied the same readers content into docs/qdp/readers.md, propagating the placeholder into the published site.
2026-02-04 dee2170bc @guan404ming "Deploy new Docusaurus website" — site build artifact (asf-site branch).
2026-02-11 930c0a3fe (PR #1040) @suyashparmar11 "Update the docs versioning" — froze the placeholder into version-0.4 / version-0.5 snapshots.

So the link was a forward-looking pointer to an extension guide that the original author intended to write but never did. Two and a half releases later, it's still a TODO. Rather than block this PR on writing the guide, this fix matches what the published page already does — keep the placeholder visible as plain text — and unblocks the link checker.

How

  • qdp/docs/readers/README.md — replace the two dead [../ADDING_INPUT_FORMATS.md](../ADDING_INPUT_FORMATS.md) markdown links with `ADDING_INPUT_FORMATS.md` (TODO) plain text, matching docs/qdp/readers.md lines 142 and 226. The placeholder remains visible to anyone who wants to write the extension guide later, but is no longer a broken link.
  • lychee.toml — drop ./qdp/docs/readers/README.md from exclude_path (and its TODO: fix the links in this file comment) so CI''s link checker covers the file again.

Out of scope (left to @ryankert01 or follow-ups):

  • Writing the actual ADDING_INPUT_FORMATS.md content.
  • Reconciling docs/qdp/readers.mdqdp/docs/readers/README.md duplication / "File Organization" stale tree.
  • Other [Docs] Enhance docs #1285 sub-tasks (migration docs, more examples).

Verification

Reproduced and verified locally with lychee 0.24.2.

Before:

$ lychee qdp/docs/readers/README.md
[ERROR] file:///…/qdp/docs/ADDING_INPUT_FORMATS.md (at 137:5) | File not found
[ERROR] file:///…/qdp/docs/ADDING_INPUT_FORMATS.md (at 221:25) | File not found
🔍 2 Total ✅ 0 OK 🚫 2 Errors

After (with project config so the new exclude_path is honoured):

$ lychee --config lychee.toml qdp/docs/readers/README.md
🔍 0 Total ✅ 0 OK 🚫 0 Errors

(0 total because the only links in this file were the broken ones; the rewritten markers are now plain text. Nothing else in the README points outward.)

Pre-commit (end-of-file-fixer, trailing-whitespace) passes on the changed files.

Refs #1285

qdp/docs/readers/README.md referenced ../ADDING_INPUT_FORMATS.md in
two places, but that file has never existed. lychee.toml carried an
explicit exclude with a 'TODO: fix the links in this file' note
because of these.

Mirror the treatment already used by the published page
docs/qdp/readers.md, which softens the same dangling reference to a
plain-text 'ADDING_INPUT_FORMATS.md (TODO)' marker rather than a
broken link. This keeps the placeholder visible to anyone looking to
write the extension guide later, without leaving a 404 in the link
checker.

Also drop ./qdp/docs/readers/README.md from lychee.toml exclude_path so
the link checker covers it again.

Verified locally with lychee 0.24.2:
  Before: 2 file-not-found errors on ../ADDING_INPUT_FORMATS.md
  After:  0 errors on qdp/docs/readers/README.md (--config lychee.toml)

Pre-commit (end-of-file-fixer, trailing-whitespace) clean.

Refs apache#1285

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@bearomorphism
Copy link
Copy Markdown
Contributor Author

checking the git history about ADDING_INPUT_FORMATS.md

@bearomorphism
Copy link
Copy Markdown
Contributor Author

ok it looks just a placeholder for me

@ryankert01
Copy link
Copy Markdown
Member

ryankert01 commented May 10, 2026

Not sure of this file ever existed before, but it(ADDING_INPUT_FORMATS.md) looks like should be in issue list not in file.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants