Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

On Tue, Aug 26, 2025 at 10:24:42PM +0200, Johannes Berg wrote:
> 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?

As Bartosz mentioned, some new users of those deprecated APIs may not
even know that they should use a different API. Adding warnings to
checkpatch could help raise awareness. I don't think that would stress
out maintainers, and while some authors may ignore it, it seems worth it
to me: it's low effort, not intrusive, and can help developers who
refactor code without much drawback.

-- 
Regards,

Laurent Pinchart