Merge pull request #288 from kannes/improve-qgis4-migration

Correctly document compatibility rules for QGIS 4 plugin migration

Author: Xpirix

qgis-app/templates/flatpages/docs_migrate_qgis4.html

@@ -14,40 +14,47 @@ <h4>{% trans "Migrate Your Plugin to QGIS 4" %}</h4>
       {% blocktrans trimmed %}
       To make your plugin appear in the
       <a href="/plugins/new_qgis_ready/">QGIS 4 Ready Plugins</a> list, simply set
-      <code>qgisMaximumVersion=4.99</code> (or higher) in your <code>metadata.txt</code>
-      and remove the deprecated <code>supportsQt6</code> flag.
+      <code>qgisMaximumVersion=4.99</code> (or higher) in your <code>metadata.txt</code>.
       {% endblocktrans %}
     </p>
   </div>
 
-  <h5>{% trans "Background" %}</h5>
+  <h5>{% trans "Updating Plugin Code for QGIS 4" %}</h5>
   <p>
     {% blocktrans trimmed %}
-    During the QGIS 4 pre-release period, a temporary metadata flag called
-    <code>supportsQt6</code> was introduced to let plugin authors signal that their plugin
-    was compatible with Qt 6 and QGIS 4. Plugin authors were encouraged to add
-    <code>supportsQt6=True</code> to their <code>metadata.txt</code>.
+    QGIS 4 uses Qt 6 which requires code changes in plugins. See the
+    <a href="https://github.com/qgis/QGIS/wiki/"
+       target="_blank" rel="noopener">
+      QGIS wiki
+    </a>
+    page
+    <a href="https://github.com/qgis/QGIS/wiki/Plugin-migration-to-be-compatible-with-Qt5-and-Qt6"
+       target="_blank" rel="noopener">
+      Plugin migration to be compatible with Qt5 and Qt6
+    </a>
+    for details, tips and tools.
     {% endblocktrans %}
   </p>
   <p>
     {% blocktrans trimmed %}
-    Following the changes described in
-    <a href="https://github.com/qgis/QGIS/pull/65146" target="_blank" rel="noopener">qgis/QGIS#65146</a>
-    and <a href="https://github.com/qgis/QGIS/pull/65168" target="_blank" rel="noopener">qgis/QGIS#65168</a>,
-    the <code>supportsQt6</code> flag has been <strong>removed from QGIS core</strong> and is
-    <strong>no longer recognised</strong>. Declaring <code>supportsQt6=True</code> in your metadata has
-    no effect and plugins that relied solely on this flag to appear in the QGIS 4 plugin list have been
-    removed from that list.
+    The rest of <em>this</em> page is not about Python code changes, but describes
+    how to get your plugin listed as QGIS 4 compatible in the plugin repository.
     {% endblocktrans %}
   </p>
 
-  <h5>{% trans "The New Rule: qgisMaximumVersion" %}</h5>
+  <h5>{% trans "Compatibility by Version Range" %}</h5>
   <p>
     {% blocktrans trimmed %}
-    QGIS 4 compatibility is now determined exclusively by the <code>qgisMaximumVersion</code> field
-    in <code class="is-size-7 has-text-weight-semibold">metadata.txt</code>. A plugin version is shown in the
-    <a href="/plugins/new_qgis_ready/">QGIS 4 Ready Plugins</a> list when
-    <code>qgisMaximumVersion &ge; 4.0</code>.
+    QGIS version compatibility is determined simply from the range given by the 
+    <code>qgisMinimumVersion</code> and the <code>qgisMaximumVersion</code> (optional) fields
+    in <code class="is-size-7 has-text-weight-semibold">metadata.txt</code>.
+    If <code>qgisMaximumVersion</code> is not set, then compability is assumed up to end of the
+    <em>major version</em> line set by <code>qgisMinimumVersion</code>.
+    A plugin version is shown in the <a href="/plugins/new_qgis_ready/">QGIS 4 Ready Plugins</a>
+    list if the <code>qgisMinimumVersion</code> is <code>&ge;4.0</code> or the 
+    <code>qgisMaximumVersion</code> field is <code>&ge;4.0</code>.
+    To mark a QGIS 3 compatible plugin to be QGIS 4 as well, keep the existing 
+    <code>qgisMinimumVersion=3.xx</code> and add <code>qgisMaximumVersion=4.99</code>.
     {% endblocktrans %}
   </p>
   <p>{% trans "Examples:" %}</p>
