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.wick...@qt.io> wrote: > > >> 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
