[Qgis-psc] [QGIS-Developer] Fwd: QGIS 4.0 publicly announced - right time for propose and implement breaking changes?

[Nyall Dawson]

On Sat, 26 Apr 2025 at 05:25, Dalheimer, Jan via QGIS-Developer
<qgis-developer at lists.osgeo.org> wrote:
>
> I think part of the confusion (at least for me) might be because there is no clear information (that I can find) on what breaking changes are allowed in QGIS 4 (and between major and minor versions more generally).
>
> Even such a relatively simple question such as “if any breaking changes apart from those necessary to switch to Qt 6 are allowed for QGIS 4” isn't quite clear to me, even with Jürgens response below.
>
> The closest to written documentation on this I can find is the one sentence here: docs.qgis.org/3.40/en/docs/developers_guide/codingstandards.html#api-compatibility
>
> For core developers and other “longtimers” this is might be second nature, but for us not in that group it’s not. This might also be why there is not written documentation yet; those who know don’t need the documentation, and those who don’t can’t write it.
>
> So, to help me, Vedran and others, could someone with the right knowledge document the policy on breaking changes (as a QEP, in the documentation, or elsewhere)? Something that addresses questions such as:

Ok, to summarise discussions to date:

> * When may C++ API be broken? When may C++ ABI be broken?

At ANY stage. C++ api is not (and has never been) part of the stable
API contract.

> * When may Python API be broken?

Usually never. For 4.0 it may be broken ONLY when it directly relates
to Qt 6 / PyQt 6 changes. And even then breakage will be discouraged
and monkey-patched compatibility solutions preferred instead.

> * Does QGIS only care about backwards-compatibility, or also forwards?

Backwards only.

> * Are object names (such as of widgets) considered API subject to the previous questions, or implementation details? (some plugins depend on the names)

Not part of the stable API contract. Neither are any custom object
properties, XML structures, etc. Only things listed in
https://qgis.org/pyqgis are stable API. (Although even some of that is
marked as experimental/private API and is subject to change!)

> * Is deprecated functionality exempt from the above? (that is, if the answer to the first question is "only in major versions", may methods marked as deprecated be removed within a major version after having been deprecated for a given number of versions or time)

No, they must remain for the duration of the major release (i.e. the
lifetime of 3.x). And in the case of 4.0 we are extending this to
state that ONLY methods DIRECTLY relating to Qt 6 transition can be
removed.

> * When may significant UI changes happen?

At any stage

> * What about file formats (such as project files)?

At any stage

> * What is the process for breaking changes? Do they always require a QEP?

As above, changes which break the Python API are NOT part of routine
development. Other forms of breakage are permitted with/without a QEP.
>
> I think it would also be helpful to get some indication of the longer-term strategy (even if it's just a general thought for now, not a hard deadline). If QGIS 4 is intended to just focus on Qt 6, does this mean that there'll be a QGIS 5 in the near future (say 2-4 years) which may include other breaking changes? Or will the next opportunity for breaking changes be in another 7 years?

Yes, there will be a 5.0 sometime in future where non Qt-related API
will be broken. It will not occur for at least 2-4 years though!

(Note that I plan at some stage to document the stable API contract
formally via a QEP, but that requires time I don't have right now!)

Nyall

>
> Jan Dalheimer
> Sweco Sverige AB | Gävle
>
> -----Ursprungligt meddelande-----
> Från: QGIS-Developer <qgis-developer-bounces at lists.osgeo.org> För Jürgen E. Fischer via QGIS-Developer
> Skickat: den 25 april 2025 12:43
> Till: qgis-psc at lists.osgeo.org
> Kopia: qgis-developer at lists.osgeo.org
> Ämne: Re: [QGIS-Developer] [Qgis-psc] Fwd: QGIS 4.0 publicly announced - right time for propose and implement breaking changes?
>
> Hi,
>
> On Fri, 25. Apr 2025 at 10:14:19 +0200, DelazJ via QGIS-PSC wrote:
> > Just for reference, there are:
> > -
> > https://urldefense.com/v3/__https://github.com/qgis/qgis4.0_api/issues
> > __;!!HBVxBjZwpQ!0lUzry6JbWxdJvhAAj8ho2IsXcYFRsZirGjag3IXisILGrwh2umAtT
> > pqs5zSXPTTD5BWTUUY5EmYytKBtVJ-03w1XqMVsvDQ7w$  (mainly developer
> > oriented, but I think there are issues that may interest end users)
>
> Although this is a bit misleading now - originally we wanted to release 4.0 when we introduce above API changes.
>
> Now we need to switch to Qt6 - because 5 goes EOL - but that's a API break in itself, although we don't do above API changes or other breaking changes in QGIS itself.  And not even huge enhancements - just the few things like CMYK that are already there, but only work with Qt6.
>
>
> Jürgen
>
> --
> Jürgen E. Fischer           norBIT GmbH             Tel. +49-4931-918175-31
> Dipl.-Inf. (FH)             Rheinstraße 13          Fax. +49-4931-918175-50
> Software Engineer           D-26506 Norden            https://urldefense.com/v3/__https://www.norbit.de__;!!HBVxBjZwpQ!0lUzry6JbWxdJvhAAj8ho2IsXcYFRsZirGjag3IXisILGrwh2umAtTpqs5zSXPTTD5BWTUUY5EmYytKBtVJ-03w1XqOSuKMpeQ$
> QGIS release manager (PSC)  Germany                 IRC: jef on Libera|OFTC
> _______________________________________________
> QGIS-Developer mailing list
> QGIS-Developer at lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer