Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Johannes Berg <johannes@sipsolutions.net>]

On Tue, 2025-08-26 at 21:57 +0200, Bartosz Golaszewski wrote:
> What we usually do is:
> 1. Provide an alternative solution living in parallel to the old one.
> 2. Mark the legacy interfaces as deprecated in their kerneldocs.
> 3. Slowly convert users one by one until the relevant symbols are no
> longer called anywhere in the kernel.
> 4. Remove legacy interface.
> 
> A problem occurs when during step #3 (which may take anywhere from
> several releases to many years depending on how commonly given
> interface is used), developers continue to introduce new calls to the
> deprecated routines. This is not always easily caught, because quite
> often patches using the API of a given subsystem will not be send to
> this subsystem's maintainer (Example: while GPIO core code lives under
> drivers/gpio/, there are lots of provider implementations and even
> more consumers spread tree-wide. I cannot possibly catch every commit
> I'm not explicitly Cc'ed on and eventually some will fly under the
> radar. Also: this is not a good solution if I have to manually object
> every time, this should be more or less automated).

Once most things are converted, copy/paste will die automatically use
the right things. Sure, you might think you're almost there and then a
handful of new users are introduced, but you can actually remove the
APIs in -next and then the new ones fail to build there, if you're that
far along.

I guess you have to ask yourself how much it matters?

Is it a major hassle to keep supporting the old API? Then I guess the
effort to support the old API outweighs the effort to convert it
quickly, so do that?

If the old API just calls the new API or something simple you basically
keep the old API forever (I just looked at PCI MSI APIs which have said
it's deprecated for almost a decade, and yet is still the most commonly
used one ... I guess it didn't matter). If it doesn't matter then really
all you did was introduce an _additional_ API that might let you solve
whatever problem you were trying to solve that the old API didn't let
you solve, but isn't needed for the vast majority of cases?

More nagging etc. really won't change anything except stress maintainers
out even more, make people ignore it, etc. Whoever cares can do the
conversion, but if whoever maintains the API doesn't actually care about
converting it, why should anyone else?

johannes