summaryrefslogtreecommitdiff
path: root/README
blob: f44a0191abb03520f3097773b9d02ba1bfcf03e4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
=======================
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
====================

[Telepathy 1.0 has not yet been released, so this policy does not apply yet.]

The following changes are considered to be an API break, and will not be made
in released interfaces unless the interface's name is also changed, usually by
incrementing the version number at the end.

* 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.)
* Changing the name attribute of the <node> XML element

We do *not* consider the following changes to be an API break, and reserve the
right to make them at any time, without changing the interface name.
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.

Core interfaces such as Channel, Connection and Account do not have a version
number at the end. Incompatible changes to these interfaces will only be made
in a new major version of telepathy-spec (which would rename all interfaces
by replacing im.telepathy1 with im.telepathy2 throughout).

The "node name" (name attribute of the <node> XML element) reflects the name
and version of the interface, and the intended naming for generated code:
for instance, <node name="/Channel_Interface_Subject1"> can generate
functions, constants etc. whose names contain channel_interface_subject1,
ChannelInterfaceSubject1, channelInterfaceSubject1 or
CHANNEL_INTERFACE_SUBJECT1, as appropriate for the relevant language's naming
conventions. The "node name" should always correspond to the filename of the
XML.

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>