[Development] Semi-private headers in Qt

[Artem Dyomin]

Well, according to the input, the word "experimental" brings messages regarding temporary status and transferring to public API in the future, that doesn't fit well to some cases.
To address this, I'd rather choose the word that reflects its semiprivate status and limited compatibility guarantees.

  *
protected - for me, it doesn't sound clear in terms of headers
  *
limited_compat - looks good, but doesn't reflect private status
  *
semiprivate - perhaps better as it reflects what it does


So, what about "semiprivate"?


Confidential
________________________________
From: Fabian Kosmale <fabian.kosmale at qt.io>
Sent: Thursday, May 21, 2026 11:30 AM
To: Qt development mailing list <development at qt-project.org>; Artem Dyomin <artem.dyomin at qt.io>
Subject: AW: Semi-private headers in Qt

Hi,

for some modules, "experimental" might be fine, but I believe calling QRhi or QPA experimental might send the wrong message:
It's not an experiment that, if successful, would at some point become stable API, but it's API where we never want commit to
API and ABI stability, as we need the flexibility to adapt to changes in the underlying APIs.
"experimental" might also be read as "not fit for production usage", which is IMHO also the wrong message.

Kind regards,
Fabian

--


Fabian Kosmale


Manager



The Qt Company GmbH


Erich-Thilo-Str. 10
D-12489 Berlin


fabian.kosmale at qt.io


+49 1638686070


https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fqt.io%2F&data=05%7C02%7C%7C7c19a7e7d4cc4bcfa54408deb71b99c1%7C20d0b167794d448a9d01aaeccc1124ac%7C0%7C0%7C639149526350575904%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=l28p2OGfFzt6CI6cwZ%2F2y5ko2zs3DdiHtyuZMWy2xuo%3D&reserved=0<http://qt.io/>









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





--



________________________________________
Von: Development <development-bounces at qt-project.org> im Auftrag von Artem Dyomin via Development <development at qt-project.org>
Gesendet: Donnerstag, 21. Mai 2026 11:07
An: Qt development mailing list
Betreff: [Development] Semi-private headers in Qt

In Qt, we have semi-private functionality for rhi, qpa, ssg, that contain a disclaimer in headers and docs limiting SC and BC guarantees, and requiring to link the private part of the module. The headers are deployed as <QtGui/rhi/qrhi.h> etc.
We want to add similar headers for Multimedia with GStreamer functionality. A good idea is having a good name for this kind of API (e.g. experimental) and deploy the headers as <QtModule/experimental/qheader.h>.
The current plan is deploying new gstreamer-related headers under the new name, and then consider transferring existing headers to the new approach (with keeping old ones).

In my view, the term "experimental" is the best as the term "experimental" in C++ highly correlates with how Qt declares it in terms of SC and BC.
A discussion has been started in the CR adding "experimental".
https://codereview.qt-project.org/c/qt/qtbase/+/736307

Other proposals are "semiprivate", "nocompat", "unstable" or similar.

Are you agreed that <QtModule/experimental/qheader.h> works fine for these semi-private headers?


Confidential
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20260521/cd7c4822/attachment.htm>