[Development] QtCS 2024 session on deprecations: what did we actually agree on?

[Edward Welbourne]

For reference, here are Jan Arve's notes from the QtCS 2024 session:
https://wiki.qt.io/QtCS2024_Deprecate

On Tuesday 14 January 2025 08:46:40 Pacific Standard Time Jaroslaw Kobus:
>>>> 2. APIs that we want to only deprecate. All agrees on it, no one
>>>> complains.

Thiago Macieira (14 January 2025 18:22) replied:
>>> I think we need a timer on this. Most APIs that have been deprecated
>>> for N number of years will be removed in the next release. There may
>>> be some exceptions that we think even N years being deprecated isn't
>>> long enough (e.g., it's been around since Qt 1, such as QTimer).

My memory of the discussion says there was a clear view that there
should be no blanket rule on how long after deprecation removal should
happen.  In particular, there were clear statements about some
deprecated APIs being kept indefinitely - within #if-ery that can be
used to disable them; and ideally inlined - as long as the API itself
does no harm (and if maintaining it incurs a large cost, we may well
want to count that as harm).  Removal does harm users, so doing it
should require a clear and compelling reason.

That still left open the option of making the case for removal of
individual harmless APIs on a case-by-case basis; and we do now have
rather better macros to help us remove ABI as long as the API is
source-compatible with its replacement.  We can also consider dropping
deprecated APIs from the documentation, after a suitable delay.

apoenitz (14 January 2025 19:24) wrote:
>> I seem to remember that we decided that the decision to remove
>> something will be independent from the decision to deprecate it.

I hope (an adequate period of) prior deprecation is still a prerequisite
for removal, except in cataclysmic cases, so they're not independent;
however, indeed, "Deprecation is not removal" is one of the two summary
points in which Jan Arve ended the write-up.  The decision to deprecate
does not *imply* a decision to remove.

>> I don't remember a fixed default, my assumption is there is none, and
>> I also think there doesn't need to be one.

That matches my memory and the write-up.

>> For me, it would make a lot of sense to do all the
>> to-drop-or-not-to-drop discussions more or less in one go at the same
>> time a few months before the major version change.
>>
>> As such an event would probably draw some attention, this gives us a
>> chance to get some kind of (more) uniform judgement involving roughly
>> the same participants at roughly the same time.
>>
>> This would nicely address one of the issues I had with the 5.x
>> deprecations (plus resulting automatic removal in the end) which
>> trickled in over a period of three(?) years, done by (often very few)
>> different people with diverging directions that led in the end to a
>> rather inconsistent distributed discussions and results.

We have, since that meeting, introduced new macros to qualify
deprecation with "and remove at Qt 7" and similar for Qt 8.  Our current
process is that reviewers can discuss whether one of these is an
appropriate choice when a deprecation is being added.  We can, of
course, later come back and overturn such a decision, in either
direction, and we shall probably want to review deprecations predating
6.9 for whether they should be removed.  So that's an on-going process,
with the "diverging directions" issues you mention, although the first
API change review after each addition of a removal marker shall at least
give a wider audience a chance to object.

We can, however, use those new macros to, in the run-up to Qt 7, conduct
a systematic and general review of all such proposed removals, similar
to our current API change reviews before release.  And, of course, the
new macros are something we can grep for in the source in order to
prepare such a review - or you, as a user, can grep for to find out
whether there's any you object to.

Robert Schimkowitsch (15 January 2025 10:46) wrote:
> If I may add a user's perspective to the discussion.
> I know gift season is over, but here is what I (as a user) would
> ideally get:
> 1) Things get deprecated, including clear communicating when they are
>    planned to be removed (e.g. "to be removed in Qt 7" or "to be
>    removed in Qt 8")

The new macros aim to provide that; however, they only do so for readers
of the source code - I can't remember what we decided as regards how to
document the intent to remove, but that's clearly an option to consider.

> 2) There is always at least one X.Y-release between deprecating and
>    removing. So if something is deprecated in the last version of Qt
>    6.x, it is removed in Qt 8, not Qt 7

We currently have a delay between
* When the replacement API is available and deprecation markers are in
  place and
* When the deprecation kicks in

although the exact details remain a bit fuzzy; some seem to be using
"after the next LTS and at least 6.(n+3)" when the deprecation markers
are added in time for 6.n, but I don't think we've yet had an Ex
Cathedra decision on what our rule for that is.  Jan Arve's notes
include a suggestion of "5 versions" as the interval.

We can similarly insist on a delay between the deprecation kicking in,
with removal indicated as part of it, and removal actually happening.
That's something we can probably handle in review when someone adds a
removal marker; and (see my answers to Andre' above) we can hopefully
pick that up also in a Grand Review of Removals, if we go ahead with
that idea.

> 3) This also gives me time, as a user, to study deprecations, and
>    write a support ticket ("are you serious?") in the probably rare
>    cases things would really break the world for me

Such tickets would indeed be very useful sanity checks for those
introducing both deprecations and proposed removals.

> 4) Offering Compat modules is welcome where it is feasible

That still leaves open the question of when, if ever, we should retire
such modules.  That would overlap with [0] QUIP-14.

[0] https://codereview.qt-project.org/c/meta/quips/+/246320

I think we need to keep open the option of removal, as a necessary
support to being able to manage our maintenance overheads, while still
allowing some deprecated APIs to remain indefinitely.  I am wary of
"hard and fixed rules" as the way to settle such questions, favouring a
guideline-based approach.
* If an existing API causes active harm to users, or incurs a high
  maintenance cost, eventual removal is a natural choice.
* If a harmless API can be trivially inlined, and its removal would be
  source-incompatible, then we should keep it indefinitely.

The vast spectrum between those two extremes shall require thoughtful
judgement; maybe, over time, and with experience of how it plays out, we
can refine our guidelines.  For now, Maintainer Discretion seems a sane
start-point.

	Eddy.