Skip to content

change(governance): decouple speccing from shipping, add /considered/#121

Open
jdevalk wants to merge 1 commit into
mainfrom
add/considered-register
Open

change(governance): decouple speccing from shipping, add /considered/#121
jdevalk wants to merge 1 commit into
mainfrom
add/considered-register

Conversation

@jdevalk

@jdevalk jdevalk commented Jul 23, 2026

Copy link
Copy Markdown
Owner

Implements the two rule changes you asked for, plus the public register the second one needs.

1. Speccing no longer requires shipping

The old rule was:

do not promote a convention to spec status without us shipping a working implementation first. The site is the proof-of-feasibility.

That forced a false choice whenever a topic was right for readers but irrelevant to a small static site — and it quietly encouraged the worst outcome, implementing something we don't need purely to earn the right to document it.

Replaced with three honest page shapes, all fine:

  1. Specced and shipped — the common case, keeps the "this site ships it; see X" callout.
  2. Specced, deliberately not shipped — carries a one-line note saying so, with the reason.
  3. Not specced — see below.

Shape 2's note is treated as content, not an apology. "This site does not ship it: we are static, so no response ever means this changed" tells the reader something true about when the topic applies. Silence would not.

2. Adoption, not finality, is the bar — and thin adoption is your call

A final RFC with permanent IANA registration still doesn't earn a page if nothing implements it; the page would recommend a header no cache reads. The converse also holds — a widely-deployed convention can earn a page before its RFC lands.

Where adoption looks thin, the routine must now surface it rather than decide: not open the PR, not silently drop it, but put it in Slack with what was checked (MDN/BCD, Chrome Platform Status, the relevant CDN or server docs) and wait for you.

3. New: /considered/ — "Considered, not adopted"

Hand-curated collection at src/content/considered/, same shape as the changelog (not derived — nothing generates it). Per entry: title, date, reason, sources, and revisit — what would change our mind, which is what keeps the register from becoming a graveyard.

Three reasons, each with a standing definition on the page:

Reason Meaning
too-early Real and final, but nothing implements it yet
out-of-scope A way of building a site, not something a site does
too-narrow Real, implemented, auditable — but applies to too few sites

Grouped by reason rather than date: it reads as a register of decisions, not a timeline.

Seeded with four real decisions, all from actual history rather than invented:

  • HTTP Cache Groups (RFC 9875)too-early. Final and IANA-registered, but no MDN page or BCD key, no Chrome Platform Status entry, nothing in Cloudflare's cache docs or changelog, and no sign in Fastly, Varnish, nginx or Squid. Souin is the one candidate and documents itself against the pre-RFC draft.
  • HTTP QUERY (RFC 10008)out-of-scope. A property of an API, not of a website.
  • CSS subgridout-of-scope. Records why add(foundations): CSS subgrid page #82 was closed. This is the reference case for newly-Baseline authoring features generally, which is why it's worth having written down.
  • WebSubtoo-narrow. Real, implemented, auditable, but hub publishing is a fediverse/IndieWeb speciality.

Entries are decisions already taken, not a queue. When a reason expires, the entry gets deleted in the same PR that adds the spec page.

Wiring

Header and footer nav · OG image (/og/considered.png) · llms.txt Project section · a "When a topic is absent" section in SKILL.md (digest re-signed) so an agent checks the register before reporting a gap or re-proposing something already turned down · matching guidance in CONTRIBUTING.md for human contributors.

ops/routines/daily-standards-scan.md is updated too, so the next scheduled run picks up the new rules automatically — including a requirement that every turn-down gets a /considered/ entry, and that the Slack "skipped, and why" section agrees with the register.

Checks

Rendered and verified at /considered/ in the dev server — three reason groups, four entries, revisit notes and source links all present.

npm run build ✓ · npm run check ✓ (0 errors) · npm run lint ✓ · npm run format:check ✓ · npm run check:skill

Two things for you to decide

  1. Naming. I read "specs we have decided not to ship yet" as standards we decided not to write up — since rule 1 makes not-shipping the unremarkable case, the noteworthy decision is not speccing at all. If you meant the other thing (a list of specced topics we don't implement), that's a different page and I'll rebuild it.
  2. No changelog entry. Per CLAUDE.md the changelog is about the spec's content, pages not plumbing, and this adds no spec page. Happy to add a changed entry if you'd rather the register's arrival were announced.

🤖 Generated with Claude Code

Two rule changes, plus the public register the second one needs.

1. Speccing no longer requires shipping.

The old rule ("do not promote a convention to spec status without us shipping a
working implementation first — the site is the proof-of-feasibility") forced a
false choice whenever a topic was right for readers but irrelevant to a small
static site. It also encouraged the worst outcome: implementing something we
don't need, purely to earn the right to document it.

Replaced with three honest page shapes — specced and shipped, specced and
deliberately not shipped, or not specced — where shape 2 carries a one-line note
on the page saying we don't ship it and why. That note is content, not an
apology: "we are static, so no response ever means this changed" tells the
reader something real about when the topic applies.

2. Adoption, not finality, is the bar for adding a page — and thin adoption is
   the maintainer's call.

A final RFC with permanent IANA registration still doesn't earn a page if
nothing implements it; the page would recommend a header no cache reads. The
converse also holds — a widely-deployed convention can earn a page before its
RFC lands. Where adoption looks thin, an agent must surface it rather than
either shipping the page or silently dropping it.

3. New: src/content/considered/ → /considered/ ("Considered, not adopted").

Hand-curated collection, same shape as changelog (not derived, nothing
generates it). Per entry: title, date, reason (too-early | out-of-scope |
too-narrow), sources, and `revisit` — what would change our mind, which is what
keeps the register from being a graveyard. Grouped by reason rather than date,
because it reads as a register of decisions, not a timeline.

Seeded with four real decisions:
- HTTP Cache Groups (RFC 9875) — too-early. Final and IANA-registered, but no
  MDN page or BCD key, no Chrome Platform Status entry, nothing in Cloudflare's
  cache docs or changelog, and no sign in Fastly/Varnish/nginx/Squid. Souin is
  the one candidate and documents itself against the pre-RFC draft.
- HTTP QUERY (RFC 10008) — out-of-scope. A property of an API, not a website.
- CSS subgrid — out-of-scope. Records why PR #82 was closed; this is the
  reference case for newly-Baseline authoring features generally.
- WebSub — too-narrow. Real, implemented, auditable, but hub publishing is a
  fediverse/IndieWeb speciality.

Entries are decisions already taken, not a queue. When a reason expires, the
entry is deleted in the same PR that adds the spec page.

Wiring: header + footer nav, OG image, llms.txt Project section, and a
"When a topic is absent" section in SKILL.md (digest re-signed) so an agent
checks the register before reporting a gap or re-proposing a rejected topic.
CONTRIBUTING.md gains the same guidance for human contributors.

Verified: page renders correctly at /considered/ in the dev server, three reason
groups, four entries. build ✓ lint ✓ format ✓ check ✓ (0 errors) check:skill ✓

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying specification-website with  Cloudflare Pages  Cloudflare Pages

Latest commit: c893601
Status: ✅  Deploy successful!
Preview URL: https://b6601c2f.specification-website.pages.dev
Branch Preview URL: https://add-considered-register.specification-website.pages.dev

View logs

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