Attachment 57093 Details for Bug 26866 – Describe our policy on versioned interfaces

[patch] Describe our policy on versioned interfaces

0001-Describe-our-policy-on-versioned-interfaces.patch (text/plain), 2.96 KB, created by Simon McVittie on 2012-02-15 05:32:30 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2012-02-15 05:32:30 UTC

Size: 2.96 KB

patch

obsolete

>From f98885d690c542576c957c4f931cfcb19a23497a Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Wed, 15 Feb 2012 13:31:47 +0000
>Subject: [PATCH] Describe our policy on versioned interfaces
>
>---
> README |   41 +++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 41 insertions(+), 0 deletions(-)
>
>diff --git a/README b/README
>index e99e967..a3d5dfb 100644
>--- a/README
>+++ b/README
>@@ -67,6 +67,47 @@ a way that will not break if we do these:
> If any changes not mentioned here would break your library's API and you want
> us to avoid them, please ask for clarification on the mailing list.
> 
>+Policy on versioned interfaces
>+==============================
>+
>+Some newer Telepathy interfaces have a version number, e.g. Subject2.
>+These interfaces follow the following rules:
>+
>+If the interface has the tp:causes-havoc attribute, it is considered to be
>+a draft. Incompatible changes will cause the version number to be
>+incremented, but will not change the "node name" (the name attribute on the
>+node XML element, used to name generated code) or the filename (which should
>+always correspond to the node name). For instance, if Foo1 was never
>+considered stable, then Foo1 and Foo2 would both have node name /Foo.
>+Stable libraries should not expose these interfaces as API.
>+
>+If an interface with the tp:causes-havoc attribute is considered to be
>+stable without further incompatible changes, that attribute will be removed,
>+at which point that interface may be included in stable libraries as described
>+below. Implementations of the last draft version and the final version will
>+interoperate, since the interface name is the same; this is the
>+version-numbering scheme's major advantage over the older convention of
>+a .DRAFT suffix, in which case the last draft version could never interoperate
>+with the final version despite being identical.
>+
>+If the interface does not have the tp:causes-havoc attribute, it is
>+considered to be stable. Incompatible changes will not be made, and such
>+interfaces can be included in a stable library, using the node name as
>+the basis for code generation. For instance, Chan.I.Subject2 has node name
>+/Channel_Interface_Subject, and generates code like
>+TpSvcChannelInterfaceSubject in telepathy-glib.
>+
>+If a stable interface is found to require incompatible changes, it will be
>+deprecated instead, and the incompatible changes will be made in a new copy
>+of that interface with a higher version number. This time, the node name
>+does have to include the version number, so that stable libraries which
>+already committed to generating code for the old version can continue to
>+do so, while also generating code for the new version. For instance,
>+now that Chan.I.Subject2 is considered stable, if we make incompatible
>+changes (leading to Chan.I.Subject3), the new version will have node name
>+/Channel_Interface_Subject3, and hence generate code like
>+TpSvcChannelInterfaceSubject3 in telepathy-glib.
>+
> Contact info
> ============
> 
>-- 
>1.7.9
>

Actions: View | Splinter Review

Attachments on bug 26866: 57036 | 57037 | 57093

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.