@@ -63,10 +70,31 @@ <h5>{% trans "The New Rule: qgisMaximumVersion" %}</h5>
       </li>
       <li>
         <code>qgisMinimumVersion=3.22</code>, <code>qgisMaximumVersion=3.99</code>
-        &rarr; {% trans "Not listed (QGIS 3 only)" %}
+        &rarr; {% trans "Not listed for QGIS 4 (QGIS 3 only)" %}
       </li>
     </ul>
   </div>
+  
+  <h5>{% trans "Deprecated Temporary <code>supportsQt6=True</code> Flag" %}</h5>
+  <p>
+    {% blocktrans trimmed %}
+    During the QGIS 4 pre-release period, a temporary metadata flag called
+    <code>supportsQt6</code> was introduced to let plugin authors signal that their plugin
+    was compatible with Qt 6 and QGIS 4. Plugin authors were encouraged to add
+    <code>supportsQt6=True</code> to their <code>metadata.txt</code>.
+    {% endblocktrans %}
+  </p>
+  <p>
+    {% blocktrans trimmed %}
+    Following the changes described in
+    <a href="https://github.com/qgis/QGIS/pull/65146" target="_blank" rel="noopener">qgis/QGIS#65146</a>
+    and <a href="https://github.com/qgis/QGIS/pull/65168" target="_blank" rel="noopener">qgis/QGIS#65168</a>,
+    the <code>supportsQt6</code> flag has been <strong>removed from QGIS core</strong> and is
+    <strong>no longer recognised</strong>. Declaring <code>supportsQt6=True</code> in your metadata has
+    no effect and plugins that relied solely on this flag to appear in the QGIS 4 plugin list have been
+    removed from that list.
+    {% endblocktrans %}
+  </p>
 
   <h5>{% trans "How to Update Your Plugin" %}</h5>
   <div class="content">
@@ -85,17 +113,31 @@ <h5>{% trans "How to Update Your Plugin" %}</h5>
         <strong>{% trans "Verify Qt 6 / PyQGIS 4 compatibility" %}</strong>
         <p>
           {% blocktrans trimmed %}
-          Before bumping <code>qgisMaximumVersion</code>, make sure your plugin actually works
+          Before bumping your plugin's compatibility to QGIS 4, make sure it actually works
           with QGIS 4. Key things to check:
           {% endblocktrans %}
         </p>
         <div class="content">
           <ul>
             <li>{% trans "Replace any deprecated Qt 5-only APIs with their Qt 6 equivalents." %}</li>
-            <li>{% trans "Replace <code>PyQt5</code> imports with <code>PyQt6</code> (or use the QGIS-provided compatibility shim)." %}</li>
+            <li>{% trans "Replace <code>PyQt5</code> imports with <code>PyQt6</code> (or better yet, use the QGIS-provided <code>qgis.PyQt</code> compatibility shim)." %}</li>
             <li>{% trans "Test your plugin with a QGIS 4 nightly or release build." %}</li>
           </ul>
         </div>
+        <p>
+          {% blocktrans trimmed %}
+          You can find helpful tips and helper tools on the
+          <a href="https://github.com/qgis/QGIS/wiki/"
+             target="_blank" rel="noopener">
+            QGIS wiki
+          </a>
+          page 
+          <a href="https://github.com/qgis/QGIS/wiki/Plugin-migration-to-be-compatible-with-Qt5-and-Qt6"
+             target="_blank" rel="noopener">
+            Plugin migration to be compatible with Qt5 and Qt6
+          </a>
+          {% endblocktrans %}
+        </p>
       </li>
       <li>
         <strong>{% trans "Upload a new version" %}</strong>