From 71dae4f29121d769c25ea8164432c5b76b6aab45 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 4 Mar 2011 23:14:39 +0000 Subject: New definition of versions. --- core.lv2/lv2.ttl | 126 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 82 insertions(+), 44 deletions(-) diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl index c1f1a68..6fd80be 100644 --- a/core.lv2/lv2.ttl +++ b/core.lv2/lv2.ttl @@ -326,58 +326,96 @@ lv2:port a rdf:Property ; rdfs:label "port" ; rdfs:comment "Relates a Template or Plugin to the Ports it contains" . -lv2:revision a rdf:Property ; +lv2:minorVersion a rdf:Property ; rdfs:domain lv2:Resource ; - rdfs:range xsd:string ; - rdfs:label "revision" ; - lv2:documentation """ -

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.

- -

An LV2 revision is a string conforming to the SemVer 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".

- -

All LV2 plugins and extensions SHOULD have an explicit revision. The -revision property of a Plugin or Specification MUST be located in the -manifest.ttl 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 compatible resource, not to distinguish -incompatible successors of a resource. More precisely:

+ rdfs:range xsd:nonNegativeInteger ; + rdfs:label "minor version" ; + lv2:documentation """ +

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.

+ +

The version of an LV2 resource is composed of two fields: minor version, +and micro version. These have the usual semantics:

+ + + +

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, a new version of a resource MUST be able to replace an older version +without breaking 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. SemVer conformant) version number is required, the +major version of all released LV2 resources is 1.

+ +

Plugins and extensions must adhere to the following rules:

-

This list may not exhaustively cover all cases. In general the rule is: -replacing a resource with a new revision must not break anything.

+

These rules are an attempt to rigorously define the necessary best +practices, but may not exhaustively cover all cases. In general the rule is: +replacing a resource with a new version of that resource MUST NOT break +anything.

-

A resource with no revision may be considered to have revision 0.

+

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 +should be designed such that there is no need to do this (e.g. indices should +only be meaningful for a particular plugin instance at run-time).

-

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.

+

When hosts discover several installed versions of a resource, they SHOULD +warn the user and load only the most recent version.

-

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).

""" . +

This property describes half of a resource version. See also lv2:minorVersion, the +property which describes the other half.

+""" . + +lv2:microVersion a rdf:Property ; + rdfs:domain lv2:Resource ; + rdfs:range xsd:nonNegativeInteger ; + rdfs:label "micro version" ; + lv2:documentation """ +

The micro component of a Resource's version.

+ +

An odd micro version indicates that the resource is a possibly unstable +development version. Hosts and tools SHOULD clearly indicate this wherever it +makes to do so.

+ +

Correct version numbers MUST always be maintained for published +resources. For example, after a release, if a change is made in the development +version in source control, the micro revision MUST be incremented (to an odd +number) to distinguish this modified version from the previous release.

+ +

This property describes half of a resource version. For detailed +documentation on LV2 resource versioning, see lv2:minorVersion. +""" . lv2:binary a rdf:Property ; rdfs:domain lv2:Resource ; -- cgit v1.2.1