Bug 49400

Summary: add GLib-2.32-style deprecation macros
Product: Telepathy Reporter: Simon McVittie <smcv>
Component: tp-glibAssignee: Simon McVittie <smcv>
Status: RESOLVED FIXED QA Contact: Telepathy bugs list <telepathy-bugs>
Severity: enhancement    
Priority: medium CC: guillaume.desmottes, xclaesse
Version: git masterKeywords: patch
Hardware: Other   
OS: All   
Whiteboard:
i915 platform: i915 features:
Attachments: 1/9] Add GLib 2.32-style deprecation macros
2/9] Ignore deprecation of TpChannelFactoryIface when calling its methods
3/9] Use _TP_DEPRECATED_IN_* for most deprecated functions
4/9] Stop using TP_ERRORS
5/9] Emit deprecation warnings for TP_ERRORS
6/9] Get rid of the last few references to TpIntSet (it's now TpIntset)
7/9] Deprecate TpIntSet, TpIntSetIter and TpIntSetFastIter
8/9] tp_connection_dispose: use the fast version of int-set iteration
9/9] Deprecate the slow version of TpIntset iteration
10/15] Allow defs.h to contain UNRELEASED
11/15] Add a _TP_AVAILABLE_IN_UNRELEASED macro for use in unmerged branches
12/15] Fix earliest-required-version checking: I only went back to 0.16
13/15] Fix defaults for TP_VERSION_MIN_REQUIRED, TP_VERSION_MAX_ALLOWED
14/15] Fix computation of CUR_STABLE, PREV_STABLE for nearly-0.19 (0.18.999.1)
15/15] Version-annotate recent API

Description Simon McVittie 2012-05-02 12:37:50 UTC
Everyone likes deprecating stuff, right?
Comment 1 Simon McVittie 2012-05-02 12:38:16 UTC
Created attachment 60921 [details] [review]
1/9] Add GLib 2.32-style deprecation macros
Comment 2 Simon McVittie 2012-05-02 12:38:34 UTC
Created attachment 60922 [details] [review]
2/9] Ignore deprecation of TpChannelFactoryIface when calling  its methods

TpBaseConnection has to support it for backwards compatibility.
Comment 3 Simon McVittie 2012-05-02 12:38:52 UTC
Created attachment 60923 [details] [review]
3/9] Use _TP_DEPRECATED_IN_* for most deprecated functions

Also make use of TP_DISABLE_DEPRECATED consistent: always wrap
deprecated functions, and add deprecation decorators to any wrapped
function.
Comment 4 Simon McVittie 2012-05-02 12:39:22 UTC
Created attachment 60924 [details] [review]
4/9] Stop using TP_ERRORS

We deprecated this in 0.11.

---

(but it just won't die)
Comment 5 Simon McVittie 2012-05-02 12:39:34 UTC
Created attachment 60925 [details] [review]
5/9] Emit deprecation warnings for TP_ERRORS
Comment 6 Simon McVittie 2012-05-02 12:39:47 UTC
Created attachment 60926 [details] [review]
6/9] Get rid of the last few references to TpIntSet (it's now  TpIntset)
Comment 7 Simon McVittie 2012-05-02 12:40:19 UTC
Created attachment 60927 [details] [review]
7/9] Deprecate TpIntSet, TpIntSetIter and TpIntSetFastIter
Comment 8 Simon McVittie 2012-05-02 12:40:36 UTC
Created attachment 60928 [details] [review]
8/9] tp_connection_dispose: use the fast version of int-set  iteration

There's no good reason why we want to iterate in order.
Comment 9 Simon McVittie 2012-05-02 12:40:54 UTC
Created attachment 60929 [details] [review]
9/9] Deprecate the slow version of TpIntset iteration
Comment 10 Guillaume Desmottes 2012-05-03 00:27:32 UTC
*** Bug 47040 has been marked as a duplicate of this bug. ***
Comment 11 Guillaume Desmottes 2012-05-03 00:28:30 UTC
Comment on attachment 60921 [details] [review]
1/9] Add GLib 2.32-style deprecation macros

Review of attachment 60921 [details] [review]:
-----------------------------------------------------------------

++
Comment 12 Guillaume Desmottes 2012-05-03 00:29:05 UTC
Comment on attachment 60922 [details] [review]
2/9] Ignore deprecation of TpChannelFactoryIface when calling  its methods

Review of attachment 60922 [details] [review]:
-----------------------------------------------------------------

Are we getting rid of this in 'next'?
Comment 13 Guillaume Desmottes 2012-05-03 00:30:35 UTC
Comment on attachment 60923 [details] [review]
3/9] Use _TP_DEPRECATED_IN_* for most deprecated functions

Review of attachment 60923 [details] [review]:
-----------------------------------------------------------------

::: telepathy-glib/account-channel-request.h
@@ +72,4 @@
>  gint64 tp_account_channel_request_get_user_action_time (
>      TpAccountChannelRequest *self);
>  
> +#ifndef TP_DISABLE_DEPRECATED

Do we really still need TP_DISABLE_DEPRECATED? It doesn't seem that much useful with these macros; maybe we can drop it in next.
Comment 14 Guillaume Desmottes 2012-05-03 00:30:56 UTC
Comment on attachment 60924 [details] [review]
4/9] Stop using TP_ERRORS

Review of attachment 60924 [details] [review]:
-----------------------------------------------------------------

