[Development] Semi-private headers in Qt

[Volker Hilsheimer]

> On 28 May 2026, at 16:23, Thiago Macieira <thiago.macieira at intel.com> wrote:
> 
> On Thursday, 21 May 2026 02:07:54 Pacific Daylight Time Artem Dyomin via 
> Development wrote:
>> 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.
> 
> I think we need to flesh out what the guarantees for semi-private are. Please 
> explain how they differ from private and from public.
> 
> And please make it *one* set of rules applying to all of them. The only thing 
> that can vary is a parameter, such as the length of time a deprecated API will 
> last before being removed, and no parameter can become zero.

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

This is documented here:

https://doc.qt.io/qt-6/qrhi.html#details
https://doc.qt.io/qt-6/qpa.html

(with slightly different wording and style, but saying the same thing).

Headers are installed, code using them might have to link against a private module.

Volker