[Development] On deprecated APIs

[André Pönitz]

On Wed, Aug 31, 2016 at 09:38:03PM +0200, Marc Mutz wrote:
> Hi André,
> 
> On Wednesday 31 August 2016 21:04:27 André Pönitz wrote:
> > They are not completely independent, but a 'Q_FOREACH' ban in Qt
> > proper does not have to imply its removal for users. If it is
> > not useful in your view, you can mention it in the docs. Breaking
> > formerly compilable code for no good reason is not a good base
> > for a 'contract'.
> 
> All the text in my email (which you cut away) is about how _not_ to break 
> formerly compilable code, for *any* reason.

That's a bit of a stretch, as some users *do* want builds with full warnings
and -Werror or similar atrocities, but with the 'In return, the Qt users:
stop insisting on -Wdeprecated-clean builds without' it'd be part of the
price they pay for the deal.

> What I actually don't understand is why people are so keen on enabling -
> Wdeprecated and at the same time don't want to move a finger about it.

Because they can. Not that I think that this is a god idea, but some
people do excruciating things just because they are possible. 

> Why enable it if it just annoys you? Why not just *not enable* the warning? 
> The fear, I guessed, is that if you don't enable it, you will get caught with 
> your pants down when your start compiling against Qt 6.
> 
> So this proposal is for a way to lift that fear, so people who don't want to 
> don't feel that they need to enable -Wdeprecated, turning it into its former 
> meaning: API we have deprecated, not removed.
> 
> So, do you have any opinion on the actual proposal?

I do.

Re-inserting the cut text:

> > > I'd therefore like to propose a new contract with our users:
> > > 
> > > The Qt Project:
> > > - continues to deprecate API it wants gone

I'd like to see this weakened a bit, maybe by adding something like
'if a reasonable replacements has been shipped in the previous $K
minor releases'. K == 2 would feel good to me.

> > > - maintains deprecated Qt N.x API until Qt (N+1).0.

That's generous. I'd be even ok with something harsher, like 
'maintains deprecated Qt N.Y API until Qt (N+1).0 _or_ Qt N.(Y+5),
whatever happens earlier'.

> > > - does *not* remove deprecated N.x API anymore come (N+1).0

Same here.

> > > - does also *not* maintain deprecated N.x API after the initial (N+1).0.0
> > >   release
> > >   * (ie. N+1).y CI runs with API deprecated in N.x (or earlier) disabled
> > >   * also means Qt does the work of making sure deprecated API is turned
> > >     all-inline before a .0.0 release to maintain BC.

Something that I believe is valuable is to provide an upgrade path from
N.y to (N+1).0 that's as source compatible as possible. We had Qt Creator
compilable on Qt 4 and Qt 5 for quite a while, and this was a real boon
to catch Qt 4 -> Qt 5 regressions. This can be phased out after (N+1).2 or
so, and it's not really in contrast to what you are suggesting here.

> > > In return, the Qt users:
> > > - stop insisting on -Wdeprecated-clean builds without investing time of their
> > >   own into updating their sources
> > > - provide patches to maintain deprecated APIs we no longer maintain
> > > 
> > > In return, the Qt Project:
> > > - pledges to take those patches in without hackling about "but it's
> > >   deprecated..."

Ok.

Andre'