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.19 (2009-01-28)
===================================

The "out of cheese error" release.

Changes to experimental API:

* Tube.Status is now called Tube.State to be more consistent

New API:

* Many new errors: NotCapable (a more specific form of NotAvailable),
  and D-Bus error forms of all the Connection disconnection reasons and
  all the error-like Group change reasons: Offline, Channel.Kicked,
  Busy, DoesNotExist, NoAnswer, AuthenticationFailed, EncryptionNotAvailable,
  EncryptionError, Cert.NotProvided, Cert.Untrusted, Cert.Expired,
  Cert.NotActivated, Cert.FingerprintMismatch, Cert.HostnameMismatch,
  Cert.SelfSigned, Cert.Invalid

* ConnectionError, a signal which can emit extensible error information
  from the Connection just before StatusChanged(Disconnected, ...) is signalled

New experimental API:

* A preliminary design for audio, video and transport capabilities has been
  added to StreamedMedia.FUTURE and MediaSignalling.FUTURE

Clarifications:

* The reason for the SelfHandle being removed from a Group before a channel
  closes can be taken to be the error that the channel closed.
  (telepathy-glib already had this interpretation.)

Tools:

* It is now possible to have hyperlinks (or other HTML with attributes)
  in the specification markup format

telepathy-spec 0.17.18 (2009-01-20)
===================================

The "telekinesis" release.

API changes:

* Unix_Timestamp64 is now a signed 64-bit integer, not unsigned as it was
  previously. In practice this shouldn't cause problems, as it only appeared
  in variants, where implementations should be lenient about types in any case.

* Changed the tp:name-for-bindings annotation on the Tubes channel type to
  match what telepathy-glib historically generated, meaning that when
  telepathy-glib code generation changes to use this annotation in 0.7.23,
  it will not break ABI. (The only binding using tp:name-for-bindings so far
  is telepathy-qt4, which is not ABI-stable yet anyway, so this change seems
  unlikely to break things.)

Changes to experimental API:

* Improve the DBusTube interface: use maps (handle → D-Bus name) rather than
  lists of structs for D-Bus names, make OfferDBusTube return the address that
  will be used, remove GetDBusTubeAddress as a result, and turn GetDBusNames
  into a property

New API:

* The FileTransfer channel type is now considered stable (much rejoicing)

* A new type has been added, Rich_Presence_Access_Control, for use by
  rich presence interfaces like Location

New experimental API:

* Replaced the old ContactInfo interface with a much-improved draft

* Added the Location interface, hopefully the first of several "rich presence"
  interfaces

Deprecations:

* MediaStreamHandler.RemoveRemoteCandidate is deprecated: it seemed like a
  good idea at the time, but turned out not to be useful

* SetStreamPlaying with argument FALSE is basically meaningless, and is now
  deprecated

Miscellaneous:

* Sorted out the possible errors for RequestHandles, hopefully for the last
  time

* Some clarifications to MediaStreamHandler

* Added names for all 'out' parameters and made doc-generator.xsl warn
  whenever this has not been done

telepathy-spec 0.17.17 (2009-01-06)
===================================

The "why is ³ a NameChar, but not ²?" release.

New API:

* Added Handle_Identifier_Map, an a{us} mapping handles to identifiers, and
  a "contact-ids" detail of that type in the MembersChangedDetailed signal
  (for round-trip reduction)

* In the Messages interface, Message_Part_Index and Message_Part_Content_Map
  now have explicit types

* RequestHandles can now raise NotImplemented

Spec markup enhancements:

* Container types have an array-depth attribute indicating how deeply nested
  an array of arrays ... of the type can sensibly be; the only use so far
  is Message_Part, which can have an array depth of 2 (Message_Part[][])

Clarifications:

* The Requested property MUST NOT be accepted by CreateChannel, EnsureChannel
  (it would make no sense)

* The Members_Changed_Detailed flag on groups MUST NOT change during the
  channel's lifetime

* clarify the role of the Display_Name parameter to
  AccountManager.CreateAccount

telepathy-spec 0.17.16 (2008-12-12)
===================================

The "alban-enhanced-contact-capabilities-with-complex-types-but-no-cup-of-coffee-because-wjt-is-trying-to-give-up" release.

API changes:

* Avatar tokens are now required to make the triple (connection manager name,
  protocol, token) unique.

  Previously, the triple (our account, their identifier, token) was required
  to be unique, but this would require every avatar cache implementation to
  be aware of a persistent identifier for the account.

Changes to experimental API:

* ChannelDispatcher: CreateChannel MUST return before AddRequest is called

* Observer: give the ChannelDispatchOperation, if any, to ObserveChannels

New API:

* The MembersChangedDetailed signal on the Group interface indicates change
  metadata in an extensible way, including an optional D-Bus error name

* The Messages interface introduced in 0.17.5 is finally considered to be
  stable, and libraries should generate bindings for it

* Connection manager parameters with the new flag
  Conn_Mgr_Param_Flag_DBus_Property are D-Bus properties on the Connection,
  and the AccountManager SHOULD write changes through to the Connection when
  they are changed

* 'as' (string array) connection manager parameters can now have a default
  value in a .manager file

New experimental API:

* ContactCapabilities is intended to replace Capabilities, providing greater
  extensibility

Fixes:

* Many improvements to cross-references, including a fix for fd.o #18219

