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

[Paul Wicking]

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