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 SMIL 2.0, SVG 2.0, and XHTML 2.0, not to mention HTML 4, DOM Level 3, and CSS Level 3). 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 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 "Latest version URI" mean when W3C has published Recommendations 1.x and 2.x of a technology?
2. What short names should a Working Group choose to facilitate future management of multiple versions?

This document provides some 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.

This version and latest version URIs are described on the TR page.

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

3. Tracking Versions

Each W3C technical report includes a "latest version URI" 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 latest version URI has proved a useful companion to the "this version URI."

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 the "latest version URI". When a Working Group is managing multiple versions of a specification in parallel, some clarification is required. When a "latest version URI" appears in an "ExampleML 2.0" specification, does the URI identify the latest version of ExampleML? of ExampleML 2.x? of ExampleML 2.x Recommendation? Something else?

The following proposal -- for two "latest version URIs" -- 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.

3.1 Latest version URI Semantics

W3C recommends that groups use the following latest version URIs:

1. For a set of minor versions that are part of the same major version branch, one URI designates the most recent minor version, whatever its maturity level (Working Draft, Recommendation, etc.). The label for this URI should be "Latest [Acronym] 1 version", as in "Latest ExampleML 1 version".
2. In each Recommendation, a second URI designates the most mature Recommendation of a given technology, whatever the major version number. The label for this URI should be"Latest [Acronym] Recommendation", as in "Latest ExampleML Recommendation"

The first URI provides quick access to the latest work within a given major version. The second URI helps readers find the most mature standard when several major versions are available.

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

Some groups have suggested that additional latest version URIs may help them manage their work. For instance, some Working Groups would like to use "latest minor version" URIs while working towards a new Recommendation. We advise against "latest minor version URIs" 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 URI" 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 URIs", we recommend simply using the group's home page (public or Member-only) to track the latest draft.

3.2 Latest Version URI Syntax and Short Names

We recommend this syntax for latest version URIs:

1. /TR/<shortname>: Latest <Name> Recommendation
2. /TR/<shortnameN>: Latest <Name> N version

As an example, see the MathML 2.0 Recommendation which uses:

1. /TR/MathML/ : Latest MathML Recommendation
2. /TR/MathML2/ : Latest MathML 2 version

When a Working Group follows this scheme, Director approval of short names is not required; the Communications Team can allocate them (provided they are reasonable, not offensive, etc.).

Working Groups wishing to adopt this scheme even though they already have allocated other short names should contact the Communications Team.

3.3 Latest Version URIs and Normative References

We 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" URI instead of a "latest version" URI.

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 for additional discussion of references to resources that change over time and when references to these resources are are appropriate.

4. Namespace Management

It is important to specify clearly the relationship between a Namespace URI and the specification that defines it. Each group should explain that relationship in the defining specification and/or schema; see URIs for W3C Namespaces for more information.