Make the roadmap reachable, and stop a phase plan claiming shipped work is proposed (#395) - #407
Open
ChronicallyJD wants to merge 1 commit into
Open
Conversation
…rk is proposed Three parts, following the plan on commandprompt#395. A user-facing docs/roadmap.md, in the nav under Development. jd went looking for the file listing upcoming features and could not find it, because the only routes to design/ROADMAP.md were a raw GitHub link in docs/index.md and one in the CHANGELOG header. This publishes a new entry-point page rather than moving design/ROADMAP.md into docs/. That document is a working record: it fails the user-doc style rules in 26 places, and it carries internal notes such as an account of four previous rewrites of itself being wrong. Publishing it verbatim would put working notes on the documentation site, which is the class of problem this issue is about. The new page states status, done, planned and under-investigation, and links to the working record for detail. PHASE_G_EXTERNAL_PARQUET_PLAN.md said "Status: proposed, not implemented" for work that has shipped: the reader, the FDW surface, pushdown, multi-file and partition pruning are all in the tree with suites behind them. It now says shipped and points at ROADMAP.md for anything outstanding. The object-storage item moves out of that file's "Open decisions for review" and into ROADMAP.md's Remaining, pointing at commandprompt#393 and commandprompt#394. A breadcrumb stays behind so a reader does not conclude it was dropped. That heading was the trap: a decided item that was also outstanding work, filed under open decisions. Also carries a correction. The original wording said the scan core is unchanged because both paths just hand it bytes. True of the core, and it understates ranged GETs, concurrency, retries and credentials. docs_style gains the narrow check from the plan: fail if the roadmap is not in the nav. A page outside the nav is not published, and nothing else would notice it had gone. Closes commandprompt#395.
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.
Closes #395. Follows your plan, with one deviation I want to flag rather than bury.
1. The roadmap is reachable
New
docs/roadmap.md, in the nav under Development. Status, done, planned with an issueper row, and an under-investigation section for #403, #405 and #390.
The deviation: I did not move
design/ROADMAP.mdintodocs/. You said publishing itas-is versus editing it was a statement about its content, so here is the measurement:
and it contains lines like "Four successive rewrites of this file were each wrong because
they restated numbers that...". That is a working record talking to itself, which is
useful and is not a user-facing page. Publishing it verbatim would put working notes on the
site, which is the class of problem this issue is about. Rewriting 26 sentences would also
be me changing the voice of your document wholesale.
So: a new entry-point page that links to the working record. Say the word if you would
rather I did the edit and moved it, and I will.
2. The misfiling, fixed both ways
The object-storage item moves out of
PHASE_G_EXTERNAL_PARQUET_PLAN.md's "Open decisionsfor review" and into
ROADMAP.md's Remaining, pointing at #393 and #394. A breadcrumbstays so nobody concludes it was dropped.
It also carries a correction. The original said the scan core is unchanged "because both
just hand it bytes". True of the core, and it understates ranged GETs, concurrency, retries
and credentials, which is the substance of #393.
3. The expiry header, and a thing I found while adding it
That file's header read:
External Parquet read is shipped: the reader, the FDW surface, projection and predicate
pushdown, multi-file reads and partition pruning, all with suites behind them. The document
has been describing shipped work as unbuilt.
That is a sharper instance of your point 3 than the one we started with. A stale "not
implemented" is worse than a missing status line, because it reads as authoritative. It now
says shipped and defers to ROADMAP.md for anything outstanding.
I applied it to this one file rather than sweeping all thirty phase plans, because I have
not verified the status of the other twenty-nine and a wrong status header is exactly the
problem. Happy to work through them if you want, but that is a research pass, not an edit.
4. The check
Your narrow version, since the broad one needs an issue-tracker lookup from a shell script:
check "the roadmap is in the documentation nav" ...A page outside the nav is not published, and nothing else would notice it had gone. That is
how this happened.
Docs and one test script.
ste_checkclean on every user-facing document.