[Development] Proposal to retain \since version information in Qt Documentation

[Volker Hilsheimer]

> On 24 Sep 2024, at 15:12, Paul Wicking via Development <development at qt-project.org> wrote:
> 
> Proposal:
> 
> 1. Retain Existing `\since` Annotations: I propose that we keep the `\since
>   [version]` annotations in the documentation, even for older versions like Qt
>   4.x, to preserve this valuable information for those who may need it.
> 
> 2. Revert Previously Merged Changes: Consider reverting the changes that have
>   already been merged, which removed `\since` annotations, to restore the
>   completeness of our documentation.
> 
> 3. Establish a Clear Documentation Policy: To prevent similar disputes in the
>   future, we should develop a clear and unambiguous policy regarding the
>   inclusion of version information in our documentation. This policy would
>   provide guidance to contributors and maintainers, ensuring consistency and
>   preserving the integrity of our documentation.


+1 to the above proposals.

The documentation policy regarding versioning has so far been rather implicit: more experienced reviewers will check that the addition of a new API is not only accompanied by documentation, but that this documentation also includes a \since tag. Looking out for \since is mentioned on https://wiki.qt.io/Things_To_Look_Out_For_In_Reviews#New_Classes, and perhaps it’s quite obvious that one should also look out for \since when reviewing a patch that adds a new API to an existing class.

The plan following the respective discussion at Qt CS was to transfer uncontroversial content from TTLOFIR  into QUIP(s), although perhaps a more explicit policy on this specific topic might deserve a separate QUIP.

If the bot that analyses changes to public headers could learn to look out for documentation (with \since) for changes adding public API, then that could be useful.

Volker