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

[Paul Wicking]

> On 24 Sep 2024, at 23:13, Thiago Macieira <thiago.macieira at intel.com> wrote:
> 
> We didn't start adding them until post 4.0. I don't think 3.x had the tag at 
> all and APIs new in 4.0 weren't marked as such either. That means the furthest 
> back we can go is 4.0. Qt 3 to 4 was also a massive update, so I don't think 
> it would be useful to go that far back anyway. Qt 4.0 will be 20 years old 
> next year.

Hi Thiago,

Thank you for providing historical context about the usage of `\since` tags in
our documentation. Given that Qt 3 to Qt 4 was a significant overhaul, and
recognizing that Qt 4.0 will be 20 years old next year, it's understandable to
question the usefulness of including version information dating that far
back. I've been pondering this a bit today.

I think establishing a clear baseline for our documentation can be
beneficial. I'm thinking along the lines of how C++98 (being the first standard)
serves as the baseline for the documentation on cppreference.com. Any features
introduced after C++98 are annotated accordingly, providing developers with
valuable information about the evolution of the language.

For Qt, setting Qt 4 as our baseline makes sense for several reasons:

1. Binary Compatibility Promise: Since Qt 4, the project has promised binary
   compatibility between minor versions within a major branch. This commitment
   to stability means that many APIs introduced in Qt 4 are still in use today,
   and their longevity underscores the robustness of our framework.

2. Maturity and Stability Indicator: Including `\since` information starting
   from Qt 4 highlights the maturity and stability of our APIs. It serves as an
   indicator of how long a particular feature has been part of Qt, which can
   instill confidence in developers about the reliability of the API they are
   using.

3. Consistent Documentation: Establishing Qt 4 as the baseline allows us to
   provide consistent version information throughout our documentation. This
   consistency helps developers understand the historical context of features
   and makes our documentation more informative and useful.

4. Marketing the Strength of Qt: Showcasing the long-term stability and
   continuity of our APIs can be a subtle form of "marketing." It tells a story
   of a mature and stable framework that developers can trust for their
   long-term projects.

My guess is that there are some product managers in Qt Group who keep en eye on
this mailing list that might nod in silence at some of those points. But
ultimately, my main concern is aligning on what we, as a project, aim to achieve
with our documentation. If we can agree on a baseline—whether it's Qt 4 or
another version—we can ensure that our documentation remains consistent,
informative, and valuable to a wide range of developers.

--
//! Paul