Skip to content

docs: split T3 marks, add online-safety column, state the unix philosophy - #57

Open
Kiran01bm wants to merge 1 commit into
mainfrom
kiran01bm/capabilities-t3-marks
Open

docs: split T3 marks, add online-safety column, state the unix philosophy#57
Kiran01bm wants to merge 1 commit into
mainfrom
kiran01bm/capabilities-t3-marks

Conversation

@Kiran01bm

Copy link
Copy Markdown
Collaborator

Summary

docs/capabilities.md rendered every T3 row with the same ❌, so the page visually read as "pg-sprite doesn't support a bunch of things" when most of those rows are deliberate scope boundaries — operations that either have no online-safety problem to solve or belong to a different tool class. This PR makes the distinction visual and explicit, and states the underlying design stance — the Unix philosophy — loudly in the prominent positioning docs.

What

  • T3 rows now carry one of three marks:
    • ⚪ no online-safety problem to solve — transactional catalog work or bootstrap on an object nothing reads yet; run it through owner tooling.
    • 🔵 a different tool class owns it — data-change runners, provisioning/IaC, convergence planners, expand/contract frameworks.
    • ❌ no online mechanism exists — PostgreSQL provides no online pattern to build on; the only rows where "unsupported" is the honest reading (EXCLUDE constraints, USING INDEX on a partitioned parent).
  • Every matrix table gains an "Online-safety problem?" column: "Yes" for rows an online engine must solve; "No" cells name the tool class users should reach for.
  • Tier-model section and the matrix legend updated to define the three marks.
  • Unix philosophy called out explicitly — "do one thing, and do it perfectly", where the one thing is changing the shape of live PostgreSQL tables under concurrent load:
    • docs/vision.md: a dedicated paragraph after the intro, reconciling "one tool for all schema changes" with "do one thing" (depth across every table-shape change, never sprawl across object types), plus a framing line opening "What pg-sprite is not".
    • README.md: a paragraph after the planner positioning, pointing at capabilities.md.
    • docs/capabilities.md: a framing line in "What pg-sprite is — and why it exists" — the page is the map of where the one thing ends.

Why

The capabilities page is the doc we point users at for "does pg-sprite support this?". A scope boundary presented with the same mark as a hard limitation misrepresents the tool: only two rows in the whole matrix are genuinely impossible today, and the rest of T3 is design intent. Naming the Unix philosophy in the vision and README makes that intent legible before a user ever reaches the matrix, and the new column answers the follow-up question ("then what do I use?") inline.

…ophy

A wall of ❌ read as "unsupported" when most T3 rows are scope
boundaries, not gaps. T3 now carries three marks — ⚪ (no online-safety
problem to solve), 🔵 (a different tool class owns it), ❌ (no online
mechanism exists in PostgreSQL) — and every matrix table gains an
"Online-safety problem?" column whose "No" cells name the tool class
users should reach for instead.

The same boundary is now stated loudly as the design stance it is:
vision.md, README.md, and capabilities.md call out the Unix philosophy —
do one thing (online table-shape change under concurrent load) and do
it perfectly — so scope limits read as intent, not missing features.
@Kiran01bm Kiran01bm changed the title docs: split T3 marks, add online-safety column, state the Unix philosophy docs: split T3 marks, add online-safety column Aug 23, 2026
@Kiran01bm Kiran01bm changed the title docs: split T3 marks, add online-safety column docs: split T3 marks, add online-safety column, state the Unix philosophy Aug 23, 2026
@Kiran01bm
Kiran01bm marked this pull request as ready for review August 23, 2026 20:46
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@Kiran01bm Kiran01bm changed the title docs: split T3 marks, add online-safety column, state the Unix philosophy docs: split T3 marks, add online-safety column, state the unix philosophy Aug 23, 2026
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.

1 participant