search

tobie / specref

An open-source, community-maintained database of Web standards & related references.
http://www.specref.org/
Apache License 2.0
165 stars 142 forks source link

Consider supporting entries for specification series #811

Open tidoust opened 2 months ago

tidoust commented 2 months ago

Via discussion in https://github.com/tobie/specref/pull/810#discussion_r1722985394

Various specs in W3C come in levels that belong to the same series. Both levels and series have shortnames in W3C, but the series shortname is more to be seen as a way to redirect to the "current" level (which evolves over time). For example: css-fonts-3, css-fonts-4, css-fonts-5 all belong to the css-fonts series. As the time of writing, the current spec is css-fonts-4.

Levels may be created after a first iteration on a spec. For example, media-source-1 was known as media-source until level 2 got created. media-source is now the shortname of the underlying series, the current spec being media-source-2.

Specref does not have the concept of series. That means no entry for css-fonts, and no easy way to "follow" the current specification in the latter case, requiring clunky workarounds, as done in #810. It would be great to support series shortnames more directly in Specref.

The end goal would be to make it easy to reference a spec by:

  1. its series shortname, such as css-fonts, in which case the reference goes to the latest version of the current level in the series.
  2. its shortname, such as css-fonts-5, in which case the reference goes to the latest version of that level.
  3. a dated version, such as css-fonts-4-20240201 in which case the reference goes to the specified version. The dated version typically includes the level, we should not need to create or use a css-fonts-20240201 entry!

Adding support for series requires switching the W3C update script to the W3C API, because tr.rdf does not know anything about series either.

Note the need to preserve past dated versions in the case where the level gets introduced afterwards (e.g. media-source-20140717 needs to exist even though the media-source spec is now known as media-source-1). Also note that some specs start without a level, then get a level, and then get back to a no-level mode...

(I don't think the notion of specification series exists in other SDOs, although that could perhaps be useful to track versions of ETSI and ISO specs longer term)

tobie commented 2 months ago

My suggestion would be to have the dated versions tied to the unversioned entry, so: FOO-20240201, not FOO-2-20240201.

tidoust commented 2 months ago

My suggestion would be to have the dated versions tied to the unversioned entry, so: FOO-20240201, not FOO-2-20240201.

In the css-fonts example, both css-fonts-4 and css-fonts-5 are currently active (that situation is not uncommon for CSS specs). That means it's possible to end up in a situation where both levels get published on the same day. That would create duplicate CSS-FONTS-YYYYMMDD entries. That shouldn't happen much in practice, for sure, but that may happen...

tobie commented 2 months ago

Fair point.