Re: [MAINTAINER SUMMIT] Enforcing API deprecation

[Linus Torvalds <torvalds@linux-foundation.org>]

On Tue, 26 Aug 2025 at 13:28, Jiri Kosina <jikos@kernel.org> wrote:
>
> > If you are not willing to fix up all existing users, and you introduce
> > a parallel API, then you are the one that maintains both the old and
> > the new API forever.
>
> I don't disagree, I just feel that it's important to note that it's pretty
> much impossible to do a proper functional testing of many such
> conversions.

Yes.

And I think the takeaway from that should be "think through the API
conversion before you go wild".

If you can't automate a good 1:1 conversion that is clearly a no-op,
maybe your new API is just complete garbage.

Honestly, if a new API is not a 100% obvious proper superset of the
old one, WTF are you doing?

IOW, if you are creating a new API that doesn't express the EXACT SAME
behavior as the old API did as one part of it, I think your new API is
likely complete and utter shite.

So the starting point should be that any new API can AT LEAST express
the old API as one situation.  If you can't do that, don't even start.

And then, as a second step, think about how you express the new API so
that it's _easy_ to convert with automation.

Exactly so that you don't have to test every single conversion,
because when it comes to most drivers, that simply isn't an option
when hardware access may be very questionable.

(In some other areas, you *can* test things - at least in theory,
architecture interfaces and filesystems should be things that you can
ask people to actually test, because there are only a handful of cases
- and automating it may not be possible anyway, because some new
architecture feature may require writing some new assembly sequence
etc)

And yes, I agree that a lot of API conversions have *not* been done
with those "proper superset" and "easy conversion" steps in mind. We
obviously have had a lot of parallel API's all over the kernel, some
of them living for years.

The biggest pain points are often semantic locking issues, and the VFS
layer kept those duplicate "locked or shared" operations around for a
long time - we introduced the 'shared' directory iteration back in
2016, and the locked version *finally* went away in 2023, so it stayed
around for over seven years..

But maybe sometimes the API changes are just too damn big in the name
of "let's get it right".

Perfect is often the enemy of good. Making the new API easier to
convert to, in the name of making for a smoother development model,
may be the right thing to do, even if maybe the new API isn't then
everything you would want it to be.

I suspect Bartosz comes at this from the recent GPIO setting changes,
and honestly, I do think that could have been done with a coccinelle
script originally, instead of doing a parallel API at all.

             Linus