* In Requests.CreateChannel, the request MUST include ChannelType

* In StreamedMedia, describe Requests semantics

Miscellaneous:

* `make upload-branch` tries to name the HTML upload after the current git
  branch, and prints a possible URL (which is correct if the local username
  is the same as the fd.o username)

telepathy-spec 0.17.15 (2008-11-21)
===================================

The "new shipment of groove" release.

API changes:

* Account.Nickname is now of type 's', rather than the meaningless 'as'.
  This matches what was actually implemented in Mission Control 5.

API additions:

* Introduce the Avatar type (a struct containing a byte array and a MIME type)
  and use it on the Account.Interface.Avatar.Avatar property

Changes to experimental API:

* Add the sending flags that were in effect to the MessageSent signal, so
  Observers can tell whether a delivery report was requested

* Incoming Messages SHOULD always have a message-received timestamp

Additions to experimental API:

* Messages: add delivery-dbus-error, delivery-dbus-error-message

* Add the Account property to ChannelRequest objects (passed straight through
  from CreateChannel and EnsureChannel)

* Add Channel.Type.FileTransfer, a channel used to send a single file to a
  contact

* Add Channel.Type.StreamTube and Channel.Type.DBusTube, the new "one
  channel per tube" version of Tubes

* Add a use-case description for a channel closing while undispatched

Fixes:

* Many enhancements to cross-references and other minor corrections

telepathy-spec 0.17.14 (2008-10-30)
===================================

The "down with the sickness" release.

API changes:

* CreateChannel and (if a new channel is created) EnsureChannel are now
  guaranteed to return before NewChannels announces the channel (previously
  it was the other way round)

* NewChannels is now guaranteed to be emitted before NewChannel

Changes to experimental API:

* DeliveryReporting is no longer a separate interface - it's been incorporated
  into Messages. As a result, delivery reports no longer have the 'interface'
  key in their header part, and are only distinguished by their 'message-type'

* The meaning of Messages.MessagePartSupportFlags has been altered to remove
  the redundant Data_Only flag, which should in practice always have been set.
  The following equivalence holds:

    old_value = (new_value * 2) + 1
    new_value = floor(old_value / 2)

* The 'type' key in message parts is now called 'content-type' and there is
  now a 'message-token' in the header part

* Messages.SendMessage is now required to return before Messages.MessageSent
  is emitted; previously the order was unspecified

New API:

* The Destroyable interface is now considered stable, and Text channels
  SHOULD implement it

* Text.Send SHOULD return before Text.Sent is emitted

* Channel_Text_Message_Flag_Scrollback (or 'scrollback' in the Messages
  header) indicates an incoming message that is a replay of a message from
  the past, e.g. when joining an XMPP MUC or an IRC proxy that records backlog

* Channel_Text_Message_Flag_Rescued (or 'rescued' in the Messages header)
  indicates an incoming message that has already been seen on this Connection,
  and was transferred to a new copy of a channel when that channel was
  closed with the message still unacknowledged

* The 'stored' ContactList indicates all the contacts stored in a persistent
  contact list on the server (e.g. the XMPP roster), and is not present at all
  if there is no such list (e.g. in SIP presence)

telepathy-spec 0.17.13 (2008-10-13)
===================================

The "from the future" release.

API changes:

* The Account.Connection property is now an object path, or '/' for none.

* Connection managers with the Requests interface must include the new
  Requested property in the channel details.

New API:

* Requested, InitiatorHandle and InitiatorID have been added to the Channel
  interface as stable API.

Fixes in experimental API:

* ChannelDispatchOperation.ChannelLost now gets the object path of the lost
  channel.

* When approvers start up, they are given all existing matching
  ChannelDispatchOperations

telepathy-spec 0.17.12 (2008-09-26)
===================================

The "drilling holes in walls" release.

New API:

* Added EnsureChannel to the Requests interface. This returns an existing
  channel if possible, or creates a new channel otherwise; it also makes
  sure that only one caller considers itself to be responsible for
  dispatching or handling the new channel.

* Added new errors Cancelled and NotYours to support the ChannelDispatcher.

* Added a Forwarded flag to Channel.Interface.CallState

New experimental API:

* Added the Client and ChannelDispatcher machinery. The ChannelDispatcher
  is a central service dependent on the AccountManager (in practice, it will
  usually be in the same process) which provides functionality for requesting
  channels, and is also responsible for dispatching channels to appropriate
  clients. The Client interface is used to discover appropriate clients.

  When finished, this will supersede the ChannelHandler interface for clients,
  and Mission Control 4's D-Bus API.

* Added a Destroyable interface so the channel dispatcher has a way to
  kill off unhandleable channels (e.g. if we don't have a Text UI for some
  reason)

Miscellaneous:

* doc/*.txt contain various thoughts about use cases for new functionality,
  which provide further rationale for why the ChannelDispatcher is so
  complicated :-)

telepathy-spec 0.17.11 (2008-09-12)
===================================

The "release the global implementor lock" release.

New API:

* Connection.Interface.Requests has been declared to be stable.

  The EnsureChannel method introduced by Simon's dispatcher-clients branch has
  not yet been added, but will be added in a future spec release.

Fixes:

* Account.Interface.Avatar (introduced in 0.17.6) is now included in the HTML
  spec.

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 :-)

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