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>