First deprecate APIs and then remove them in the next major version

[Sébastien Wilmet <swilmet gnome org>]

Hi,

I'm a bit worried about how GTK+ 4 is developed. It seems that there
will be a lot of API breaks that will require to adapt the code at once.

Ideally, a new major version of a library should only remove deprecated
APIs. It's how a library should be developed, in case the developers
want to get rid of old APIs: 1. New APIs are added. 2. Old APIs are
marked as deprecated (but still work). 3. In the next major version,
deprecated APIs are removed.

Why is it a good practice to follow that approach? Because developers
using the library can port their code to the new APIs *incrementally*.
The deprecated APIs still work, so the code can be ported to the new
APIs, one step at a time, by writing small and testable commits (for
each commit, the code can be compiled, running the unit tests, testing
the GUI, etc). Not with one huge commit/branch, untestable until all the
code is ported.

It is more work for the library developers to keep the deprecated APIs
still working, but it provides a much smoother experience for all the
developers using the library (and in case of GTK+, there are a lot of
users). Can I remind you that most of the biggest GTK+ apps are still
using GTK+ 2? MonoDevelop, GIMP, Ardour, …

With the new model of GTK+ development, each stable GTK+ 3.9x version
can be seen as a new major version, so that developers can port their
code to 3.90, then 3.92, etc (if those versions are in a sufficiently
usable state). But currently, with how those versions are developed,
it'll be quite hard to port the code, the same as the GTK+ 2 -> 3
transition, because there are direct API breaks instead of just removing
deprecated APIs.

So, that's it, I think when GTK+ 4.0 will be released, if it is still
developed in the same way, developers will have a really bad surprise
when trying to port their code. At least 2 years worth of direct API
breaks… GTK+ 4 will probably be awesome for writing new applications,
but it'll probably be a different story for developers wanting to port
their code from GTK+ 3.

GTK+ 3 was criticized for being a bit unstable. But that was not the
root of the problem IMHO, the root of the problem is that there are
direct API breaks (and for GTK+ 3, the CSS was not sufficiently
advertised as having an unstable API; it's fine to have unstable APIs in
a library, but there must be big warnings in the documentation).

My 2 cents,
Sébastien