This file contains the same edited highlights as the announcement emails.
For full details, see the ChangeLog in tarballs, or "git log" in Git
checkouts.

telepathy-spec 0.17.10 (2008-09-09)
===================================

The "brass plaque" release.

API changes:

* Text channels with any pending messages should "respawn" when closed (the
  channel is replaced by an incoming channel with the same incoming message
  queue). This avoids a race condition that could cause messages to be lost,
  by always behaving as though Close() had won the race.

* Connection bus names and object paths are now required to have exactly 7
  components, rather than at least 7, and Channel object paths are required
  to have their Connection's object path in the first 7 components.

* It is recommended that the account manager cannot be service-activated
  by using the Telepathy bus name. Clients can activate a particular
  implementation if they want to.

* Connection managers where the result of GetSelfHandle can change while
  in the CONNECTED state (Idle is the only known example) must emit the new
  SelfHandleChanged signal when this happens.

Deprecations:

* Passing suppress_handler=FALSE to RequestChannel is discouraged.

New API:

* Connection has a new SelfHandle property, which matches the result of
  GetSelfHandle and has change notification via the new SelfHandleChanged
  signal

* DBus_Error_Name and DBus_Well_Known_Name string types have been added
  in preparation for use in the ChannelDispatcher API. A Unix_Timestamp64 type
  has been added so we won't have to change the spec as 2038 approaches :-)

New experimental API:

Tools changes:

* doc-generator.xsl requires methods, signals and properties to have a
  tp:name-for-bindings attribute in Ugly_Case. This can be used by code
  generation tools to convert to languages' naming conventions (CamelCase,
  javaCamelCase, UPPER_CASE, lower_case) using tr(1) or XPath's translate().

Miscellaneous:

* There is now a better README, loosely based on the one in telepathy-glib

* Some of the things we do and don't consider to be API guarantees
  are now documented in README

* telepathy-spec is now maintained in git. See README for details.

telepathy-spec 0.17.9 (2008-08-15)
==================================

The "-otron" release.

API changes:

* The special behaviour of the self handle in GetKnownAvatarTokens has been
  changed to match what's actually been implemented; the spec now explains
  under what circumstances clients (or the account manager) should reset the
  avatar

New API:

* Connection.Interface.Aliasing.GetAliases is like RequestAliases but returns
  immediately, rather than waiting for network round-trips to complete

