Re: [Development] BC/SC in patch releases (particularly enum additions)
On 23 Aug 2023, at 15:39, Marc Mutz via Development wrote: Hi, I cannot find Eddy's email in between, In case you're still looking for it: https://lists.qt-project.org/pipermail/development/2023-August/044348.html //! Paul -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] BC/SC in patch releases (particularly enum additions)
On Wednesday, 23 August 2023 06:39:32 PDT Marc Mutz via Development wrote: > 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?). There may be technical solutions for that particular problem. The one that came to mind is to add the variables to QOperatingSystemVersionBase instead of QOperatingSystemVersion. That won't work because you can't declare a static constexpr variable of a class type inside that type because the type not being complete yet isn't yet a literal. The solution to that, like most problems in computing, is yet another level of indirection. Proof of concept: https://codereview.qt-project.org/c/qt/qtbase/+/498775 -- Thiago Macieira - thiago.macieira (AT) intel.com Cloud Software Architect - Intel DCAI Cloud Engineering smime.p7s Description: S/MIME cryptographic signature -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] BC/SC in patch releases (particularly enum additions)
> On 23 Aug 2023, at 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
As QUIP 6 focuses specifically on SiC changes between minor releases, and since
the technicalities that influence what we can do within a patch cycle (in
particular our ambition to maintain forward binary compatibility) are somewhat
different from that, a separate QUIP might be cleaner.
> 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.
If we focus such a QUIP exclusively on where we allow what kind of additions
within a patch cycle, then I think we should be explicit about each case, and
have a good change process for each addition. I can, from the top of my head,
not come up with more than what you listed above. Everything else is not
allowed.
Volker
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development
Re: [Development] BC/SC in patch releases (particularly enum additions)
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
Principal Software Engineer
The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io
Geschäftsführer: Mika Päl
Re: [Development] BC/SC in patch releases (particularly enum additions)
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.
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development
Re: [Development] BC/SC in patch releases (particularly enum additions)
> On 23 Aug 2023, at 11:48, Edward Welbourne via Development > 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 -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] BC/SC in patch releases (particularly enum additions)
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. 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. 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, Eddy. -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
