From bc2d0f4cd71dfff2ea0473bd0c4d3e10d067bbdc Mon Sep 17 00:00:00 2001 From: Kin Lane Date: Fri, 7 Aug 2026 09:37:20 -0400 Subject: [PATCH] Give the roadmap a title, and one heading level per section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page had two h1s — "From a description to a specification" and, halfway down, "The tracked work" — and no heading anywhere that said "Roadmap". It read as two documents stapled together, and the pivot between them arrived without warning. Lead with "# Roadmap" and a lede that states the page is in two halves: the shape, which is the argument, and the tracked work, which is the generated issue list. Demote both old h1s to h2 and their children to h3, so the outline matches every sibling page. No Liquid logic changed. The where_exp filters stay split one comparison each, for the Jekyll 3.10 that Pages pins. Co-Authored-By: Claude Opus 5 (1M context) --- roadmap.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/roadmap.md b/roadmap.md index f0350ba..138b127 100644 --- a/roadmap.md +++ b/roadmap.md @@ -8,10 +8,20 @@ description: >- permalink: /roadmap/ --- -# From a description to a specification +# Roadmap + +This page is in two halves. **The shape** is the set of artifacts that separate what exists today +from a formal specification — four workstreams and the governance problem underneath them, written +as an argument. **The tracked work** below it is the live issue list, generated from the repository, +where each of those workstreams gets broken into things somebody can actually pick up. + +--- + +## From a description to a specification The document in this repository describes the Spectral ruleset format well. That is not the same -thing as a specification, and being clear about the difference is the point of this page. +thing as a specification, and being clear about the difference is the point of this half of the +page. A description tells you how something behaves. A specification tells an independent implementer what they **must** do to be correct, gives them a way to prove it, and gives everyone else a @@ -19,11 +29,11 @@ stable thing to cite. The gap between the two is not more prose — it is a spec artifacts that standards organizations produce as a matter of routine and that software projects almost never get around to. -This page is the list. All of it is open work. +This half is the list. All of it is open work. --- -## 1. Normative wording +### 1. Normative wording The draft currently explains the format in the voice of documentation: *this is what happens when you write `given` as an array*. A specification says *an implementation **MUST** treat an array @@ -39,7 +49,7 @@ where the current description hides an assumption rather than states a rule. --- -## 2. A conformance section +### 2. A conformance section Right now there is no definition of what it means to conform. That means **no compatibility claim between any two engines can be adjudicated**, because there is nothing to adjudicate against. @@ -55,7 +65,7 @@ this repository can produce. [More on the plan](/conformance/). --- -## 3. A versioning strategy +### 3. A versioning strategy Numbered versions, a clear line between what is stable and what can still move, and references that keep working. The model to follow is the one the API specification world already understands @@ -68,7 +78,7 @@ document that will outlive everyone's interest in the project. [The proposal](/v --- -## 4. A stable identity, published on its own site +### 4. A stable identity, published on its own site A specification needs a URI that is stable, controlled by the project, and safe to cite. Today the schema identifies itself with a source-control URL pointing at a branch — mutable by definition, on @@ -81,7 +91,7 @@ to happen deliberately and early. [Where that stands](/schema/#the-canonical-uri --- -## Why the order matters +### Why the order matters These are listed roughly in dependency order. Normative wording is what makes a conformance section possible, because you cannot test a requirement that was never stated as one. Conformance is what @@ -93,7 +103,7 @@ None of it requires permission. All of it benefits from people who have done it --- -## The fifth thing, which is not a document +### The fifth thing, which is not a document All four workstreams above assume somebody is here to do them, and right now that is one person. **A specification with one maintainer is not a specification, it is a file somebody happens to be @@ -106,7 +116,7 @@ Co-maintainers are welcome and actively wanted. --- -# The tracked work +## The tracked work Everything above is the shape. **Everything below is generated from issues labeled `roadmap` on [this repository]({{ site.repo }})**, refreshed automatically — no hand-maintained list, because a @@ -176,7 +186,7 @@ Two rules keep it honest: {% for g in groups %} {% assign bucket = live | where: "maturity", g %} {% if bucket.size > 0 %} -## {% case g %}{% when 'ready' %}Ready to implement{% when 'consensus' %}Rough consensus{% when 'discussing' %}Under discussion{% when 'raised' %}Raised{% endcase %} +### {% case g %}{% when 'ready' %}Ready to implement{% when 'consensus' %}Rough consensus{% when 'discussing' %}Under discussion{% when 'raised' %}Raised{% endcase %}

{% case g %}{% when 'ready' %}Specified enough that the next step is a pull request.{% when 'consensus' %}Agreement on what to do. Still needs pinning down before anyone builds it.{% when 'discussing' %}Genuinely open. This is where arguing is worth the most.{% when 'raised' %}Newly raised, barely discussed. Easiest to redirect.{% endcase %}

@@ -207,7 +217,7 @@ Two rules keep it honest: {% endfor %} {% if parked.size > 0 %} -## Parked +### Parked