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.18.0 (2009-09-24)
==================================

This is a new stable version of telepathy-spec, intended to serve as a
reference point for future work. The D-Bus API is identical to 0.17.28
(the only changes were some improvements to the documentation tools, by wjt).

This spec version is supported by the upcoming 0.8.x stable branch of
telepathy-glib.

The versions of connection managers recommended for use with GNOME 2.28 and
Maemo 5 can be expected to support most of 0.18.0, with the notable exception
of ContactCapabilities (which was finished slightly too late). Connection
managers that support "most of" 0.18.0, except for ContactCapabilities, include:

* telepathy-gabble >= 0.8.0 (stable branch)
* telepathy-salut >= 0.3.10
* telepathy-sofiasip >= 0.5.18
* telepathy-haze >= 0.3.2
* telepathy-idle >= 0.1.5
* telepathy-butterfly >= 0.5.0

There have been many changes since the 0.16.0 stable release (almost two years
ago!), here's a summary:

Connection managers
-------------------

Significant API changes include:

* Several new calling conventions were introduced for StreamedMedia channels,
  while continuing to support everything that already worked. Details at:
  <http://telepathy.freedesktop.org/wiki/Requesting%20StreamedMedia%20channels>
* Channels are not guaranteed to be unique per (channel type, handle type,
  handle) triple, even if the handle type is nonzero
* Channel.Interface.Hold has changed considerably
* Text.SendError has different semantics (which match what was actually
  implemented in practice)
* GetKnownAvatarTokens' special behaviour for the self-handle has different
  semantics (which, again, match what was actually implemented)
* The allowed characters in connection manager and protocol names are
  explicitly specified to be a subset of what D-Bus would allow

New stable API includes, in no particular order:

* mandatory InitiatorHandle, InitiatorID and TargetID properties on all
  channels
* the mandatory Contacts interface on Connection, for round-trip reduction
  when inspecting batches of contacts
* the mandatory Requests interface on Connection, an extensible version of
  the old RequestChannel/ListChannels/NewChannel functionality with better
  sematics
* the SimplePresence interface on Connection, replacing Presence
* the ContactCapabilities interface on Connection, intended to replace
  Capabilities (not yet implemented in all connection managers, though)
* the Location interface on Connection, for geolocation
* StreamTube and DBusTube channels (one channel per tube), deprecating the
  Tubes channel type
* the FileTransfer channel type
* change notification for the self-handle (mainly for IRC)
* the Messages interface on Text channels, which supports extensible metadata,
  MIME-style attachments and alternatives, and extensible delivery-reports,
  and lays the foundations for future support for formatted messages
* the "rescued" and "scrollback" message flags
* removing the SelfHandle from a Group, a newly documented way to depart
  gracefully
* an optional CallState interface on StreamedMedia channels
* Hold support in MediaSignalling (and its related objects)
* the Busy presence type
* more well-known protocol names
* a Secret flag for CM parameters that represent a password, private key etc.
* CM parameters that are also D-Bus properties, and so can be changed by the
  account manager while remaining online
* the .manager file syntax (previously undocumented)
* D-Bus core Properties on several interfaces (most notably Group and Channel),
  for round-trip reduction
* Text channels that "respawn" when closed with unacknowledged messages, to
  avoid data loss on race conditions by behaving as if Close() had won the race
* the Destroyable interface, to circumvent the "respawn" mechanism and forcibly
  close a channel with possible data loss, intended for use by the
  ChannelDispatcher when no Handler can deal with a channel
* many new D-Bus error names
* the "stored" ContactList

Deprecations include:

* the Tubes channel type (use StreamTube and DBusTube instead)
* the Presence interface (use SimplePresence instead)
* RequestChannel, ListChannels and NewChannel (use Requests instead)
* handle = 0 in the Capabilities interface, which we never actually implemented
* passing clear=TRUE to Text.ListPendingMessages, which was never really safe

Account Manager
---------------

The new AccountManager service, and its AccountManager and Account objects,
replace part of the functionality of Mission Control 4's D-Bus and C API.

Mission Control 5.x provides a reference implementation of this service.

Channel Dispatcher
------------------

The new ChannelDispatcher service, and its ChannelDispatcher,
ChannelDispatchOperation and ChannelRequest objects, replace the rest of the
functionality of Mission Control 4's D-Bus and C API.

Again, Mission Control 5.x provides a reference implementation of this service.

Clients that handle channels are now expected to implement the Handler
interface, which replaces the ChannelHandler interface used by MC 4.

The concepts of Observers, Approvers and Handlers have been introduced,
together with common functionality in the Client interface. These describe
Telepathy clients which interact with channels, and can interact with the
ChannelDispatcher to provide user interfaces, logging and other functionality.

Tools and code generation
-------------------------

