=======================
Telepathy specification
=======================

telepathy-spec is the canonical description of the Telepathy D-Bus API,
on which all other Telepathy projects are based.

Telepathy is a D-Bus framework for unifying real time communication,
including instant messaging, voice calls and video calls. It abstracts
differences between protocols to provide a unified interface for
applications.

Requirements
============

Building HTML documentation for telepathy-spec requires:
  GNU make <http://www.gnu.org/software/make/>
  libxslt, xsltproc <http://xmlsoft.org/XSLT/>
  Python <http://www.python.org/>
  Docutils (rst2html tool) <http://docutils.sourceforge.net/>

Bugs, feature requests and to-do list
=====================================

Report all errata, feature requests and "to-do" items here:
  <https://bugs.freedesktop.org/enter_bug.cgi?product=Telepathy&component=telepathy-spec>

API stability policy
====================

We use an "odd/even" versioning scheme where the minor version (the y in
x.y.z) determines stability - stable branches have y even, development
branches have y odd.

The following interfaces can change at any time, so please do not include them
in libraries:

* interfaces whose names end with .DRAFT or .FUTURE
* interfaces with the tp:causes-havoc attribute

Otherwise, we will not make the following changes in a stable branch, and we
avoid them where possible even in development branches:

* Removing or renaming methods, signals or properties
* Changing the D-Bus type signature of a method or signal's arguments
* Changing the D-Bus type signature or access (can be read/can be written)
  of a property
* Removing or renaming types (tp:struct etc.)
* Changing the D-Bus type signature of a type (tp:struct etc.)

We do *not* consider the following changes to be an API break, and reserve the
right to make them at any time. Telepathy libraries/bindings should be done in
a way that will not break if we do these:

* Adding new methods or properties
* Adding new signals, if that does not make old connection managers (that will
  never emit those signals) fail to comply with the spec
* Changing the name of a method or signal argument, or giving it a name if
  it did not previously have one
* Adding new types (tp:enum, tp:struct etc.)
* Adding new members to the end of a tp:enum or tp:flags
* Changing the tp:type of a property or argument, or adding a tp:type if it
  did not already have one (as long as the D-Bus signature remains the same)
* Documenting methods to possibly raise new exceptions (any method can raise
  any exception, and client code should always cope)

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
============

This specification is maintained by the Telepathy project:
  <http://telepathy.freedesktop.org/>
  <mailto:telepathy@lists.freedesktop.org>
  <irc://irc.freenode.net/telepathy>

Telepathy development is supported by Collabora Ltd.
  <http://www.collabora.co.uk/>.

Hacking
=======

The current development version of telepathy-spec is available from the
'master' branch in the git repository:
  <git://git.collabora.co.uk/git/telepathy-spec.git>
  <git+ssh://git.collabora.co.uk/git/telepathy-spec.git> (for committers)
  <http://git.collabora.co.uk/?p=telepathy-spec.git> (gitweb)

Stable branches are available from branches with names like
'telepathy-spec-0.16' in the same repository.

Proposed patches awaiting review can usually be found in the freedesktop.org
bugzilla with the ‘patch’ keyword, which can be listed using the following
formidible URL:
  <https://bugs.freedesktop.org/buglist.cgi?keywords=patch&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=tp-spec&product=Telepathy>