[Development] On deprecated APIs

[Marc Mutz]

Hi Andre,

On Wednesday 31 August 2016 10:04:55 André Somers wrote:
> While I understand the idea, I think it is very risky. I think it will
> be hard to explain to users, and even harder to defend against
> complaints and negative sentiments from users when the functionality
> _does_ break. Not maintaining something any more will mean that probably
> at one point, it will break. Do we really want to ship Qt in a way that
> we know will break, and will accumulate more breaks as time goes by? How
> do you deal with features that not too many (capable) people care about,
> do you just let them rot?

We've been doing this for a while now. QtWebkit, say, or Qt3Support in Qt 4.
 
> I think asking the community to keep supporting certain features the
> project at large wants to deprecate without any support is not a fair
> deal for anyone. Would the people able to support such features into the
> future in fact already be likely contributing to the Qt project?

If they can't do it themselves, they can pay someone to do the contributing. 
Most people can't contribute to the Linux kernel, but most people can pay for 
it.

> Supporting a feature without the aid of CI is also quite a bit harder
> for any individual maintainer. In the case of Q_FOREACH: how would you
> maintain this without access to all the supported platforms and
> compilers? On the other hand: how do you as a user know which
> depreciated features are and which are not supported by the community?
> Doesn't that make Qt as a whole less reliable?

No. If that was the case, Boost couldn't exist. Boost does not have a central 
CI, and lives by users providing patches. True, they have a test 
infrastructure that anyone can run locally and upload the result to the Boost 
web page. Maybe that would be a good idea for Qt, too?

> I would like to make a slightly different suggestion: let a deprecation
> be a reversible state.

The point is that deprecated API is API we consider a *mistake*. We don't 
_want_ users to use this API, but we don't remove it (right away) out of 
respect for existing users. If deprecation was reversible, it would mean we 
think it's ok for this API to be used again. No, we don't think so. We think 
that new code should use neither Q_FOREACH, nor QList. New code should use 
C++11 ranged-for, or QVector/std::vector. So, no, deprecation cannot be a 
reversible state.

> It could signify that the Qt project is no longer
> willing to maintain it, and it thus will go away, _unless_ somebody
> stands up to accept maintainership of said feature/class/whatever and
> promisses to keep it working before the removal takes place. It would
> then *not* be removed from CI, but it could be marked as "community
> supported" or something like that to signify it's continued support is
> not as certain as other parts of Qt. Also, Qt internally would not be
> allowed to depend on such community supported code any more. If nobody
> stands up to take maintainership, it will indeed be removed at the
> appropriate time.

And what do we do if the CI breaks due to running such community-supported 
code, and we can't get our stuff integrated anymore? How long do we wait for 
"the community" to fix it? Ain't it more likely that TQtC, woboq or KDAB will 
provide a fix to unblock the CI before "the community" even noticed there's a 
problem? No, if it runs in the official Qt CI, it will effectively be 
maintained by the Qt project. So no, it cannot run in the official CI.

> BTW: A quick search on the ML archive did not turn up a discussion on
> the removal of Q_FOREACH. Would that not be required before marking it
> deprecated? I did find more of an announcement[1]. I also found a

I don't think there's a requirement to discuss deprecating features on the ML. 
As long as the module maintainer is in the loop, and doesn't request an ML 
discussion, I don't see why we need to spam the ML with such stuff. Sure, the 
usual nay-sayers who are against any form of change will call this U-Boot 
tactics and demand a bikeshedding on the ML, but Qt is a meritocracy, not a 
democracy.

> post[2] by you where you say:
> > Try to port all your Q_FOREACH to range-for loops. You will be surprised
> > how much digging is required if you don't always want to take the hit of
> > taking a copy.
> 
> Isn't that essentially the contents user outcry you are refering to?

No, it's just testament to why Q_FOREACH is bad API. It's important to 
understand (and note in a code comment) if the container you're iterating over 
is modified further down in the call stack, because that severely restricts 
what can be done to the loop in the future.

As I said in the blog post: Q_FOREACH is convenient for the writer of the 
code. *You* don't need to care about understanding the code you write. And 
since *you* don't understand the code, you don't write the necessary comment. 
That's an extremly egocentric approach, because it leaves the infamous 
maintenance programmer with the task of having to understand the code *you* 
refused to understand when writing.

(with *you* I don't mean you personally, Andre :)

> [1] http://lists.qt-project.org/pipermail/development/2016-May/025843.html

Q_FOREACH use was never allowed in Qt library code, and this mail is about the 
removal from Qt libraries, not about deprecating it for users.

Thanks,
Marc



-- 
Marc Mutz <marc.mutz at kdab.com> | Senior Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
Tel: +49-30-521325470
KDAB - Qt, C++ and OpenGL Experts