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

Wed Sep 25 08:02:42 CEST 2024

Sorry to reply directly but can't write much on my mobile. \since does occour in the documentation but it's suppressed for a long time for everything older than \since 5.0 in the QtBase (at least, did not check others) documentation. We don't talk about removing \since at all here. Just for stuff added 20 years ago which no normal user is seeing anymore except developers looking into the source code directly (and hopefully know about 'git blame'). 

Christian 

Von meinem Xperia Smartphone von Sony gesendet

---- EXT Mitch Curtis via Development schrieb ----

>I'm confused... \since does show up in the generated documentation:
>
>- https://doc.qt.io/qt-6/qml-qtquick-item.html#focusPolicy-prop
>- https://doc.qt.io/qt-6/qml-qtquick-listview.html#displayMarginBeginning-prop
>
>For what it's worth, my vote goes for keeping that information too. As a user it's much more convenient for me to be able to use the latest versions of the docs that search engines give me and be able to see when an API was introduced, even if I'm using an old major version.
>
>________________________________________
>From: Development <development-bounces at qt-project.org> on behalf of Kai Köhne via Development <development at qt-project.org>
>Sent: Tuesday, 24 September 2024 11:48 PM
>To: Qt development mailing list; Paul Wicking
>Subject: Re: [Development] Proposal to retain \since version information in Qt Documentation
>
>Hi,
>
>I don't feel strongly about  '\since 5.x' , or '\since 4.y '. Given that it doesn't show up in the
>generated documentation, it is IMO of little value, and I was
>happily approving such changes in the past. But it's also true that it doesn't cost us much
>to keep these lines, so if people that browse the sources find them useful  ... fair. Just keep
>in mind that we weren't always strict about adding these in the past, so for
>accurate results, git history is arguably the more reliable source. That is, unless you're
>interested in changes that predate the big git import in Qt 4 times 😉
>
>Anyhow, I think I would oppose trying to make https://doc.qt.io/qt-6/<https://doc.qt.io/qt-6/qtcore-index.html> documentation 'work' for
>Qt 5, let alone Qt 4. For one, we have dropped documentation for removed modules,
>removed API, abandoned platforms between major versions, and bringing these back is
>IMO unfeasible. Sure, there are also classes that are still available since Qt 4, so for these
>stable parts you could use Qt 6 documentation even if you write a Qt 4 hello-world.
>But what for? https://doc.qt.io/qt-6/<https://doc.qt.io/qt-6/qtcore-index.html>  is the documentation for Qt 6. People that have to work
>with Qt 5 are better off with  https://doc.qt.io/qt-5<https://doc.qt.io/qt-5/>, and for Qt 4.8 with
>https://doc.qt.io/archives/qt-4.8/. So let's not imply that any API documentation on
>https://doc.qt.io/qt-6 is anything but Qt 6. For changes between major versions, we have
>dedicated 'What's new' pages.
>
>If we stick to this for the generated documentation, \since tags for older Qt versions in the
>source code don't do much harm. But the benefits are really small, either.
>Should we just leave this to the individual maintainer to decide?
>
>My 2 cents,
>
>Kai
>________________________________
>From: Development <development-bounces at qt-project.org> on behalf of Paul Wicking via Development <development at qt-project.org>
>Sent: Tuesday, September 24, 2024 15:12
>To: Qt development mailing list <development at qt-project.org>
>Subject: [Development] Proposal to retain \since version information in Qt Documentation
>
>Dear Qt Developers,
>
>I am writing to address a series of recent code review changes that propose
>removing the `\since [version]` documentation strings from various modules in
>Qt:
>
>- https://codereview.qt-project.org/c/qt/qtbase/+/592996/2
>- https://codereview.qt-project.org/c/qt/qtbase/+/592997/2
>- https://codereview.qt-project.org/c/qt/qtbase/+/592998/2
>- https://codereview.qt-project.org/c/qt/qtbase/+/592999/2
>- https://codereview.qt-project.org/c/qt/qtbase/+/593000/2
>
>The commit message for these changes states:
>
>> "Remove all \since 4.x comments in [module name] - this is no longer of
>interest."
>
>I would like to express my concerns regarding this proposal and advocate for
>retaining the `\since` version information in our documentation. I believe that
>removing this information could have unintended negative consequences, and I
>would like to outline several reasons why this metadata remains valuable:
>
>1. Support for Legacy Systems: Many organizations continue to maintain legacy
>   systems built with older versions of Qt, such as Qt 4. Developers working on
>   these systems might refer to the latest documentation when exploring
>   potential upgrades or seeking to understand the evolution of the API. Knowing
>   when a feature was introduced helps them determine compatibility and avoid
>   using unsupported features.
>
>2. Maintenance and Debugging: When maintaining or debugging legacy code,
>   understanding when certain features were added can be crucial. If a piece of
>   code utilizes a feature that wasn't available in the version it's supposed to
>   run on, it can lead to issues. The `\since` annotations provide immediate
>   insight into such potential problems.
>
>3. Migration Planning: Teams planning to upgrade from an older version of Qt to
>   a newer one benefit from knowing when features were introduced. It aids in
>   mapping out the migration process, identifying features that can now be used,
>   and recognizing deprecated features that need replacement.
>
>4. Historical Context and Learning: The `\since` information offers valuable
>   historical context about the evolution of Qt's APIs. It helps developers
>   understand the progression of the framework, which can be educational and
>   foster a deeper appreciation for its development.
>
>5. Third-Party Dependencies: Some third-party libraries and integrations may
>   rely on specific versions of Qt. Knowing when features were introduced helps
>   in assessing compatibility and ensuring seamless integration.
>
>6. Compliance and Regulatory Requirements: In industries with strict compliance
>   and regulatory standards—such as healthcare or finance—thorough documentation
>   is essential. Including version information meets these requirements by
>   providing a clear record of software capabilities over time.
>
>7. Global Teams and Staggered Updates: In large organizations with teams
>   distributed across different regions, not everyone may update to the latest
>   version simultaneously. Comprehensive documentation ensures that all teams
>   have the necessary information, regardless of the version they are using.
>
>8. Professionalism and Trust: Providing detailed version information
>   demonstrates a commitment to thorough and professional documentation. It
>   builds trust with the developer community and helps avoid assumptions that
>   could lead to implementation errors.
>
>9. No Cost to Retain \since Annotations: There is virtually no maintenance
>   overhead in keeping the \since annotations. Once added, they remain static
>   and do not require ongoing updates. Removing them does not offer any tangible
>   benefits but does eliminate potentially valuable information.
>
>10. Mechanisms to Prevent Clutter: Concerns about the \since annotations
>    cluttering the documentation can be addressed through existing
>    mechanisms. QDoc provides an `ignoresince` configuration variable. This
>    feature allows us to control the visibility of \since annotations in the
>    generated documentation. It's the result of a concern prior to the release
>    of Qt 6, that references to older versions might negatively impact SEO. This
>    current discussion has sparked an internal initiative within the QDoc
>    development team to enhance how QDoc handles ignoresince
>    information. Potential improvements include  making the information subject
>    to a user-defined cutoff version in the online documentation. Benefit: By
>    utilizing these mechanisms, we can prevent any perceived clutter without
>    deleting the valuable historical data from our source code.
>
>While I am fully aware that our oldest Long-Term Support (LTS) version is
>currently 5.15, and developers working with Qt 4 are encouraged to refer to Qt 4
>documentation, in practice, the availability and accessibility of older
>documentation can be limited. Additionally, developers may not always realize
>they're consulting documentation for a newer version, despite the fact that we
>have a version selector for a limited subset of documentation sets in the online
>documentation.
>
>As an example, consider a recent discussion on the development mailing list
>where understanding the historical context was essential:
>- Why does QFlag exist? (Not QFlags):
>  https://lists.qt-project.org/pipermail/development/2024-September/045636.html
>
>In this case, digging into the history from 2003 was necessary to understand a
>current issue. The `\since` annotations (had they been there) could serve as
>valuable indicators for such deep dives, highlighting how far back one might
>need to look.
>
>I also recognize that the maintenance overhead for `\since` annotations is
>minimal—they are static after their initial addition. Removing them does not
>significantly declutter the documentation but does eliminate potentially
>valuable information.
>
>Proposal:
>
>1. Retain Existing `\since` Annotations: I propose that we keep the `\since
>   [version]` annotations in the documentation, even for older versions like Qt
>   4.x, to preserve this valuable information for those who may need it.
>
>2. Revert Previously Merged Changes: Consider reverting the changes that have
>   already been merged, which removed `\since` annotations, to restore the
>   completeness of our documentation.
>
>3. Establish a Clear Documentation Policy: To prevent similar disputes in the
>   future, we should develop a clear and unambiguous policy regarding the
>   inclusion of version information in our documentation. This policy would
>   provide guidance to contributors and maintainers, ensuring consistency and
>   preserving the integrity of our documentation.
>
>By making these adjustments, we can ensure that our documentation remains a
>comprehensive resource for all developers—whether they're maintaining legacy
>systems, planning migrations, or simply seeking to understand the evolution of
>Qt.
>
>I welcome further discussion on this matter and would appreciate hearing other
>perspectives. Thank you for considering this proposal.
>
>Personal note:
>I must admit that I was hesitant to bring this matter to the mailing list, as it
>feels somewhat like an escalation. However, the interest and contrasting
>opinions expressed by multiple reviewers on these patches indicate that it would
>be beneficial to have a project-wide discussion. While this issue may not seem
>critically important in isolation, I believe it holds meaningful implications for our
>documentation practices and, more broadly, for how we make decisions that impact
>the developer community.
>
>I also feel that it's not my responsibility to block these changes based on
>personal reservations. Given that there are strong opinions on both sides, it
>seems appropriate for us as a community to reach a consensus. A collective
>decision would ensure that our actions reflect the values and needs of the
>entire Qt project.
>
>It is thus with the utmost respect for the author of these patches and the time
>and effort put in to make these and other contributions that I raise these
>questions on the mailing list.
>
>--
>Best regards,
>
>Paul Wicking
>Staff Software Engineer
>Qt Group
>--
>Development mailing list
>Development at qt-project.org
>https://lists.qt-project.org/listinfo/development
>-- 
>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/20240925/0afb97ab/attachment-0001.htm>