Consistent guidelines spec links, especially in CSS

[mirisuzanne]

It seems like it might be useful to have some consistent guidelines for linking to specifications.

With CSS specs, there are several variations to consider. First, the publishing status:

• Editor's Draft URLs start with drafts.csswg.org/…, and represent the latest thinking of the spec editors. However, these are drafts. While they're publicly visible, they are not necessarily stable, or agreed-on, and are not considered to be 'published' for public use.
• Published specification URLs all start with www.w3.org/TR/…. While Working Drafts may still change, publishing those changes requires group consensus. At this point, even as the status moves from WD to Candidate Recommendation or beyond, the URL will remain more reliable.

I think we should always use TR links when they are available for a feature. Hopefully it's rare that browsers ship a feature before it reaches any published consensus. When looking at an Editor's Draft, there is always a link at the top to the Latest published version of that spec.

Which leads us to the fact that CSS specs are versioned. For every 'module' (eg css-cascade) there are several layers of link specificity:

• Per-publication 'dated', e.g. https://www.w3.org/TR/2021/WD-css-cascade-4-20211015/
• Per-level 'versioned', e.g. https://www.w3.org/TR/css-cascade-4/
• Per-module 'current' level, e.g. https://www.w3.org/TR/css-cascade/

I'm not exactly sure how the 'current' level is determined. For css-cascade that is currently pointing to css-cascade-4, even though levels 5 & 6 are well established (defining layers and scope). I imagine the 'current' spec is the lowest level that still has a Working Draft status?

I expect it's best to optimize for long-term accuracy. Years after a feature has shipped, the 'current' link should still give a relatively accurate and up-to-date definition of the feature.

My proposal:

When linking to a CSS specification:

• Prefer the 'current' TR link, without any level version number.
• If the feature does not yet appear in the 'current' level, prefer the versioned TR link where that feature is defined (e.g. css-cascade-5 for layers, and css-cascade-6 for scope)
• If no published specification includes the feature, then link the Editor's Draft

Ideally, non-current links get updated over time. I don't know if that's something that can be automated?

I don't think this issue exists in the HTML specification, unless we want to specify linking to the single-page vs multi-page version? It's a massive page all together, so might be best pointing people to the multi-page URL? But I'm not sure if one is more stable than the other.

I have no experience with TC39.

[gsnedders]

There's a bunch of history here around browser-compat-data about what spec links should point at; historically some of this was tied to the fact that many specs didn't publish to TR at all often (often with multiple years between publication).

w3c/browser-specs#1268 is kinda related to this.

I'm not exactly sure how the 'current' level is determined. For css-cascade that is currently pointing to css-cascade-4, even though levels 5 & 6 are well established (defining layers and scope). I imagine the 'current' spec is the lowest level that still has a Working Draft status?

This is whatever the WG has decided; for the CSS WG I believe the answer is whatever spec the WG considers "current work" — typically levels beyond the current work have been delta specs, which makes them not useable as general link for the whole spec.

[jamesnw]

In looking at the peer datasets, it looks like Caniuse uses published versions, and BCD uses drafts, and I suspect we are using drafts because we build our draft/specs from BCD data.

[mirisuzanne]

I totally get that there are caveats with any approach here, but it seems to me like unpublished drafts are not the best compromise. When a level is written as a diff spec, the ED is also a diff - so provides no advantage. And the fact that ED's get ahead of published specs is as much a risk as it is helpful. EDs are (intentionally) used to draft ideas for discussion, and are very likely to change before getting published.

For features that can be linked in the 'current' WD, that provides the most resilience long-term. The link will still be relevant, even as the feature is updated in newer levels of the spec. In all cases, I think it's reasonable to link directly to ID's within the spec. Ideally those are carried over from one level to the next - working in both diff and non-diff levels.

In the same way this project opens issues on BCD, I think people should feel free to open issues on CSSWG - requesting an update to what is current, or requesting the group re-publish an outdated spec.

[captainbrosset]

Tagging @tidoust for a point of view on this, which I feel he will have.

I can't bring anything constructive to the conversation myself, other than, yes, we use ED here because this is how BCD did it too.

On why BCD did it this way, maybe @Elchi3 can help us with some history from that project.

[tidoust]

From a web-features perspective, I would personally favor following the same convention as that used in BCD, given the close ties that exist between the projects. Now, I wouldn't mind if BCD changed its approach and started linking to published versions where possible. One practical argument could be that CSS Editor's Drafts are hosted on a more "fragile" server with stricter rate limits.

A key issue remains that published versions of some CSS specs remain outdated compared to their Editor's Draft, making linking to them less appealing from a documentation perspective (when developers follow a link to a spec, they usually want to access the most up-to-date spec text).

If we were to adopt a "prefer TR links" approach, I would not necessarily switch to the "current" level if the feature was updated in a more recent level. The proposal seems sound otherwise. Dated URLs are best avoided no matter what.

That's a side note but, in the end, what matters more to me is which fragments get used: whenever possible, we should favor stable IDs, meaning links to exported definitions or headings, as raised in w3c/webref#1198 (comment). And that we have tooling in place to validate the URLs and fragments, which should be doable using data in Webref (@Elchi3 explored automatic validation for BCD in mdn/browser-compat-data#23958, ideally that would be completed to warn about links to unstable identifiers). Even with stable identifiers, there is no guarantee that a fragment remains in the spec from one level to the next. Unversioned URLs also need validation over time.