Member → The Art of Consensus →

Version Management in W3C Technical Reports

This Guidebook is the collected wisdom of the W3C Group Chairs and other collaborators.

Status of this Document

This document is part a series of documents that describe W3C Technical Report Publication Policies.

1. Introduction

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:

1. What will be the relationship between the Recommendations? Does the new one supersede or outdate the old one or will the two co-exist, each with an appropriate audience? What is the impact of these changes on authors? On implementers?
2. Should the version number change? What will the marketing impact be of a particular version number change?
3. What is the impact on XML namespaces defined in one or both specifications?
4. Beyond the technical issues related to forwards and backwards compatibility, what about the branding and naming issues?

There are also numerous operational issues to consider:

1. What does "Canonical URL" mean when W3C has published Recommendations 1.x and 2.x of a technology?
2. What conventions should a Working Group choose to facilitate future management of multiple versions?

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.

2. Version Numbers

W3C Working Groups have adopted several approaches to versioning, including:

• Major and minor version numbers (e.g., SMIL 2.1)
• Levels (CSS 3, DOM 3)

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."

2.1 Tracking Version Numbers

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.

2.2 Versioned URL Semantics

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 webreq@w3.org.

Here is an example of how W3C manages these URLs over time.

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.

3. Short Names and canonical URLs

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:

/TR/<shortname>/

As an example, see the HTML specification which uses /TR/html/.

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 webreq@w3.org.

3.2 Alternative canonical URLs

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".

  /TR/<shortname>/latest/
  

    /TR/<shortname>/upcoming/
    

            /TR/<shortname>/ed/
            

4. Dated URLs and outdating

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.

5. URLs and Normative References

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.

6. Namespace Management

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.