Re: [MAINTAINER SUMMIT] Enforcing API deprecation

Julia Lawall
2025-08-27T14:59:18Z

[-- Attachment #1: Type: text/plain, Size: 3428 bytes --]

On Wed, 27 Aug 2025, Bartosz Golaszewski wrote:

> On Tue, 26 Aug 2025 at 22:12, Linus Torvalds
> <torvalds@linux-foundation.org> wrote:
> >
> > On Tue, 26 Aug 2025 at 12:58, Bartosz Golaszewski
> > <bartosz.golaszewski@linaro.org> wrote:
> > >
>
> [snip]
>
> > > 4. Make build bots detect it.
> >
> > Fine, but doesn't solve anything.
> >
>
> How so? The developer gets an email telling them they used a legacy
> API, the maintainer sees a build bot report and knows to ignore the
> patch. That's already better than what we (don't) have currently.
>
> > > I would like to propose a discussion on how to enforce API deprecation
> > > in a way that supports efforts to reduce technical debt, without being
> > > hampered by developers and maintainers who mean no harm but simply
> > > don’t know any better.
> >
> > Here's the only thing that works: if you change the API, you have to
> > fix up all existing users.
> >
> > 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.
> >
> > Or at least until somebody else did the work that you weren't willing to do.
> >
>
> That sounds great in theory but in practice, one may be willing to do
> the work and it will still take years (as is the case with GPIO) where
> there were thousands of calls to the legacy API and - due to the
> nature of the differences between the old and new one - the
> conversions are far from trivial.
>
> I'm not advocating a policy change, I'm trying to bring up the subject
> of making the effort easier for those who participate in the tree-wide
> refactoring.
>
> > End result: the burden of new / different API's is on the person
> > introducing them. IOW: don't introduce new API's unless you are
> > willing to support them.
> >
>
> I would assume, kernel developers in general and maintainers in
> particular want to make linux better. An old API may have been
> introduced long ago in times where we didn't know what we didn't know
> (or even implemented by completely different people altogether) and
> the new one, implemented later, is objectively better.
>
> Sometimes a new API is close enough to the old one, that it can simply
> be wrapped in backward compatible inline functions and the
> implementation is the same for both. That's awesome and supporting the
> legacy interface is not a big problem in this case. However, in other
> cases, the underlying change in philosophy can be so fundamental that
> we effectively end up with two intertwined implementations where a lot
> of code could simply be removed once we unify all the users. In our
> case, the work IS happening and several people are contributing. My
> point is: this effort is commendable and should be supported rather
> than brushed off with a "that's the API's author problem". I'm sure I
> don't have to even name the advantages of having less code to
> maintain.
>
> And to address your last sentence on a personal note: thing's arent
> always so black and white - for me: I inherited the GPIO subsystem
> with both the old and the new API already present tree-wide and am
> just trying to improve the pre-existing situation.

Is there some centralized place listing what APis need attention and
giving some hints about what should be done? Hints could be text or
change examples or pointers to commits where the change has been done.

julia