SpecGL checkpoint 7.4 and versions

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