Hello, I would like to keep the \since just to keep the continuity.
I would suggest an even larger overhaul about how version support is portrayed in the documentation. If Qt is to move into a life cycle approach, then the inception, inclusion, and EOL/EOS should be clarified in the documentation. Sorting out the different supported platforms and versions is really messy. In reality, Qt has two/three existing major versions… and any module can be a spinoff of an existing module, a community addition, commercial exclusive, resurrection of a previous module, or a combination of any of these. It would not be inconceivable for a module to be moved out of Qt and reintroduced later. These movements should be clearer and integrated into compatibility topic. It would be nice to see the relevant version in the documentation and just download it from the online installer without the inside knowledge of when it was merged by whom. I’ve seen some issues with how Qt deals with this life-cycle in the reference documentation already. There are even pages from current minor versions appearing in pages for previous minor versions. There could be safeguards for the documentation at the codereview to prevent this from happening. The pick-to may be too relaxed for documentation issues, maybe. Jerome Pasion Specialist Technical Writer The Qt Company AS Sandakerveien 116 0484 Oslo Norway jerome.pas...@qt.io<mailto:jerome.pas...@qt.io> +47 99 08 39 08 www.qt.io<https://www.qt.io/> [signature_4008513735]<https://www.qt.io/> [signature_285784628]<https://www.facebook.com/qt/> [signature_1572216309]<https://twitter.com/qtproject> [signature_1040780505]<https://www.linkedin.com/company/qtgroup/> [signature_3354964817]<https://www.youtube.com/QtStudios> From: Development <development-boun...@qt-project.org> on behalf of Axel Spoerl via Development <development@qt-project.org> Date: Thursday, 26 September 2024 at 10:11 To: development@qt-project.org <development@qt-project.org> Subject: Re: [Development] Proposal to retain since version information in Qt Documentation 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
-- Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
