From 778092cc34f729d62b9e6a145a741c7b39cc5b72 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Thu, 3 Mar 2011 04:58:17 +0000
Subject: Sensible and more rigorous definition of lv2:revision.

---
 core.lv2/lv2.ttl | 62 ++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 47 insertions(+), 15 deletions(-)

(limited to 'core.lv2/lv2.ttl')

diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index 94dcfd5..c1f1a68 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -328,24 +328,56 @@ lv2:port a rdf:Property ;
 
 lv2:revision a rdf:Property ;
     rdfs:domain lv2:Resource ;
-    rdfs:range  xsd:nonNegativeInteger ;
+    rdfs:range  xsd:string ;
     rdfs:label  "revision" ;
-    rdfs:comment """
-The revision of an LV2 Resource. If a plugin's port indices change, the
-revision of the plugin MUST be increased. Note that if port symbols
-change or are removed, the plugin URI MUST be changed, the revision acts
-as a 'minor version' to distinguish otherwise compatible revisions of
-a plugin. A plugin that has changed indices MUST have a lv2:revision
-property, if a plugin has no revision property it is assumed to be 0.
+    lv2:documentation """  
+<p>The revision of an LV2 Resource. This property is used by hosts to
+distinguish different revisions of a compatible resource, e.g. to load only the
+bundle with the most recent revision.</p>
+
+<p>An LV2 revision is a string conforming to the <a
+href="http://semver.org">SemVer</a> specification, except with the major
+version number omitted. In other words, an LV2 revision is of the form Y.Z
+where Y and Z are integers, with an optional special version suffix which "MUST
+be comprised of only alphanumerics plus dash [0-9A-Za-z-] and MUST begin with
+an alpha character [A-Za-z]". For example, "1.3" or "2.0beta2". In contexts
+where a full version number is required, the major version number of any
+released LV2 resource is 1. Unreleased resources (with no revision property, or
+equivalently, revision 0) have full version "0.0.0".</p>
+
+<p>All LV2 plugins and extensions SHOULD have an explicit revision. The
+revision property of a Plugin or Specification MUST be located in the
+<tt>manifest.ttl</tt> file (since it is required by the host for
+discovery). Revisions act as a minor version number, i.e. they are used to
+distinguish revisions of a <em>compatible</em> resource, not to distinguish
+incompatible successors of a resource. More precisely:</p>
 
-Anything that refers to a specific revision of a plugin (e.g. a serialisation
-that depends on specific port indices) MUST refer to the plugin by URI along
-with the revision.
+<ul>
+<li>All revisions of a plugin with a given URI MUST have the same set of
+mandatory (i.e. not lv2:connectionOptional) ports with respect to
+lv2:symbol.</li>
+<li>All revisions of a plugin MUST have at least the rdf:type properties of
+previous revisions.</li>
+<li>All revisions of an extension MUST be compatible in the sense that it can
+interoperate with an implementation of any previous revision.</li>
+</ul>
 
-This property may be used for other objects, in this case it should be
-used in a similar way to represent a 'minor version', and NOT as a major
-version to distinguish incompatible objects (use the URI for that).
-""" .
+<p>This list may not exhaustively cover all cases. In general the rule is:
+replacing a resource with a new revision must not break anything.</p>
+
+<p>A resource with no revision may be considered to have revision 0.</p>
+
+<p>Anything that depends on a specific revision of a plugin (e.g. a
+serialisation that depends on specific port indices) MUST refer to the plugin
+by both URI and revision.  However, implementations should be tolerant and
+extensions should be designed so that there is no need to do this.</p>
+
+<p>When hosts discover several installed revisions of a resource, they SHOULD
+warn the user and load only the most recent revision. The special revision
+"all" indicates that a (partial) description of a resource should be loaded
+regardless of the revision of any other bundles discovered. This revision
+SHOULD be used by bundles that contain additional data for a resource, but not
+the main description of that resource (e.g. plugin presets).</p>""" .
 
 lv2:binary a rdf:Property ;
     rdfs:domain lv2:Resource ;
-- 
cgit v1.2.1