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

[Emmanuele Bassi <ebassi gmail com>]

On 13 December 2017 at 16:34, Christian Schoenebeck
<schoenebeck linuxsampler org> wrote:
> On Mittwoch, 13. Dezember 2017 12:33:34 CET Emmanuele Bassi wrote:
> > On 13 December 2017 at 12:05, Sébastien Wilmet <swilmet gnome org> wrote:
> > > Ideally, a new major version of a library should only remove deprecated
> > > APIs.
> > The short answer is: that's not how library development works, unless
> > you have a small enough library whose API is inconsequential, or it's
> > used only by a handful of projects. GTK is neither.
>
> The most popular application level frameworks i.e. from Apple, Microsoft, Qt,
> etc. are actually all handling it as expected by application developers; that
> is they usually deprecate old APIs and retain them for many years before they
> eventually (if at all) remove them one day. It is rare that they remove APIs
> without deprecating them first, and in such rare cases there are "usually"
> profound reasons like security aspects (or -cough- "product policies").

In short:

 - GTK supports parallel installation of different major API versions
 - symbols, types, properties, and signals deprecated in a major API
version continue to exist forever (and possibly work as well)
 - new major versions remove the deprecated API from the previous
major API version
 - application developers port their projects between major versions
at their own leisure

The API that gets removed in GTK+ 3.9x is deprecated in GTK+ 3.22 beforehand.

We are not talking about remove API inside the same major version.

Porting applications between major versions is its own effort, just
like porting an application from Windows Vista to Windows 10, or from
macOS 10.6 to 10.12.

> > If we just removed deprecated API without adding any new feature,
> > there would be no incentive whatsoever to port applications to a new
> > major version, which will result in an untested API that we cannot
> > change until the next major release cycle.
>
> Personally I feel with him, although I can live with APIs being removed, even
> without a deprecation phase. A much bigger problem that I see is when
> replacement APIs are introduced which are missing features from their
> predecessors. That happened with at least every major release of Gtk, and I
> see this to happen with Gtk 4 again. I hope some of my patches will be
> accepted to fix a couple of those issues before Gtk 4 will be officially
> released.

Not every new feature or replacement will be 1:1 with deprecated API.
We did not deprecate something because we were tired of how it's
named: we deprecated it because some things should not be done any
more, or because they won't work in a new environment, or because they
exposed some toolkit internals that make changing the toolkit without
breaking applications impossible.

Ciao,
 Emmanuele.

-- 
https://www.bassi.io
[@] ebassi [@gmail.com]