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

[Paul Wicking]

> On 24 Sep 2024, at 22:37, Axel Spoerl via Development <development at qt-project.org> wrote:
> 
> 
> - It’s of course visible in cpp files. If I have my hands on C++, I tend to believe more in git blame’s version of the gospel.

Axel,

I wanted to mention something that slipped my mind yesterday. I agree that
version control history is indeed the definitive source for when something was
added to the codebase, even if it means searching through different repositories
or version control systems. However, I feel this point is somewhat tangential to
our discussion. The main purpose of the `\since` command is to inform our
/users/ about when a feature became part of the /public/ API. For example, if a
feature was introduced in version 6.3 as a private API and then made public in
version 6.8, the documentation should state `\since 6.8`, even though the
underlying code was added five minor versions earlier. From what I've seen over
the years, I believe this is our common practice. This is also important for
enumerations that see additions over the years (which I'm sure Eddy can attest
to). We typically include `\since` information for new values.

By focusing on when features become part of the public API, we provide clear and
relevant information to users about the availability of features they can
actually use, without requiring them to delve into the intricacies of the
codebase history. For developers /of/ Qt, the `\since` entries can possibly
offer an anchor point when doing code archaeology.

I believe documenting when features become part of the public API helps
illustrate the product's lifecycle. This is important because it provides users
with a clear roadmap of how the software has evolved over time. Understanding
the lifecycle aids users in planning upgrades, assessing feature stability, and
making informed decisions about adopting new functionalities. Accurate `\since`
entries thus support users in aligning their projects with the appropriate
versions of Qt. However, while related, I think an overall product lifecycle
documentation strategy is worthy of a separate discussion, as it clearly
involves more than "just `\since` strings" :)

//! Paul