> On 24 Sep 2024, at 15:12, Paul Wicking via Development 
> <development@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

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

Reply via email to