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

[Jerome Pasion]

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.pasion at qt.io<mailto:jerome.pasion at 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-bounces at qt-project.org> on behalf of Axel Spoerl via Development <development at qt-project.org>
Date: Thursday, 26 September 2024 at 10:11
To: development at qt-project.org <development at 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.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
--
Development mailing list
Development at qt-project.org
https://lists.qt-project.org/listinfo/development
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 4327 bytes
Desc: image001.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0005.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image002.png
Type: image/png
Size: 709 bytes
Desc: image002.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0006.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 1935 bytes
Desc: image003.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0007.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image004.png
Type: image/png
Size: 1001 bytes
Desc: image004.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0008.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image005.png
Type: image/png
Size: 1127 bytes
Desc: image005.png
URL: <http://lists.qt-project.org/pipermail/development/attachments/20240926/ceaf0e03/attachment-0009.png>