[Development] BC/SC in patch releases (particularly enum additions)

[Lars Knoll]

> On 23 Aug 2023, at 11:48, Edward Welbourne via Development <development at qt-project.org> wrote:
> 
> On Tuesday, 22 August 2023 14:27:09 PDT Marc Mutz via Development wrote:
>>>> I think we should decide what we mean by forward BC and SC and
>>>> describe it in https://wiki.qt.io/Qt-Version-Compatibility more
>>>> precisely.
> 
> On 23.08.23 04:48, Thiago Macieira wrote:
>>> I thought the rule was "no new symbols, period" with the exception
>>> for QOperatingSystemVersion for operating systems that have been
>>> released since that Qt release was made.
> 
> Marc Mutz  (23 August 2023 07:52) replied:
>> Indeed. This is how I remember it, too (though the exception is new to
>> me), but that is clearly not what the project is producing atm,
>> therefore I decided to raise this here.
> 
> All of which makes perfectly good sense, but we do have history of
> adding new members to other enums.  The example I'm familiar with - that
> I dimly remember, although one should be wary of trusting my memory and
> I can't find where it happened, asking Lars about when he was Chief
> Maintainer, and continuing at his bidding - is adding members to
> QLocale's Language, Script and (formerly and still technically Country,
> now to be thought of as) Territory enums.

We have been adding new enum values in certain cases. The operating system versions needing to be amended to support a new version of macOS is one example. That has happened a couple of times within LTS releases as far as I remember.

We’ve also once or twice upgraded CLDR or Unicode versions within patch level releases to fix serious bugs, and I believe have in that process also added new enum values.

> The documentation of these does get "since" annotations (and these will
> reference future versions, if we don't amend them during or after
> picking) that could be the basis for "don't use these overtly in code if
> you care about backwards-and-forwards compatibility" docs (that should
> be added, if we continue doing this).  They only present a problem if
> the client code overtly exercises the new enum members.

Those new enum values only present an issue if they are explicitly used in user code. But in that case, I would think that the user is happy to have them available. Given the choice between that and a forward compatibility promise that allows downgrading I am sure they all prefer having the enum value available.

I can honestly not see any real downside of adding those enum values in these kind of cases. If you don’t use the value explicitly, you don’t have a problem. If you do, you really want it and are happy we made it available.

> 
> To quote (with [minor changes]) the commit message of (trial baloon)
> https://codereview.qt-project.org/c/qt/qtbase/+/498607
> 
>  The counter-case is that client code generally only queries the
>  available locales to ask the user to pick one, then uses it; or reads
>  a locale ID from some source (e.g. HTTP headers) and passes it to
>  QLocale to make sense of it. That [may] exercise newly-added enum
>  members, in which case it will be a behavior change between patch
>  releases (we now support locales we did not before), but the same can
>  arise simply from CLDR adding data for locales we already do have the
>  codes for in our enums. In any case, code doing this will run when
>  compiled and run-time linked against different patch releases, in
>  either direction; and users gain the benefit of the new enum members
>  [and locales] if they update their Qt libraries.
> 
> which I suppose to be the rationale for past post-x.y.0 additions to
> these enums.  This benefit may well be significant for some users and
> authors of client code do have to go out of their way to break it.
> 
> I agree with Marc that we should, at the very least, be clearer about
> what exactly our policy is - and stick to it,

I agree with that, but would propose to amend our policy and explicitly allow adding enum values in those limited cases. Updates to Unicode data, supporting new OS versions and maybe a few other limited cases come to my mind here.

Cheers,
Lars