Checkpoint 4.5. Include examples to illustrate how to avoid using deprecated features
Conformance requirements
The specification MUST provide an example for each deprecated feature showing how to avoid using it. This checkpoint is not applicable if there are no deprecated features. This checkpoint is only applicable to specifications that identify "producer of content" as one of its classes of product.
Test Assertion
If the specification identifies "producer of content" as one of its classes of product AND deprecated features exist THEN, for each deprecated feature, the specification provides an example of how an alternative approach done in place of the deprecated feature will produce the same objective. If deprecated features do not exist THEN this checkpoint is not applicable.
Rationale
Examples are helpful in providing alternatives or better ways to get the same results. Showing what can be done in place of the deprecated feature will help get implementers to discontinue use of the deprecated feature.
Discussion
Note that this checkpoint only makes sense for specifications that define the behavior of a producer.
Checkpoint 6.1. Indicate if the specification is extensible, and if extensions are allowed, define their scope and constraints. [Priority 1]
Conformance requirements
The specification MUST state the conditions under which extensions are allowed and disallowed, and if allowed, MUST state:
Test Assertion
The specification states the conditions under which extensions are allowed and disallowed AND IF extensions are allowed THEN the specification states the scope of the extensions AND their effect on conformance claims AND any limitations or restrictions on the use of the extension AND documents the rationale for allowing extensions by referencing use cases and/or project requirements.
Rationale
Readers should be able to understand the motivation for the inclusion of an extension and its intended use. Documenting the scope and rationale for extensions helps assess the impact of extensions on interoperability.
If the specification writer wants to enhance interoperability by constraining implementer extensions, wording in the specification must indicate this.
If extensions are not allowed, then it should be clear to the reader that not only are extensions not allowed, but the circumstances under which they are not allowed. Strict conformance is often imposed on applications or content (e.g., a software program or document instance). This prohibition of extensions could be applied to a specific profile or module, rather than to the entire specification.
The specification MUST define a policy about implementation requirements for mitigation of the interoperability impacts of extensions. This checkpoint is not applicable if extensions are not allowed. This checkpoint is only applicable to specifications that identify "producer of content" as one of its classes of products.
Test Assertion
If "producer of content" is one of the specification's classes of products AND extensions are allowed THEN the specification contains a section detailing the policy about implementation requirements for mitigation of the interoperability impacts of extensions
Extensions can have a negative affect on implementation interoperability. This checkpoint can be used to impose conformance requirements on producer implementations to minimize the consequences of the extension. For example, the specification could include a requirement that implementations have a no-extensions mode; or could include a requirement that implementations include equivalent alternative (standard) content with any extensions; or could explicitly state that there are in fact no implementation requirements for mitigation of interoperability impacts of extensions. This checkpoint can be used to ensure that there is a way to produce (generate) only conforming content.
The specification:
Test Assertion
The specification defines the way conformance requirements can be identified AND identifies conformance requirements EITHER by using the RFC 2119 keywords to denote if the requirements are mandatory, recommended or optional OR (the specification defines an alternative way that conformance requirements are identified AND explicitly states why the RFC 2119 keywords were not used).
Using the RFC 2119 keywords helps to identify the testable statements in a specification as well as those statements that are desirable or allowed. This specification does not place any requirements on the formatting or rendering of these keywords.Guidance on the proper usage of these keywords is given in RFC 2119.
If for some reason, the RFC 2119 keywords cannot be used in the specification, it is important that the reader can identify the conformance requirements explicitly and unambiguously.