[Development] On Removing Public Undocumented/\internal APIs

[Jaroslaw Kobus]

Hi All,

in my opinion we have an attention redirection here.
We can of course start considering whether a particular change applies to the rules,
provided the is a gain the change brings.

The original rename doesn't bring any value, so discussing if it was applying to the rules doesn't move us forward.

Best regards

Jarek


Confidential
________________________________________
From: Development <development-bounces at qt-project.org> on behalf of Marc Mutz via Development <development at qt-project.org>
Sent: Thursday, July 10, 2025 2:37 PM
To: development at qt-project.org
Subject: Re: [Development] On Removing Public Undocumented/\internal APIs

Hi,

I'm coming back to this thread, because this conclusion:


Confidential
On 18.03.24 16:28, Volker Hilsheimer wrote:
[...]
>
> to use those APIs you have to read the code. And
> then you’ll see that they are either undocumented, or documented as
> \internal.
>
> You can still use them, but you know that they might change.
[...]

is being challenged for a recent change of mine that renamed
undocumented QArrayData::ref_ to m_ref¹. There's a growing pile of reviewers
that don't like the change, mainly because it breaks QtC (a fix is
available already², there's also a revert³ of the original change)

¹ https://codereview.qt-project.org/c/qt/qtbase/+/651494
² https://codereview.qt-project.org/c/qt-creator/qt-creator/+/660083
³ https://codereview.qt-project.org/c/qt/qtbase/+/660072

With the above rule, undocumented is equivalent to private. In particular,
you have to assume that undocumented API changes at any time.

We now see how loud the outcry is when such changes, routinely done
every week, happen to hit one of our own tools with a vocal developer base.

Do we still uphold the rule? I will bow to the decision, but either the
change is allowed alongside all others, or none are. It can't be that
we apply double standards.

Thanks,
Marc

--
Marc Mutz <marc.mutz at qt.io> (he/his)
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

--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development