++
Comment 15 Guillaume Desmottes 2012-05-03 00:31:19 UTC
Comment on attachment 60925 [details] [review]
5/9] Emit deprecation warnings for TP_ERRORS

Review of attachment 60925 [details] [review]:
-----------------------------------------------------------------

++
Comment 16 Guillaume Desmottes 2012-05-03 00:31:49 UTC
Comment on attachment 60926 [details] [review]
6/9] Get rid of the last few references to TpIntSet (it's now  TpIntset)

Review of attachment 60926 [details] [review]:
-----------------------------------------------------------------

++
Comment 17 Guillaume Desmottes 2012-05-03 00:32:28 UTC
Comment on attachment 60927 [details] [review]
7/9] Deprecate TpIntSet, TpIntSetIter and TpIntSetFastIter

Review of attachment 60927 [details] [review]:
-----------------------------------------------------------------

++
Comment 18 Guillaume Desmottes 2012-05-03 00:32:46 UTC
Comment on attachment 60928 [details] [review]
8/9] tp_connection_dispose: use the fast version of int-set  iteration

Review of attachment 60928 [details] [review]:
-----------------------------------------------------------------

++
Comment 19 Guillaume Desmottes 2012-05-03 00:33:21 UTC
Comment on attachment 60929 [details] [review]
9/9] Deprecate the slow version of TpIntset iteration

Review of attachment 60929 [details] [review]:
-----------------------------------------------------------------

++
Comment 20 Guillaume Desmottes 2012-05-03 00:34:24 UTC
We should at least annotate the new 0.19 API for MAX_ALLOWED.

Btw, would it be possible to raise an error during 'make check' if a new API is added without its version annotation?
Comment 21 Simon McVittie 2012-05-03 03:23:52 UTC
(In reply to comment #12)
> 2/9] Ignore deprecation of TpChannelFactoryIface when calling  its methods
...
> Are we getting rid of this in 'next'?

It already went away.

(In reply to comment #13)
> Do we really still need TP_DISABLE_DEPRECATED?

It's the only way to "deprecate" macros (and typedefs/enums, unless we add a gcc-specific version of _TP_DEPRECATED_IN_x_y), and it seems sensible to make it act on everything.

_TP_DEPRECATED and _TP_DEPRECATED_IN_x_y (and the GLib macros they're based on) are portable (to at least MSVC), but have to appear before a function; they can't appear after, and can't go on typedefs or enums or whatever.

(In MSVC they're implemented as __declspec(deprecated) or something, which can only appear on extern symbols - ABI, not API.)

_TP_GNUC_DEPRECATED (and the GLib macro it's based on) is gcc-only, but more flexible.

None of those work on macros, because macros are expanded before the compiler gets involved.

(In reply to comment #20)
> We should at least annotate the new 0.19 API for MAX_ALLOWED.

Yes. May I merge this lot first?

> Btw, would it be possible to raise an error during 'make check' if a new API is
> added without its version annotation?

I can't think of an easy way to do so. I don't want to write yet another semi-working C parser (we run two of those already, in gtk-doc and g-i).
Comment 22 Guillaume Desmottes 2012-05-03 04:04:32 UTC
(In reply to comment #21)
> (In reply to comment #20)
> > We should at least annotate the new 0.19 API for MAX_ALLOWED.
> 
> Yes. May I merge this lot first?

Sure, go for it.

> > Btw, would it be possible to raise an error during 'make check' if a new API is
> > added without its version annotation?
> 
> I can't think of an easy way to do so. I don't want to write yet another
> semi-working C parser (we run two of those already, in gtk-doc and g-i).

Yeah I was suspecting that. :\


Looks good to me.
Comment 23 Simon McVittie 2012-05-03 04:46:04 UTC
Created attachment 60961 [details] [review]
10/15] Allow defs.h to contain UNRELEASED

---

This will be needed for the _TP_AVAILABLE_IN_UNRELEASED macro. We can use the usual "grep for UNRELEASED" to replace that with _TP_AVAILABLE_IN_0_20 before release.
Comment 24 Simon McVittie 2012-05-03 04:46:27 UTC
Created attachment 60962 [details] [review]
11/15] Add a _TP_AVAILABLE_IN_UNRELEASED macro for use in  unmerged branches
Comment 25 Simon McVittie 2012-05-03 04:46:43 UTC
Created attachment 60963 [details] [review]
12/15] Fix earliest-required-version checking: I only went  back to 0.16
Comment 26 Simon McVittie 2012-05-03 04:46:58 UTC
Created attachment 60964 [details] [review]
13/15] Fix defaults for TP_VERSION_MIN_REQUIRED,   TP_VERSION_MAX_ALLOWED
Comment 27 Simon McVittie 2012-05-03 04:47:17 UTC
Created attachment 60965 [details] [review]
14/15] Fix computation of CUR_STABLE, PREV_STABLE for  nearly-0.19 (0.18.999.1)
Comment 28 Simon McVittie 2012-05-03 04:48:16 UTC
Created attachment 60966 [details] [review]
15/15] Version-annotate recent API

---

I mostly believed the Since: annotations, although I did fix a couple that were clearly wrong (TpDBusChannel and tp_account_dup_storage_specific_information_vardict_finish).
Comment 29 Xavier Claessens 2012-05-03 05:02:57 UTC
Looks all good to me, +1
Comment 30 Simon McVittie 2012-05-03 10:43:29 UTC
0.19.0

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.