Add documentation on how to adapt to new Qt versions

As a drive by, add a comment about QT6_DECL_NEW_OVERLOAD_TAIL
to the QtCore type system file.

Change-Id: Idf395158f955fb3114431a04542a26341f53a7af
Reviewed-by: Christian Tismer <tismer@stackless.com>
(cherry picked from commit d174ff9888069407a1042bce67ed63712ff1e69e)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 47 insertions, 0 deletions

diff --git a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
index 1d666ad5b..bdaef41f4 100644
--- a/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
+++ b/sources/pyside6/PySide6/QtCore/typesystem_core_common.xml
@@ -116,6 +116,9 @@
   <rejection class="*" field-name="d_ptr"/>
   <rejection class="QMetaMethod" enum-name="Attributes"/>
   <rejection class="QMetaMethod" field-name="data"/>
+  <!-- Note: Default parameter values of Disambiguated_t as defined by
+       QT6_DECL_NEW_OVERLOAD_TAIL are not seen by the clang parser since it
+       is relying on code snippets for the values. -->
   <rejection class="Qt" field-name="Disambiguated"/>
   <rejection class="" enum-name="QCborNegativeInteger"/>
 
diff --git a/sources/pyside6/doc/developer/adapt_qt.rst b/sources/pyside6/doc/developer/adapt_qt.rst
new file mode 100644
index 000000000..f8582f699
--- /dev/null
+++ b/sources/pyside6/doc/developer/adapt_qt.rst
@@ -0,0 +1,43 @@
+.. _developer-adapt-qt:
+
+Adapt to new Qt versions
+========================
+
+The dev branch of PySide is switched to a new Qt minor version
+after its API review is finished and the API is stable.
+
+Until that happens, a patch should be continuously developed
+to adapt to this version.
+
+The `new classes page <https://doc-snapshots.qt.io/qt6-6.7/newclasses67.html>`_
+is a good source of information for new API.
+
+New classes and should be added to the type system file (using
+a ``since`` attribute) and ``CMakeList.txt`` file of the respective module.
+
+Should the class not be available on all platforms, the respective
+``QT_CONFIG`` macro needs to be specified in the type system file and
+feature checks need to be added to ``CMakeList.txt`` (see for example
+``QPermission``).
+
+The process consists of running a build and evaluating the log file.
+The script
+`shiboken2tasks.py <https://code.qt.io/cgit/qt-creator/qt-creator.git/tree/scripts/shiboken2tasks.py>`_
+from the Qt Creator repository can be used to convert the shiboken warnings
+into a `task file <https://doc.qt.io/qtcreator/creator-task-lists.html>`_
+for display in the build issues pane of Qt Creator.
+
+Warnings about new enumerations will be shown there; they should be added
+to type system file using a ``since`` attribute.
+
+Warnings about not finding a function signature for modification
+also need to be handled; mostly this is a sign of a function parameter
+being changed from ``int`` to ``qsizetype`` or similar.
+
+If the build succeeds, a test run should be done.
+
+The Qt source code should be checked for new overloads
+(indicated by ``QT6_DECL_NEW_OVERLOAD_TAIL`` starting from 6.7).
+The resolution needs to be decided for each individual case,
+mostly by removing old functions and using ``<declare-function>``
+to declare new API.
diff --git a/sources/pyside6/doc/developer/index.rst b/sources/pyside6/doc/developer/index.rst
index d15b36bc3..92c84259d 100644
--- a/sources/pyside6/doc/developer/index.rst
+++ b/sources/pyside6/doc/developer/index.rst
@@ -17,6 +17,7 @@ Development Topics
    add_port_example.rst
    add_tool.rst
    documentation.rst
+   adapt_qt.rst
    extras.rst
 
 Implementation details