> On 24 Sep 2024, at 22:37, Axel Spoerl via Development > <development@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 -- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