The canonical form of the HTML documentation generated from the XML spec is now
a multi-page document; the old single-page version is still generated, for now,
but expect it to be removed early in 0.19.

Unstable and experimental interfaces are explicitly marked as such. Various
existing interfaces that were never actually implemented have been marked as
experimental.

The spec is much more informative, with syntax for too much new stuff to
describe here.

telepathy-spec 0.17.28 (2009-09-14)
===================================

The "build your own desk" release.

New stable API:

* The ContactCapabilities interface is now considered to be stable, with the
  same semantics as in draft 2

* The InitialAudio and InitialVideo properties have been added to the
  StreamedMedia channel type, with the same semantics as the draft versions

* The ImmutableStreams property has been added to the StreamedMedia channel
  type, with minor changes to its semantics so it is better-defined (wjt)

* fd.o #23409: CallStates has an In_Progress state, similar to SIP 183
  Session Progress (mikhailz/smcv)

Additions to stable API:

* CreateChannel and EnsureChannel may raise PermissionDenied, for instance if
  a server refuses to perform a contact search (cassidy)

telepathy-spec 0.17.27 (2009-08-16)
===================================

The "goths in hot weather" release.

API changes:

* The D-Bus error equivalent of Name_In_Use is no longer considered to be
  NotYours; instead, we've split up the three cases, as new errors
  RegistrationExists, AlreadyConnected and ConnectionReplaced (smcv)

New stable API:

* The Location interface is now considered stable, with some changes to the
  set of known keys (smcv, pierlux, cassidy)
  - "language" has been added
  - "horizontal-error-m" is now called accuracy as per XEP-0080
  - "error" has been removed (it was in arc-minutes, which are a bizarre unit,
    and was deprecated in XEP-0080)
  - "climb", "vertical-error-m" and "accuracy-level" have been removed
  - "countrycode" is still there, despite its omission from XEP-0080; we've
    asked for its inclusion in the XEP

* The Debug interface is now considered stable, with no further changes

* New D-Bus errors: ResourceUnavailable, ServiceBusy, RegistrationExists,
  AlreadyConnected and ConnectionReplaced (smcv)

* New Media_Stream_Error codes: Codec_Negotiation_Failed, Connection_Failed,
  Network_Error, No_Codecs, Invalid_CM_Behavior, Media_Error (Tester)

* New well-known CM parameter: keepalive-interval (wjt)

* ConnectionManager explicitly allows byte ('y') parameters, serialized in
  .manager files as ASCII decimal numbers (smcv)

* ConnectionRefused etc. can be used as more specific versions of NetworkError
  when a Connection breaks (smcv)

* StreamedMedia channels have a new pseudo-capability Immutable_Streams,
  indicating that streams cannot be added or removed, for instance in calls
  using Google's Jingle variants (smcv)

* Each Handler has a new Capabilities property, listing "capability tokens"
  which will later be used by the ContactCapabilities interface; the
  MediaSignalling interface defines an initial set of capability tokens (smcv)

Deprecations:

* Media_Stream_Error_EOS never really made sense and is now deprecated (Tester)

Changes to experimental API:

* ContactCapabilities.DRAFT2 replaces the previous draft (smcv)
  - Handlers now have a list of capability tokens indicating supported
    transports, codecs etc., which cannot be expressed easily in terms of
    filters
  - As a result, the NAT traversal flags in MediaSignalling.FUTURE no longer
    exist, and that pseudo-interface has been removed
  - SetSelfCapabilities is replaced by UpdateCapabilities, which gives the
    CM a set of structs representing clients, and requires the CM to remember
    which client has which capabilities

* ContactSearch.DRAFT2 replaces the previous draft (cassidy)
  - SearchResultReceived now contains multiple rows

New experimental API:

* StreamedMedia.FUTURE.ImmutableStreams is similar to the Immutable_Streams
  pseudo-capability (wjt)

Tools and formatting:

* There is now specific markup for contact attributes and for handler
  capability tokens, and the spec tools have been extended to turn it into
  nice HTML (smcv)

telepathy-spec 0.17.26 (2009-06-09)
===================================

New stable API:

* ChannelDispatcher is finally declared to be stable, as is its optional
  OperationList interface. The ChannelDispatchOperation and ChannelRequest
  objects that it exports are also considered to be stable.

* The Client interface is also declared stable, along with client types
  Observer, Approver and Handler, and the optional Requests interface for
  Handlers.

Fixes:

* The punctuation used in naming the new errors from 0.17.25 has been
  corrected, meaning that code-generation tools will produce the right names
  (this change was already backported into the copies of telepathy-spec found
  in telepathy-glib and telepathy-qt4).

telepathy-spec 0.17.25 (2009-05-27)
===================================

The "75cl of Vino" release.

Changes to stable API:

