From 4ee92b42cbbb5ba43ddf7536b71811195b025900 Mon Sep 17 00:00:00 2001 From: David Robillard <d@drobilla.net> Date: Sat, 9 Feb 2013 03:11:31 +0000 Subject: Reserve minor version 0 for unstable development plugins (fix #9). --- lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl | 2 ++ lv2/lv2plug.in/ns/lv2core/lv2core.ttl | 54 ++++++++++++------------------ 2 files changed, 24 insertions(+), 32 deletions(-) (limited to 'lv2/lv2plug.in/ns/lv2core') diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl index 25cace6..4fe9f3a 100644 --- a/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl +++ b/lv2/lv2plug.in/ns/lv2core/lv2core.doap.ttl @@ -27,6 +27,8 @@ rdfs:label "Set range of lv2:designation to lv2:Designation." ] , [ rdfs:label "Make lv2:Parameter rdfs:subClassOf rdf:Property." + ] , [ + rdfs:label "Reserve minor version 0 for unstable development plugins." ] ] ] , [ diff --git a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl index c339343..8bfd6ec 100644 --- a/lv2/lv2plug.in/ns/lv2core/lv2core.ttl +++ b/lv2/lv2plug.in/ns/lv2core/lv2core.ttl @@ -312,12 +312,11 @@ lv2:minorVersion rdfs:range xsd:nonNegativeInteger ; rdfs:label "minor version" ; lv2:documentation """ -<p>The minor version of an LV2 Resource. This property is used (along with -lv2:microVersion) by hosts to distinguish different versions of a compatible -resource, e.g. to load only the bundle with the most recent version.</p> -<p>The version of an LV2 resource is composed of two fields: minor version, -and micro version. These have the usual semantics:</p> +<p>The minor version of an LV2 Resource. This, along with lv2:microVersion, is +used to distinguish between different versions of the <q>same</q> resource, +e.g. to load only the bundle with the most recent version of a plugin. An LV2 +version has a minor and micro number with the usual semantics:</p> <ul> <li>The minor version MUST be incremented when backwards (but not @@ -328,24 +327,19 @@ plugin.</li> compatibility at all, e.g. bug fixes or documentation updates.</li> </ul> -<p>Note there is deliberately no concept of a major version: all versions of an -LV2 resource with a given URI are by definition backwards compatible. More -precisely: replacing a resource with a newer version of that resource MUST NOT -break anything. If a change is made which breaks this rule, the URI -of the resource MUST be changed. In contexts where a full (e.g. <a -href="http://semver.org">SemVer</a> conformant) version number is required, the -major version of all released LV2 resources is 1.</p> +<p>Note there is deliberately no major version; all versions with the same URI +are compatible by definition. Replacing a resource with a newer version of +that resource MUST NOT break anything. If a change violates this rule, then +the URI of the resource (which serves as the major version) MUST be +changed.</p> -<p>Plugins and extensions MUST adhere to the following rules:</p> +<p>Plugins and extensions MUST adhere to at least the following rules:</p> <ul> <li>All versions of a plugin with a given URI MUST have the <q>same</q> set of mandatory (i.e. not lv2:connectionOptional) ports with respect to lv2:symbol -and rdf:type. In other words, every port on a specific version of a plugin has -a lv2:symbol and a set of rdf:types; all future versions of that plugin are -guaranteed to have a port with the same lv2:symbol and at least those -rdf:types. New types may be added only if doing so does not break -compatibility, i.e. if old hosts will continue to work correctly with the new -plugin.</li> +and rdf:type. In other words, every port on a particular version is guaranteed +to exist on a future version with same lv2:symbol and at least those +rdf:types.</li> <li>New ports MAY be added without changing the plugin URI if and only if they are lv2:connectionOptional and the minor version is incremented.</li> @@ -353,31 +347,27 @@ are lv2:connectionOptional and the minor version is incremented.</li> <li>The minor version MUST be incremented if the index of any port (identified by its symbol) is changed.</li> -<li>All versions of an extension MUST be compatible in the sense that an +<li>All versions of a specification MUST be compatible in the sense that an implementation of the new version can interoperate with an implementation of any previous version.</li> </ul> -<p>(Note these rules are not necessarily exhaustive)</p> - <p>Anything that depends on a specific version of a plugin (e.g. a serialisation that references ports by index) MUST refer to the plugin by both -URI and version. However, implementations should be tolerant and extensions +URI and version. However, implementations should be tolerant and extensions should be designed such that there is no need to do this (e.g. indices should only be meaningful for a particular plugin <em>instance</em> at run-time).</p> <p>When hosts discover several installed versions of a resource, they SHOULD warn the user and load only the most recent version.</p> -<p>An odd minor <em>or</em> micro version indicates that the resource is a -possibly unstable development version. Hosts and tools SHOULD clearly indicate -this wherever appropriate. Several versions of a resource with an odd version -may exist; i.e. it is acceptable to work on a development version of a resource -(e.g. in source control) without worrying about version numbers as long as -either the minor or micro version is odd.</p> - -<p>This property describes half of a resource version. See lv2:minorVersion -for the description of the other half.</p> +<p>An odd minor <em>or</em> micro version, or minor version zero, indicates +that the resource is a development version. Hosts and tools SHOULD clearly +indicate this wherever appropriate. Minor version zero is a special case for +pre-release development of plugins, or experimental plugins that are not +intended for stable use at all. Hosts SHOULD NOT expect such a plugin to +remain compatible with any future version. If possible, hosts SHOULD hide such +plugins from users unless an <q>experimental</q> option is enabled.</p> """ . lv2:microVersion -- cgit v1.2.1