This document is part a series of documents that describe W3C Technical Report Publication Policies.
As W3C has matured, more and more technologies are undergoing major revisions (as seen with SVG 2.0, HTML 5.2, DOM 4.1, CSP 3, etc.). Working Groups typically find they need to address several high-level versioning issues when starting to revise a Recommendation:
There are also numerous operational issues to consider:
This document provides some rules and guidance on a few of these topics, based on experience with W3C publications. This document is far from an exhaustive treatise on version management; it is intended to help raise awareness about a handful of common W3C publication issues. Please also consult the list of TAG findings for discussion of versioning from a technical perspective.
See the standards FAQ for information about this version and latest version URLs.
W3C Working Groups have adopted several approaches to versioning, including:
Note: Current W3C practice is to reserve the phrase "Nth Edition" for editorial revisions of a Recommendation.
The remainder of this document focuses on the choice of using major and minor version numbers, as this is scheme most groups have adopted.
Branding, magnitude of changes, relationships to other specifications, and other factors have an impact on the choice of version number. Please also note the different classes of change described in section 6.2.5 of the W3C Process Document. This document does not address all of the factors that go into the choice of a version number. However, one common expectation when using the major/minor version scheme is that, for a given major version number, the Recommendation with the highest minor version number supersedes all others sharing that major version number. By supersede, we mean that authors and implementers should stop using the old version and start using the new version; in effect the new version masks the old one. The status section of a minor version should state clearly that it supersedes the previous minor version.
The expectation that version N.2 supersedes N.1 leads to other suggestions in this document. Therefore, if a Working Group does not expect this to be the case for their documents, they should contact the Communications Team.
Please recall that W3C's persistence policy ensures that a superseded document will always be identifiable by its "this version URL."
Each W3C technical report includes several URLs to make it easier for readers to track the evolution of a specification. There are other ways to find information about W3C technical reports, including on the W3C technical reports index, on Working Group pages, and through a search engine. The URL with shortnames has proved a useful companion to the "this (dated) version URL."
In the linear world of a document series that starts with a First Public Working Draft and ends with a Recommendation, it is easy to understand the semantics of a "latest version URL". When a Working Group is managing multiple versions of a specification in parallel, some clarification is required. When a "latest version URL" appears in an "ExampleML 2.0" specification, does the URL identify the latest version of ExampleML? of ExampleML 2.x? of ExampleML 2.x Recommendation? Something else?
The following proposal -- for multiple "latest version URLs" -- strikes a balance between brevity in the document front matter and useful additions to help readers find important resources. This proposal will not address the needs of all readers or users of a specification. We therefore encourage Working Groups to advise readers (e.g., in the status section, or in the section on changes) to consult the Working Group's public pages for the complete revision history of related specifications.
W3C recommends that groups use the following versioned URLs: For a set of minor versions that are part of the same major version branch, one URL designates the most recent minor version, whatever its maturity level (Working Draft, Recommendation, etc.). The label for this URL should be "Latest [Acronym] 1 version", as in "Latest ExampleML 1 version".
We recommend this syntax for version number URLs:
/TR/<shortname-N> (or /TR/<shortnameN>)
Those versioned URLs provides quick access to the latest work within a
given major version.
N is a number, not interpreted by the underlying system except
for its sequence order. You may use for example 2, 2.0, 2018.
When a Working Group follows this scheme, Director approval of new version number is not required.
Working Groups wishing to adopt this scheme even though they already have allocated their short name should contact email@example.com.
Here is an example of how W3C manages these URLs over time.
|ExampleML 1.0 WD published||ExampleML 1.0 Rec published||ExampleML 1.1 WD published||ExampleML 1.1 Rec published||ExampleML 2.0 WD published||ExampleML 2.0 Rec published|
|"Latest ExampleML 1" URL identifies||ExampleML 1.0 WD||ExampleML 1.0 Rec||ExampleML 1.1 WD||ExampleML 1.1 Rec||ExampleML 1.1 Rec||ExampleML 1.1 Rec|
|"Latest ExampleML 2" URL identifies||N/A||N/A||N/A||N/A||ExampleML 2.0 WD||ExampleML 2.0 Rec|
Some groups have suggested that additional latest version URLs may help them manage their work. For instance, some Working Groups would like to use "latest minor version" URLs while working towards a new Recommendation. We advise against "latest minor version URLs" because their utility is short-lived, in light of the premise that minor versions supersede one another. For example, as soon as the ExampleML 1.2 is published, the "latest ExampleML 1.1 URL" will become a dead-end; one will not be able find the new 1.2 minor version directly from the 1.1 version. Rather than publish "latest minor version URLs", we recommend simply using the group's home page to track the latest draft of a minor version.
For each set of specifications, a URL designates the most relevant of a given technology, whatever the major version number. The label for this URL should be "Canonical URL".
We use this syntax for those URLs:
As an example, see the HTML specification
The canonical URL designates the most relevant specification approved by a Group for a given technology. It may designate the most mature Recommendation of a given technology or the most agreeing-on version depending on the choices of the Group. The label for this URL should be "Canonical URL".
In practice, this "Canonical URL" returns the document provided in 3.3.1 Latest URLs or in 3.3.2 Upcoming URLs. Working Groups wishing to pick their most relevant specification for the purpose of this "Canonical URL" should contact firstname.lastname@example.org.
The "Canonical URL" and the version numbers dp not address all of the needs that go into the choice of a link for a technology. Consequently, several URLs are created automatically based on the "Canonical URL".
"Latest" will return the most "stabilized" document available. We use this syntax for those URLs:
For example, /TR/CSP/latest/ points to the latest Recommendation for CSP.
More precisely, the algorithm to determine this URL will return the first document in the following list:
"upcoming" will return the "tip" document agreed by the Group. We use this syntax for those URLs:
For example, /TR/CSP/upcoming/
As such, it points to the first document in the following list:
If provided in the published document, those URLs will redirect to the editor's draft of the upcoming document, which may or may not have review from the Working Group. We use this syntax for those URLs:
For example, /TR/CSP/ed/ redirects to https://w3c.github.io/webappsec-csp/ .
If the editing workmode of your Group guarantees its agreement to the content of the editor draft (this is the case if your Group uses a pull request review process), we highly recommend at the minimum that the document be automatically published to ensure that the editor draft URLs and the Upcoming URLs return the same main content. An even better approach in such case is to redirect the "editor draft URL" to the "Upcoming URL" (this avoids returning 404 on the editor draft URL).
CSP1 is a Working Group Note. CSP2 is a Recommendation. CSP3 is a Working Draft. This would imply the following URLs:
/TR/CSP1/returns the CSP1 Working Group Note
/TR/CSP2/returns the CSP2 Recommendation
/TR/CSP3/returns the CSP3 Working Draft
/TR/CSP/upcoming/returns the same document as /TR/CSP3
/TR/CSP/latest/returns the same document as /TR/CSP2
/TR/CSP/returns the same document as /TR/CSP/upcoming (since the Working Group favors the "tip")
/TR/CSP/ed/redirects to the CSP3 editor draft, ie https://w3c.github.io/webappsec-csp/
W3C is automatically outdating a dated document if it is used as a previous version link from a more recent one. This allows the community to be aware that they're potential looking at an old draft. For example, see the W3C Working Draft, 1 September 2016 for CSP3.
At this time (read: we know this is suboptimal nowadays), we still recommend that you not create normative references from a W3C Recommendation to resources (published inside or outside W3C) that are likely to change over time and where those changes might affect the meaning of, or conformance to, the W3C Recommendation. It follows that if you wish to create a normative reference to a W3C technical report, you should use a "this version" URL instead of a canonical URL (or their alternative forms).
In general, if the Working Group has expectations about the evolution of a normative reference (however it is identified), the group should state those expectations in prose in the technical report.
See the Manual of Style and the considerations for normative references for additional discussion of references to resources that change over time and when references to these resources are are appropriate.
It is important to specify clearly the relationship between a Namespace URL and the specification that defines it. Each group should explain that relationship in the defining specification and/or schema; see URLs for W3C Namespaces for more information.