* Socket_Access_Control_Credentials: the byte sent with the credentials is not
  guaranteed to be '\0' any more.

New stable API:

* Three new errors have been added: ConnectionRefused, ConnectionFailed and
  ConnectionLost. They will be used to report stream tube connection problems.

* Channel.Interface.Tube is now undrafted.

* Channel.Type.StreamTube is now undrafted with the following changes:
  - The access_control_param in the Offer method has been removed. It doesn't
    make any sense in that context.
  - The NewConnection signal has been renamed to NewRemoteConnection and gained
    two new arguments which are used to identify the connection.
  - The NewLocalConnection signal has been added. This is the equivalent of
    NewRemoteConnection on the accepting side.
  - The ConnectionClosed signal has been added to report tube connection
    problems.

* Channel.Type.DBusTube is now undrafted with the following changes:
  - The Offer and Accept methods now have an access_control argument used
    to choose the access control policy on the tube D-Bus server.
  - The channel now has a SupportedAccessControls D-Bus property containing
    the supported access control types.

Deprecations:

* Channel.Type.Tubes is now deprecated in favor of the new tube API.

* Socket_Access_Control_Netmask is now deprecated as it has never been
  implemented and doesn't really make sense.

telepathy-spec 0.17.24 (2009-05-07)
===================================

The "robot finds kitten" release.

Changes to stable API:

* fd.o #20905: Account.UpdateParameters now returns a list of the parameter
  changes that will not take effect until Reconnect is called.

* fd.o #19428: AccountManager.CreateAccount now additionally takes a map of
  properties to set on the new account immediately. CreateAccount fails without
  creating an account if these cannot be set.

Changes to experimental API:

* In new-style Tubes, OfferStreamTube, AcceptDBusTube etc. are just called
  Offer and Accept, since the interfaces are mutually exclusive; similarly,
  StreamTubeNewConnection is now just called NewConnection

New stable API:

* fd.o #20905: Account.Reconnect allows a UI to require that the Account be
  reconnected with a single method call.

* AccountManager.SupportedAccountProperties lists properties that can be passed
  to CreateAccount.

New experimental API:

* A new Debug interface allows debug logs from processes such as connection
  managers to be gathered by a UI. telepathy-gabble implements the current
  draft, and Empathy contains a client for it.

Clarifications:

* fd.o #19183: clarify the relationship between Requests.NewChannels and
  the deprecated RequestChannel method.

telepathy-spec 0.17.23 (2009-04-21)
===================================

The "the future is mandatory" release.

Changes to stable API:

* fd.o #14620: Connection.Connect is defined to be idempotent, matching what
  has always been implemented in practice. (smcv)

* All Connections must implement the Requests and Contacts interfaces, which
  are no longer considered optional. RequestChannel, ListChannels and listening
  for NewChannel are now deprecated. (smcv)

* All Connections that implement the deprecated Presence interface must also
  implement the non-deprecated SimplePresence interface; clients should not
  attempt to support the old Presence interface. (smcv)

Changes to experimental API:

* fd.o #21148: ChannelDispatcher, ChannelDispatchOperation, ChannelRequest,
  Client, Observer, Approver and Handler are considered to be a little less
  experimental. We don't yet recommend generating bindings for them in stable
  libraries, but hopefully they won't change much more now. Accordingly,
  the .DRAFT suffix has been removed. (smcv)

* fd.o #21180: Handler: added an a{sv} parameter to HandleChannels for future
  expansion. (smcv)

* fd.o #20908: Observer: added a Requests_Satisfied parameter to
  ObserveChannels. (smcv)

* fd.o #21093: Approver: altered AddDispatchOperation to pass the channels as
  a top-level argument, since the Channels property of the CDO is mutable (smcv)

* fd.o #21176: Handler: moved request notification to a new
  Client.Interface.Requests interface. (smcv)

Additions to stable API:

* CreateChannel and EnsureChannel may raise Offline. (wjt)

* fd.o #21109: added a Terminated error; Group change reason None is either
  Terminated or Cancelled, depending on the actor. (smcv)

* fd.o #20920: StreamedMedia: RequestStreams may raise NotImplemented and
  NotCapable, and should prefer them over InvalidArgument and NotAvailable.
  (smcv)

* fd.o #20920: Group: AddMember may raise NotCapable. (smcv)

* Accounts have a HasBeenOnline property. (smcv)

Additions to experimental API:

* fd.o #21013: ChannelRequest: added a PreferredHandler property. (smcv)

* fd.o #21180: ChannelRequest: added an Interfaces property. (smcv)

Clarifications:

* fd.o #21090: Approver: AddDispatchOperation is called for all channel
  dispatch operations where at least of the channels matches the filter. (smcv)

* fd.o #21089: Observer: ObserveChannels only sees channels that match the
  filter. (smcv)

