Core-Gadget - Versioning

   <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 &lt;Module&gt; element, as well
   as the versions of any optional or required features used by including the 
   "version" attribute on &lt;Require&gt; and &lt;Optional&gt; 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>