[Development] Semi-private headers in Qt

[Elvis Stansvik]

Den fre 29 maj 2026 13:50Volker Hilsheimer <volker.hilsheimer at qt.io> skrev:

>
>
> >> On 29 May 2026, at 08:56, Elvis Stansvik <elvstone at gmail.com> wrote:
> >>
> >> Den tors 28 maj 2026 20:07Thiago Macieira <thiago.macieira at intel.com>
> skrev:
> >> On Thursday, 28 May 2026 10:39:27 Pacific Daylight Time Volker
> Hilsheimer via
> >> Development wrote:
> >> > The established and documented rules for semi-private APIs like QPA
> and RHI
> >> > are:
> >> >
> >> > - no changes within a patch cycle
> >> > - changes (both source- and binary-incompatible) might happen between
> minor
> >> > releases
> >>
> >> What would be the difference to an experimental module? I'd assume that
> if we
> >> are trying to get people to adopt experimental things, we wouldn't
> break at
> >> will within a minor series. That would make the rules equivalent to the
> semi-
> >> private.
> >> The difference is that experimental has a goal of becoming
> non-experimental
> >> some day.
> >
> > And conversely, the name "experimental" also acknowledges that the
> experiment might end (i.e. fail). The same is probably not true for rhi etc?
> >
> > So the name experimental is probably not suitable for two different
> reasons?
>
>
> I don’t know what the difference to an “experimental module” would be,
> since we don’t have any of those.
>
> We have Technology Preview for features, the Labs namespace for QML
> modules, and \preliminary documentation tagging for individual APIs or
> classes.
>
> What each of these means is not very well defined beyond QUIP-14 [1], but
> they are all a stepping stone towards becoming a mature part of Qt.
>
> [1] https://contribute.qt-project.org/quips/14
>
> Semi-private stuff is not expected to graduate. We want to keep it out of
> the scope of binary and source compatibility commitments because the APIs
> are very close to underlying APIs that are outside of our control, and
> where changes might require us to adapt in BiC/SiC ways. I.e. changes in a
> future version of GStreamer might invalidate some of the designs of the
> interface proposed at the beginning of this thread.
>
> But they are also not private because there are very valid use cases for
> using those APIs to interface with underlying subsystems directly, enabling
> use cases that go beyond of what Qt can abstract.
>

It sounds like "volatile" or "unstable" best describes what sets them apart
from normal public headers - that they may change more frequently.


>
> Volker
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20260529/0c6c2cb6/attachment.htm>