Versioning Proposal (level 1)

W3C Working Draft 04 October 2017

Specification Metadata

Canonical version:: https://www.w3.org/TR/hr-time/
This version:: https://www.w3.org/TR/2017/WD-hr-time-2-20171004/
History:: https://www.w3.org/standards/history/hr-time
Latest editor's draft:: https://w3c.github.io/hr-time/
Editors:: Ilya Grigorik, Google Inc., igrigorik@gmail.com; James Simonsen, Google Inc., simonjam@google.com (Until January 2015); Jatinder Mann, Microsoft Corp., jmann@microsoft.com (Until February 2014)
Repository:: We are on Github.; File a bug.; Commit history.
Implementation:: Can I use Versioning Proposal?; Test Suite; Test Suite repository

See below for various explanations related to the specification metadata. "canonical version", "This version", and "History" are the only required specification metadata.

Abstract

This document is a sample of what a real specification would like in the future. It has nothing to do with High Resolution Time except for the fact that HRT is used as a sample for the links. It contains various definitions and concepts used by W3C /TR cooks.

Status of This Document

This document is NOT the official versioning policy of W3C.
It is a a sample document meant to illustrate.

See Version Management in W3C Technical Reports instead for the W3C policy on /TR links/versioning.

This document isn't meant to change drastically how specifications will look like after the 2018 GRS (great redesign of specifications scheduled for 2018). For that, you can look at ideas such as the 2012 one.

1. Considerations

This document is a reflection on how to change our header links in the beginning of December 2017.

Not all headers included in this document need to be used. The important part is for the tooling to find its stuff and for the users not to be confused too much.

This document contains the advanced ability of selecting which spec you would like to see. Your current specification preference is []. You may change this by using specification preferences. (hint: change your preference to "upcoming" or "ed" and reload this document to see the effect).

2. The Origin of the Proposal

See the notes from the TPAC 2017 session.

The original meaning of latest, upcoming, all can also be found in the Latest versions proposal for leveled specifications.

2.1 Use Cases

Allow more predictability in the system for shortnames
Allow reference tools, such as specref, to better navigate through the W3C references (and consequently, the editing tools like specref can use that)
Reduce confusion around versioning by harmonizing its handling while giving the possibility to Groups to stop displaying it
Clean-up the main /TR page by "downgrading" old level versions that aren't yet obsolete/superceded/rescinded

3. Shortnames and leveled shortnames

We distinguish between:

https://www.w3.org/TR/<shortname>/, the shortname URL of a specification. This returns the document returned by /latest or /upcoming (depending on the Group choice).
https://www.w3.org/TR/<shortname>-<level>/, the leveled shortname URL of a specification. This returns the non-outdated document for a specific <level>.

with:

<shortname> ::= [-a-zA-Z]+
<level> ::= [.0-9]+

When looking at a specification use the shortname URL of a specification, it is not possible to know if you're looking at /latest or /upcoming. One may use specification preferences to set proper expectations.

4. About using level numbers in specification

The title of a specification MAY reflect the <level> of a specification. The dated URL of the specification (aka This Version) and the leveled shortname URL of the specification MUST contain the <level>.

Some Groups feel strongly about the levels of their specification, others prefer not to deal with them. We give the choice.

<Level> is a number, not interpreted by the underlying system except for its sequence order. You may use for example 2, 2.0, 2018.

You may add additional specification metadata headers in your document, such as a "Latest published Level 2 version" for the leveled shortname URL.

5. On obsolete/superceded/rescinded/retired/outdated

obsolete, superceded, and rescinded are maturity levels defined by the W3C Process. (superceded is actually proposed in Process 2018)
retired is an indication for Group notes when work on a specification ceased (see Stopping Work on a specification)
outdated is applied automatically by the W3C server when a dated document has been outdated by a new dated publication, when the level matches.

5.1 Outdated warning

Currently, we are displaying 2 types of outdated warnings:

For Recommendations that aren't obsolete/superceded/rescinded and don't have a more recent edited recommendation, we indicate that a more recent document with incorporated errata (an Edited CR or an Edited PR) is available.
or we display a note indicated "This version is outdated!".

In all cases, we direct the reader to the leveled shortname URL instead.

6. /latest/

"Latest" will return the most "stabilized" document available. Those links are created automatically for all https://www.w3.org/TR/<shortname>/. For example, https://www.w3.org/TR/hr-time/latest/

As such, it points to the first document found in the following ordered list:

the highest level being a CR, an Edited CR, a PR, an Edited PR
a REC that is not obsolete/superceded/rescinded/retired/outdated
the highest level being a Note if not retired
the lowest level being a WD
the obsolete/superceded/rescinded REC
the retired Note

7. /upcoming/

"upcoming" will return the "tip" document available. Those links are created automatically for all https://www.w3.org/TR/<shortname>/. For example, https://www.w3.org/TR/hr-time/upcoming/

As such, it points to the first document found in the following ordered list:

the highest level that is not obsolete/superceded/rescinded/retired/outdated
the obsolete/superceded/rescinded/retired document

8. /ed/

If available, "ed" will redirect to the "nightly build" of the upcoming document.

As such, it redirects to the document known as "editor's draft" that is associated with the upcoming document, if known.

should we just use "Nighlty build" instead of Editor's draft?

9. Canonical version

This represents the preferred URL you want people to use to access the specification. It helps search engines to be able to consolidate the information they have for the individual URLs (such as links to them) on a single, preferred URL. It is either the shortname URL or the leveled shortname URL.

Canonical version header shouldn't differ from rel=canonical.

RFC6596 indicates that the canonical link relation specifies the preferred URL from resources with duplicative or superset content. Sometimes, we do remove content from one published dated version to another, so we're not following RFC6595 strictly. However, we consider the consolidation of search results to take priority here given that one can always access the history of the specification.

10. History

This is intended to replace what used to be "Previous version" and represents the history for all snapshot for a given shortname URL. For example, https://www.w3.org/standards/history/hr-time

History pages aren't handling all snapshots currently. We're looking at changing that.

11. /all/

This represents the list of all non-outdated specifications for all level versions for a given shortname. For example, https://www.w3.org/TR/hr-time/all/

12. This version

This is the dated snapshot of the document:

https://www.w3.org/TR/<YYYY>/<status>-<shortname>-<level>-<YYYY><MM><DD>/, the dated snapshot of a specification. This returns the document for a specific <level> published on a specific date, even if it has been outdated.

with:

<status> ::= [A-Z][-A-Z]+ (see pubrules documentation)
<YYYY> ::= [2-9][0-9][0-9][0-9]
<MM> ::= 0[1-9] | 1[0-2]
<DD> ::= [0-2][0-9] | 3[0-1]

Should we stop using "This version" and use "This snapshot" instead? This would avoid confusion with levels, etc.

12. Normative references

For the purpose of normative references, you may use the shortname URL, the leveled shortname URL, or a dated URL depending on the nature of the dependency.

Not using the dated URL will increase the likelyhood of getting borken fragments over the years. We should encourage editing tools and editors to maintain an history of fragments to avoid disappointing the readers.