Core-Gadget - Versioning
DRAFT
<section title="Versioning" anchor="Versioning"> <t>Both the overall OpenSocial specification and individual Gadget Features are versioned. Gadget specification documents SHOULD specify the version of the OpenSocial specification to which they conform by including the "specificationVersion" attribute on the root <Module> element, as well as the versions of any optional or required features used by including the "version" attribute on <Require> and <Optional> elements.</t> <t>Version identifiers are composed of a series of up to three non-negative integers separated by the dot (.) character. For example, "1.0.0", "1.2.1", etc.</t> <figure><artwork> major = 1*DIGIT minor = 1*DIGIT patch = 1*DIGIT version = major [ "." minor [ "." patch ] ] </artwork></figure> <t>The first number in the sequence represents a "major version". Changes in the major version signify possible backward-incompatible changes from previous versions. For instance, when the methods are removed from the JavaScript API provided by a feature, or when the definitions of XML elements or attributes used within a gadget specification document are changed, or when the processing requirements for any feature or capability are modified, the major version MUST be incremented.</t> <t>The second number in the sequence is a "minor version" that is interpreted relative to the preceding major version number. When the major version is incremented, the "minor version" MUST be reset to 0. Changes in the minor version signify backward-compatible but forward-incompatible changes from previous versions. For example, when new methods are added to the JavaScript API provided by a feature, or when new elements or attributes are added to the gadget specification document format, the minor version SHOULD be incremented and the major version SHOULD NOT be incremented.</t> <t>The third and final number in the sequence is the "patch version" that is interpreted relative to the preceding minor version. When the minor version is incremented, the "patch version" MUST be reset to 0. Changes in the patch version signify changes that are both backward- and forward- compatible with previous versions. For example, when making minor clarifications, fixing errors in the description of a method or element, or making other small changes that neither affect existing functionality or introduce new functionality that would be incompatible with existing versions, the patch version MUST be incremented but the minor and major versions SHOULD NOT change.</t> <t>Version identifiers are hierarchical and can either reference a specific individual version by specifying all three elements (e.g. "1.2.3") or can identify all versions at a particular major or minor level. For instance, the identifier "2.4" would apply to all combinations of versions specifying a major version of "2" and a minor version of "4" (e.g. "2.4", "2.4.0", "2.4.1", "2.4.2", and so on) but not any other minor version (e.g. "2.3", "2.5.2", etc).</t> <t>When processing gadget specification documents and determining the appropriate method of processing the gadget itself as well as determining the correct features to enable for a gadget, containers are required to appropriately match the version identifiers specified within the gadget specification to those provided by the container. For instance, if the gadget requires version "2.3" of a particular feature, the container MUST provide an implementation of the feature whose version matches the given major and minor value (e.g. "2.3.1", "2.3.2", etc).</t> <t>It is RECOMMENDED that gadget developers specify the most general version that will satisfy the requirements of the gadget. Usually, major and minor versions will suffice. The patch version MAY be omitted from gadget specification documents.</t> <t>When a version identifier is omitted from various locations within the gadget specification, the value is assumed to be "1.0". As described above, this value will match any version beginning with "1.0", including 1.0.0, 1.0.1, 1.0.22, etc., but not 1.1.0, 2.0.0, etc. This default value will not change in future versions of the specification, ensuring that Gadgets that omit these values will not have sudden, unexpected changes in behavior when containers adopt new versions of the OpenSocial specification or Features.</t> </section>