- From: <david_marston@us.ibm.com>
- Date: Mon, 12 Jan 2004 16:28:36 -0500
- To: www-qa-wg@w3.org
I said that the conformance information in a spec MUST address the relationship between the current version and prior versions, if the version is beyond 1.0. The point came up when discussing SpecGL checkpoint 7.4, which is about finding the information. But now we have a more basic question of where SpecGL requires such a statement, if at all. There is a clear (IMHO) requirement in part 1.3.6 of PubRules, which is a Member-only document. If we want to say something about versions within SpecGL, it could fit in with GL 4 (deprecation), which is the only GL that discusses versions. It could also spawn a new section 2.2 of the text, just after DoV, pushing the current 2.2-2.4 ahead to be 2.3-2.5, but I don't see the need for that if we can point to some other public definition of versions. The text of Guideline 4 currently has three paragraphs. I propose a new 2nd paragraph, somewhat like this: After the initial publication of a specification, the Working Group that issued it may pursue another version. Implementers will want to know whether the Working Group intends to have complete or partial backward compatibility in the later version. The specification MUST address backward compatibility, including enumeration of features that will be obsoleted. The Working Group should consider the use of version numbers in XML documents, if relevant to their technology. The method of detecting a prior version, if specified, is distinct from whether the new version is completely compatible with the old. Typically, the specification MUST address the relationship between the current version and the immediate prior version. Some Working groups choose to have separate conformance policies for "major" and "minor" versions, in which case they MUST explain their policies for compatibility to both the most recent major version and also the most recent minor version, if it is newer than the major version. If the above is approved, the following to changes to GL 4 can be voted on as a package. If approved, they expand GL 4 to encompass all aspects of variability across versions. ======================== BEGIN PACKAGE ============================== The first change is to reword the Guideline to say: Identify the relation between version differences and conformance. Then add a new checkpoint. Calling it 4.1 makes logical sense (if you can stand a renumbering). Checkpoint 4.1 [NEW] Address compatibility of the current version relative to prior versions upon which it builds, if any. [Priority 1] CONFORMANCE REQUIREMENTS: The specification MUST document in a normative section the relationship of the current version to the most recent prior version, by stating: + whether old material will always be used without error, and if not, what old features will now raise an error, + instances in which old material would have caused an error but will now invoke a new feature (other than obvious differences), + whether old material will always cause the same result as it did in the prior version, and if not, what behaviors have changed, + whether a version number or similar flag on the input will affect behavior, and if so, all differences in behavior attributable to values of that flag, AND + whether there is a syntactic item (element, option, etc.) provided to cause a particular compatibility behavior to occur. If the Working Group set a compatibility policy for the current version relative to a prior version other than the most recent, such as a "major" version, all of the above points MUST be addressed relative to that version as well. This checkpoint is not applicable if there are no prior versions. RATIONALE: A reader must be able to determine whether the current version is based on a prior version, or on a combination of "major" and "minor" prior versions. The primary policy is whether backward-compatible behavior is expected or not, and then if it is, the extent of any incompatibilities that are allowed. Incompatibilities may occur in several forms, varying with the class of product. References to "old material" in the conformance requirements mean whatever artifact may have been created according to an older version and is being forced to interoperate with an implementation of the newer version. It can be assumed to be obvious that syntactic items of the current version that did not exist in the older version and would cause an error in the older version are "obvious differences" not requiring deep treatment. The reader must be able to determine whether the compatibility policy is adjustable by means of an option, special element, attribute that indicates the version, or other signal. The editors should anticipate that the reader will always want to know how the current version compares to the immediate prior version. If each version is documented with an explanation of its compatibility with the immediate prior version, the documents will have a cumulative definition of compatibility between any two versions. Version numbers are especially useful when the policy calls for compatibility from a "major" version to all its "minor" following versions. For example, all 3.x versions must be backward compatible to lower-numbered 3.x versions, back to 3.0, but that any 3.x has substantial incompatibilities with 2.x and 1.x versions. TEST ASSERTION: The specification, if for a version after the first, contains normative language that states the backward-compatibility policy relative to the immediate prior version, both in general and in detail. The details allow unambiguous determination of all instances of old material that will cause new behavior in the new version, including raising an error in one version and not the other. The specification indicates whether the backward-compatibility and the differences are universal or are affected by option flags, version flags, or features associated with other Dimensions of Variability. If there are two or more prior versions, the specification indicates policy and behavior changes relative to any prior version, other than the immediate prior version, if such prior version represents a baseline for the policy. Finally, expand 4.3 as follows: change each occurrence of "deprecated feature" to "obsoleted feature, deprecated feature, or new means of controlling backward compatibility". In the rationale for 4.3, add a new paragraph: Backward compatibility may be controlled or affected by a module or profile, and may be the subject of one or more discretionary items. If an implementer is granted a choice about supporting backward compatibility through these or other means, that policy must be documented. ======================== END PACKAGE ============================== Whether the package above is accepted or not, Checkpoint 7.4 should be expanded to include version-to-version compatibility. Specifically, a new second bullet should be added to the conformance requirements: + unambiguous statements about backward compatibility, if there is a prior version, regardless of how much compatibility is required, Having done that, I don't think the test assertions for 7.4 need to change. .................David Marston
Received on Monday, 12 January 2004 16:32:17 UTC