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

[Axel Spoerl]

Hi Paul, Christian, all,
Good arguments count, better arguments win. 
+1 to keep \since 4.x as historic landmarks, and clarify rules for it.
Thanks for the discussion. 
Cheers
Axel

> On 26 Sep 2024, at 08:45, Paul Wicking <Paul.Wicking at qt.io> wrote:
> 
> 
>> 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