* fd.o #21112: FileTransfer: clarified how RequestableChannelClasses and
  ContentHashType relate. (wjt)

* fd.o #21179: added some recommendations for a high-quality channel dispatcher   implementation. (smcv)

Tools:

* The new-style (multi-page) HTML output has a devhelp index and various
  visual improvements. (davyd, wjt)

* The new-style HTML spec is uploaded correctly. (smcv, wjt)

telepathy-spec 0.17.22 (2009-03-24)
===================================

The "remember that orange juice moves diagonally" release.

API changes:

* fd.o #20772: the implicit direction and state of new StreamedMedia streams
  has been clarified in a possibly incompatible way: CMs need to emit extra
  signals whenever a stream is added with state != Disconnected,
  direction != Receive or pending-send != Pending_Local_Send

* Reverted a change to RequestStreams that claimed that it should be
  idempotent, and explicitly documented the opposite

Changes to experimental API:

* In MediaSignalling.FUTURE, GoogleP2PTransportAvailable is now
  GTalkP2PTransportAvailable to be consistent with 'gtalk-p2p' NATTraversal,
  MSNTransportAvailable is now WLM85TransportAvailable, and
  WLM2009TransportAvailable has been added

* In MediaSignalling.FUTURE and StreamedMedia.FUTURE, removed strange fallback
  behaviour if no clients have any of the relevant capabilities, because
  clients wouldn't be able to rely on it

* In ContactSearch, extend the state machine to support paged searches, and
  rethink how paged/limited searches work

New API:

* fd.o #19558: Media.StreamHandler has new NATTraversal, STUNServers,
  CreatedLocally and RelayInfo properties which can be used to select
  a transport, and used by the transport to traverse NATs

* Media.StreamHandler documents two more NAT traversal methods, wlm-8.5 and
  wlm-2009

* Avatars now exposes avatar requirements as properties, and adds recommended
  sizes

Deprecations:

* MediaSignalling's nat-traversal, stun-server and stun-port Telepathy
  properties are deprecated in favour of per-stream D-Bus properties

* The 'stun' value for NATTraversal and nat-traversal is deprecated; 'none'
  and 'stun' should behave identically

Clarifications:

* StreamedMedia: clarified that removing all streams may close the channel,
  but that that isn't how clients should terminate calls

* StreamedMedia: documented and recommended Gabble's behaviour, which is that
  accepting calls automatically accepts the proposed direction for all streams

Tools:

* fd.o #20771: telepathy-spec now contains a new parser written in Python,
  and a new HTML rendering that uses it. Code generation tools will hopefully
  migrate to this parser in future.

  For the moment, both the old XSLT-generated HTML (one big file) and the
  new Python-generated HTML (multiple pages) are generated by telepathy-spec's
  Makefile.

telepathy-spec 0.17.21 (2009-03-17)
===================================

The "no new parser yet" release.

API changes:

* It is now explicitly stated that removing the SelfHandle from a Group is the
  recommended way to depart gracefully. All connection managers should allow
  this (telepathy-glib 0.7.27 will have the necessary support code in
  TpGroupMixin).

Changes to experimental API:

* In ContactInfo the vCard TYPE type-parameter is represented as, for instance,
  "type=work" rather than just "work", and other type-parameters such as
  "language" are supported using similar syntax

* Tube parameters for outgoing tubes are now set when offering the tube, not
  when requesting it

* Generic Tube capabilities should be advertised on protocols like XMPP even
  if no client supports a particular tube type, to reduce the "barrier to
  entry" for Tube apps

New API:

* The new Message_Depart flag in Channel_Group_Flags indicates whether a
  message can be provided when departing from a Group

* ice-udp is available as an additional value for MediaSignalling channels'
  nat-traversal Telepathy property, and NAT_Traversal_ICE_UDP is a new
  channel-type-specific capability for StreamedMedia channels

Deprecations:

* The old (complex) Presence interface is deprecated in favour of
  SimplePresence; new client code should use SimplePresence, and connection
  managers with Presence should implement SimplePresence as soon as possible

Clarifications:

* Setting a status of type Offline, Unknown or Error for yourself is explicitly
  forbidden

(Version 0.17.19 was mistakenly tagged as telepathy-spec-0.17.20, so 0.17.20
was not used as a release version to avoid confusion.)

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
  (fd.o #17974)

New experimental API:

* A preliminary design for audio, video and transport capabilities has been
  added to StreamedMedia.FUTURE and MediaSignalling.FUTURE
  (this will also address fd.o #17246, requesting initial audio/video streams,
  when it becomes stable)

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
  (closes fd.o #19613, will close #13350 when stable)

* 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 (fd.o #19610)

* 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
  (fd.o #14483)

* 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) (fd.o #16480)

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.
  (fd.o #15418, and partially addresses #14606)

  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
