======================= 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 libxslt, xsltproc Python Docutils (rst2html tool) Bugs, feature requests and to-do list ===================================== Report all errata, feature requests and "to-do" items here: 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: Telepathy development is supported by Collabora Ltd. . Hacking ======= The current development version of telepathy-spec is available from the 'master' branch in the git repository: (for committers) (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: