[QGIS-Developer] Plugins’ Dual QGIS 3 and QGIS 4 Compatibility

[Borys Jurgiel]

I just realized that our mess with the `qgis_maximum_version` tag is 
escalating, and this may be the last moment to rethink whether we really 
want it to be set automatically.

Years ago, I introduced this tag to the plugin installer in order to 
extend the compatibility range to more than one major version, which is 
exactly our current case. At the same time, @ElPaso implemented it in 
the repository application, but somehow we didn’t fully align on the 
idea: for me it was optional and not meant to be set by default. When it 
is missing, the plugin installer assumes compatibility up to the very 
end of the same major version. On the other hand, the repository always 
sets it to x.99 if it is not present. Many authors then assumed it was 
mandatory and started tagging plugins as x.99 or x.98. I guess we never 
really discussed this topic, and now we have a full variety of 
`qgis_maximum_version` values: either explicitly set by authors or 
automatically added by the repository. Furthermore, in recent years, the 
`qt6_compatible` tag was introduced, which made perfect sense at the 
time. However, it is now redundant if at least one of the version bounds 
is set to >= 4.0.

Everything worked well as long as the PyQGIS API version was 3.99. When 
it was bumped to 4.0 last year (not to be confused with the general QGIS 
version), all Qt6-compatible plugins without `qgis_maximum_version` 
explicitly set to 4 became broken:

https://github.com/qgis/QGIS/issues/62359

@JEF partially fixed this in:

https://github.com/jef-n/QGIS/commit/eac401c009f11f58c0ac2253c98d35ec6338ca60

However, this only fixed loading plugins that were already installed in 
QGIS 3. In QGIS 4, they are not available from the official repository, 
so it is impossible to (re)install them. This happens because the 
condition `if not qgisMaximumVersion (...) and supports_qt6`: fails 
twice, as the official repository always returns the 
`qgis_maximum_version` and never returns `supports_qt6`.

This is very unexpected behaviour, so many plugin authors explicitly set 
`qgis_maximum_version` to 4.99 in their plugins, what is actually how 
the tag was originally intended to be used in the installer. Currently, 
there are 171 or 182 such plugins in the official repository with 
`qgis_maximum_version` explicitly set to >= 4.0 (I don't know how many 
Qt6-compatible plugins are in the repo in total).

I can see two straightforward ways to fix this issue, but they raise a 
strategic question: do we really want `qgis_maximum_version` to be 
completed automatically?

1: If we want the function of forcibly bumping Qt6 plugins from 3.x to 
4.99 to work properly, it simply needs to be implemented in the official 
repository application as well, so that such plugins are exposed to the 
installer as 4.99 rather than 3.99.
Pros: everything will work as expected.
Cons: we introduce that rather nasty hardcoded 4.99 for a couple of 
years, and anybody will understand how it works in detail.

2: Or should we return to the original idea: make `qgis_maximum_version` 
optional, stop adding it in the repository when it is not present (and 
only handle it internally when resolving the version filter), and 
strictly require plugin authors to set this tag if they want to support 
dual major versions? In this scenario, we should also drop the 
qt6_compatible tag.
Pros: we keep things simple and unambiguous.
Cons: we break unprepared plugins until their metadata are updated.

Personally, I’m fine with either solution, but with this rather long 
story I just wanted to provide some context on how we ended up here. 
Thanks to anyone who made it to the end :)

Borys