Skip to content

docs: record three things that lived only in a conversation - #51

Merged
hebus merged 1 commit into
mainfrom
docs/record-known-limits
Aug 21, 2026
Merged

hebus merged 1 commit into
mainfrom
docs/record-known-limits

Conversation

@hebus

@hebus hebus commented Aug 21, 2026

Copy link
Copy Markdown
Owner

Four write-downs. Each one is information that existed nowhere in the repository, which is the only reason any of them is worth a commit.

1. architecture-beta edge labels cannot be written

I set out to add a regressions fixture for a collision I had claimed — an architecture edge label sitting on a route's corner and landing on a node. It does not reproduce, and finding out why was the useful part:

  • @mermaid-js/[email protected] publishes an Edge AST with a title field.
  • The grammar it ships has no ARCH_TITLE token at all — checked in the bundled chunk, not inferred. Every candidate syntax is a parse error.
  • Mermaid's develop branch has since added '-' title '-' to the arrow rule, so this starts working on a parser bump, not on a change here.

So the readme stops calling that support "full", and edgeLabel() says it is unreachable and why. No fixture: a regression test whose source cannot parse proves nothing, and would have looked like coverage.

2. The stylesheet saving is about half the arithmetic on an RSC build

Next.js emits every element twice — once as HTML, once in the RSC payload — so a saved copy is still counted once in each. Recorded next to the claim it bounds, with the measurement: four diagrams, 227.9 kB to 202.1 kB, where removing four inlined copies outright would have been nearer 52 kB.

3. Why only two checks are required on main

CONTRIBUTING.md now explains the protection, because the failure mode is silent and total — a pull request that can never merge, with nothing on the page saying why:

  • check skips itself for changeset-release/main and #skip-changeset, so requiring it blocks every version pull request.
  • build has a paths filter, so it may never report at all.
  • Zero approvals because GitHub forbids self-approval on a single-maintainer repository; enforce_admins off so the owner cannot lock themselves out; linear history not required because every merge here is a merge commit.

4. The roadmap had two 0.3 entries

Mine, from the previous pull request. Now unnumbered — the numbers went stale the moment 0.3 shipped.

On the changeset

There is one, patch, and I checked rather than assumed. The only source change is a comment, but Vite builds this package with minify: false, so the comment lands in dist/index.js and the tarball genuinely differs from the published 0.3.0 — verified by diffing the built tree against the published one, file by file. The entry says the thing a consumer cares about: edge labels are unavailable, and why.

- architecture-beta edge labels cannot be written: the AST carries a
  title, the shipped grammar has no token for one. The readme stops
  calling that support "full", and the code path that would place such
  a label says it is unreachable until the parser is bumped
- No regression fixture for the collision that label could cause: a
  test whose source cannot parse proves nothing
- The stylesheet saving is about half the byte arithmetic on an RSC
  build, since the framework emits every element twice. Written next
  to the claim it bounds
- CONTRIBUTING now explains why only verify and sites are required
  checks. Requiring `check` would block every version pull request,
  and `build` has a paths filter so it may never report at all
- Roadmap loses its version numbers, which went stale when 0.3 shipped
@hebus
hebus merged commit 3bbeb38 into main Aug 21, 2026
3 checks passed
@hebus
hebus deleted the docs/record-known-limits branch August 21, 2026 16:28
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