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

[Marc Mutz]

Hi,

I cannot find Eddy's email in between, but from what I can gleam from 
Lars' quoting of it, I'd be fine with adding enum values in patch 
releaes, provided that
- they're documented (with \since x.y._z_ for each x.y.z they were new 
in (hypotheically, 6.5.3, 6.6.1, 6.7), and in [ChangeLog][Potenitally 
Source-Incompatible Changes])
- our .0 code is well-behaved when presented with these new values (ie. 
no crash, no assert, no Q_UNRECHABLE, etc). Yes, .0 may have crashed on 
some input, while .1 fixed that, but normal bugfixing is concerned with 
what must be considered invalid (or unexpected) input, whereas passing a 
new enum value should not be considered invalid or unexpected input).
- it doesn't add new ABI (no new exported symbols)

The first is to better inform our users about such gotchas.
The second and third is to still allow users to back-track, if only for 
quick regression testing. The third, in addition, is for use to be able 
to exercise tool support to detect new symbols being added. If we have 
lots of exceptions, this will not really work. Besides, we'd have to 
audit all inline APIs for use of the new symbols, because such use could 
turn "overt use, SEP" into "recompilation already breaks" scenarios.

I cannot resist noting that the third item, in particular, is a problem 
for QOperatingSystemVersion, which, despite years of yours truly's 
hammering of that particular nail, is still exported as a 
non-polymorphic class in 6.0. I'm not sure we can prevent Windows from 
exporting such static constexpr nested variables (can we make them 
variable templates instead?).

Combined, this would bring such changes into the same category as usual 
bug-fixes: behaviour changes as .z increases, but to the better.

In fact, this isn't really restricted to enums anymore, so could be a 
general guideline. I'm all for specifying the desired outcome instead of 
the exact path to reach it, because experience shows that we constantly 
refine our understanding of the Dos and Donts in this area, anyway.

Thanks,
Marc

On 23.08.23 15:09, Edward Welbourne via Development wrote:
> Lars Knoll (23 August 2023 13:32) wrote
>> 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.
> 
> On 23 Aug 2023, at 11:48, Edward Welbourne wrote:
>>> 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.
> 
> Sounds like an update to QUIP 6, or possibly a new QUIP superseding it.
> https://contribute.qt-project.org/quips/6
> 
> So we have
> 
> * QOperatingSystemVersion
>    Not an enum; { OSType, int, int, int } tuple, with a mass of constants
>    of this type to behave a bit like an enum. Adds one such constant for
>    each newly supported OS version.
> 
> * QChar (UCD) enums:
>    - UnicodeVersion -- updates whenever we upgrade
>    - Script -- also tangles with HarfBuzz's enum hb_script_t
> 
>    Those both routinely update.  In principle, any of CombiningClass,
>    JoiningType, Decomposition, Direction, Category may get new members in
>    a new Unicode release, too.
> 
> * QLocale (CLDR) enums:
>    - Language, Script, Territory
> 
> (Peculiarly, QLocale::Script and QChar::Script never seem to cross paths.)
> 
> In searching for the HarfBuzz tie-in to QChar (which I remember from
> doing some UCD updates) I didn't find anything in QFont's public API
> that was obviously affected, but that may just reveal the depth of my
> ignorance of fonts.
> 
> I inevitably wonder whether anyone else involved in 3rdparty updates has
> other examples where an external update extends enums (or other families
> of names) in our public APIs.  Please speak up if you know of any.
> 
> The other question that arises is: do we try to formulate some
> generalised characterisation of the circumstances under which this
> policy applies - public API exposing details of third-party reality - or
> do we simply document a list of cases where exceptions are permitted ?
> In the latter case, each extension would require a QUIP update; which
> conservatively may be considered good, but may be found tiresome in
> practice.  A general rule would allow Maintainers to exercise judgement,
> possibly in conference with their peers.
> 
> 	Eddy.
-- 
Marc Mutz <marc.mutz at qt.io>
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B