* Connection.Interface.Contacts (also known as "the inspectotron") allows
  retrieval of various contact attributes, and optionally holding the handles,
  in a single D-Bus round-trip. (Methods and properties have been renamed
  since the draft version, but it's basically the same)

New experimental API:

* The ChannelBundle interface is a new concept: an object path that relates
  a bundle of related channels, and remains in existence as long as any
  channel in the bundle exists

* The Requests interface ("the requestotron") is intended to replace
  RequestChannel when it's ready: it allows channels to be created by
  specifying an extensible hash table of D-Bus properties, rather than just
  a channel type and a handle

telepathy-spec 0.17.8 (2008-07-23)
==================================

The "more spec branches than brain cells" release.

API changes:

* Use of handle = 0 in the Capabilities interface, to denote "capabilities of
  the connection itself", is deprecated; it was never very clear what it meant,
  it's not sufficiently expressive to describe new API that we plan to add,
  and as far as I know, no connection manager implements it anyway.

New API:

* Connection.Interface.SimplePresence provides a simpler API for presence;
  the old presence API turned out to be far more complicated than we needed
  in practice

* ConnectionManager now has an Interfaces property for possible future
  expansion

New experimental API:

* Connection.Interface.Contacts (also known as "the inspectotron") allows
  retrieval of various contact attributes, and optionally holding the handles,
  in a single D-Bus round-trip (as usual, we plan to make this official once
  we've tried implementing it).

Miscellaneous:

* To avoid naming conflicts and general confusion, we explicitly recommend
  against naming connection managers after the protocol they implement, or
  after a library they use

Tools changes:

* doc-generator.xsl is a lot pickier about the spec's format, and will now
  fail on various sorts of invalid markup

* doc-generator.xsl recognises <tp:dbus-ref> (to reference a D-Bus interface,
  method, signal or property) and <tp:member-ref> (to reference a method,
  signal or property of the current interface)

Release notes for projects using doc-generator.xsl:

* You'll probably need to clean up your spec markup!

* Set the allow-undefined-interfaces XSLT parameter to a true value (e.g.
  run xsltproc with --param allow-undefined-interfaces "true()") if you are
  compiling documentation for interfaces that depend on a third-party spec
  (e.g. Telepathy extensions that reference the main Telepathy spec)

telepathy-spec 0.17.7 (2008-05-06)
==================================

The "propertifying the countryside" release.

API changes:

* The Channel interface now contains properties:

  - TargetHandleType/TargetHandle (the same thing that GetHandle returns),
    deprecating GetHandle
  - ChannelType (the same thing that GetChannelType returns), deprecating
    GetChannelType
  - Interfaces (the same thing that GetInterfaces returns), deprecating
    GetInterfaces

* Channels are no longer guaranteed unique per (channel type, handle type,
  handle) triple, even when the handle type is nonzero

New experimental API:

* The Channel.FUTURE interface contains functionality targeted for inclusion
  in the core Channel interface after we have some implementation experience:

  - TargetHandleID (the ID obtained by inspecting the TargetHandle)
  - InitiatorHandle (the initiator of the channel)
  - InitiatorID (the ID obtained by inspecting the InitiatorHandle)

Fixes:

* Correct various references to obsolete API
* Mark things that were added or deprecated in 0.17.6 as such, rather than
  saying "0.17.UNRELEASED"

Additional documentation:

* Lists of use-cases for future functionality have been added, and we've
  started to propose implementations for use in the future Requests API.
  Please discuss these on the Telepathy mailing list
  <mailto:telepathy@lists.freedesktop.org> or in #telepathy on
  irc.freenode.net, and see http://monkey.collabora.co.uk/
  for further use-cases and implementation proposals.

Notes to packagers:

* Compiling the dispatch/request use-cases to HTML requires rst2html
  from the Python docutils package (python-docutils in Debian and Fedora).

telepathy-spec 0.17.6 (2008-05-26)
==================================

The "GetAll()" release.

API changes:

* The core Account interface no longer has an Avatar property, so that clients
  can safely call GetAll for properties without flooding the bus with avatars

API additions:

* Group interface state is now in terms of properties, so you can use GetAll
  to get a full state snapshot:
  - Group.GroupFlags property (deprecating GetGroupFlags method)
  - Group.SelfHandle property and Group.SelfHandleChanged signal (deprecating
    GetSelfHandle method, and adding change-notification)
  - Group.HandleOwners property and Group.HandleOwnersChanged signal
    (deprecating GetHandleOwners method, and adding change-notification)
  - Group.LocalPendingMembers, Group.Members, Group.RemotePendingMembers
    properties (deprecating GetMembers, GetLocalPendingMembers,
    GetLocalPendingMembersWithInfo, GetRemotePendingMembers and GetAllMembers
    methods)
* Account.Interface.Avatar replaces the Account.Avatar property

Fixes:

* Messages, DeliveryReporting are correctly marked as experimental

Tools changes:

* Correctly pass through HTML attributes into the HTML spec
* Add markup <tp:type>Name_Of_Type</tp:type> which generates HTML links

telepathy-spec 0.17.5 (2008-05-21)
==================================

The "Channel.Type.Text 2.0 (beta)" release.

New experimental APIs:

* Channel.Interface.Messages: extensible version of Text with support for
  MIME-style attachments, alternatives, etc. and extensible metadata
* Channel.Interface.HTML: a brief sketch of how we intend to use Messages
  to get formatted message support in future (unfinished!)
* Channel.Interface.DeliveryReporting: an enhanced version of the Text
  interface's rather simplistic SendError signal

Clarifications:

* Make it completely clear that suppress_handler does NOT mean incoming vs
  outgoing channels
* Annotate a lot of changes with the version in which they were introduced

Tools changes:

* Show when things were added/changed/deprecated in the HTML spec

telepathy-spec 0.17.4 (2008-05-09)
==================================

API changes:

* Improve the Hold interface: instead of a boolean "held?" we now have
  a quad-state arrangement (unheld, held, trying to hold, trying to unhold)
  which turns out to be more useful for clients. This API has already been
  implemented as an extension in telepathy-gabble 0.7.3 and in
  telepathy-sofiasip 0.5.8.

API additions:

* Add the Enabled and NormalizedName properties to the Account interface

* The Hold interface is now marked as stable, please include it in bindings

Fixes:

* Explain the intended interaction between the Hold API presented to
  streaming clients (MediaStreamHandler), and signalling to the remote contact

* ListPendingMessages documentation shows up correctly in the HTML spec

Tools changes:

* Some simplifications in doc-generator.xsl

telepathy-spec 0.17.3 (2008-04-03)
==================================

The "please hold" release.

API changes:

* Change documented semantics of SendError to match what Gabble and Haze
  have always done: Send emits Sent when the message is submitted, or no
  signal on failure, and SendError is emitted *after* Sent if an error is
  detected later

* Explain that AcknowledgePendingMessages is where "message received"
  acknowledgements should be sent

* Some interfaces we've never actually implemented, which we do not believe
  are necessarily very well thought-out, have been removed from the HTML
  specification to reduce confusion:
  - ContactInfo (XML vCards over D-Bus... what were we thinking?)
  - ContactSearch (server-side searches like XEP-0055)
  - Forwarding (an incomplete implementation of call-forwarding in telephony)
  - Privacy (a much more complex version of the 'block' API)
  - Transfer (transferring contacts between calls in telephony)

* Whether other people have put us on hold is now signalled as a call state

* The scope of the Hold interface has been reduced; it now only manipulates
  whether we have put the call on hold, not whether other people have put
  us on hold (note that the Hold interface is still considered experimental,
  and it's likely to change in the next release)

API additions:

* Media.StreamHandler now has a SetStreamHeld signal to ask streaming clients
  (stream-engine) to release or acquire the necessary resources for media
  streaming, and HoldState and UnholdFailure methods so the streaming client
  can indicate success or failure; these can be used to implement the
  Hold interface

Deprecations:

* Passing clear=TRUE to ListPendingMessages (the client cannot guarantee that
  the messages will actually be shown to the user or logged, if this is done)

Tools changes:

* Allow arrays of mappings

* Allow rationale to be interleaved with HTML in docstrings

telepathy-spec 0.17.2 (2008-03-06)
==================================

Significant API changes:

* Alter usage of StreamedMedia channels to not abuse Group semantics,
  and allow better call state signalling - RequestStreams is now allowed on
  contacts not in the channel, and will add them to remote-pending state
  when an attempt has been made to contact them
* Explicitly say that clients must support CMs with no .manager file
  (telepathy-glib implements the required semantics, libtelepathy does not)
* Explicitly specify that IANA service names are valid and recommended
  for stream-tube service names (with dns-sd.org as a secondary source)
* Some avatar-related clarifications

New APIs:

* Add Account, AccountManager interfaces (a D-Bus API for the account
  management functionality in Mission Control)
* Add CallState interface (SIP 180 Ringing, 182 Queued, etc., or equivalent)
* Add Conn_Mgr_Param_Flag_Secret, a generic way to indicate passwords etc.
  in connection manager parameters

Tools changes:

* Support <tp:rationale> in docstrings
* Support D-Bus core Properties

telepathy-spec 0.17.1
=====================

* Add Channel.Interface.CallMerging for manipulating PBX, GSM, etc. multi-party
  conversations
* Channel.Interface.Hold is now per channel, not per member
* Document .manager files
* Document exactly how to form Connection and ConnectionManager bus names and
  object paths
* Connection manager names must now match [A-Za-z][A-Za-z0-9_]*
* Protocol names must now match [A-Za-z][A-Za-z0-9-]*
* More well-known protocol names (qq, sametime, myspace)
* Clarifications include:
  - avatars interface
  - Group.AddMembers() must not complain if you re-add people who're already
    present
  - clients shouldn't call MediaSessionHandler.Ready until they've connected
    to NewStreamHandler
* Tools and code generation:
  - spec format improvements to support other specs that reference this one
  - added ls-interfaces.xsl

telepathy-spec 0.17.0
=====================

* Add a "Busy" presence type, to align Telepathy with Mission Control
* Annotate unstable/deprecated interfaces likely to cause havoc in APIs
* Annotate types of just about everything
* Name structure etc. types for easy reference
* Add ChannelHandler, which is used by Nokia's Mission Control