[MAINTAINER SUMMIT] Enforcing API deprecation

[Bartosz Golaszewski <bartosz.golaszewski@linaro.org>]

I am not sure how many other maintainers are affected by the issue I'm
about to describe but I imagine it impacts to some degree all
subsystems that have existed for a long time, have undergone
significant reworks and whose API is used ubiquitously tree-wide
across many files. Power-management and device properties/driver core
APIs come to mind as potential examples and I personally face it with
the GPIO subsystem.

Deprecating legacy programming interfaces after introducing better
alternatives is a natural result of the way the kernel is developed
and the size of the codebase. We typically cannot rework interfaces in
a single patch or series series, especially when dealing with existing
cross-tree consumers.

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).

A lot of less experienced driver developers write their code by simply
copy-pasting from existing modules without checking whether given
symbols are marked as deprecated.

There are several things that look like potential solutions:
1. Use gcc's __attribute__((deprecated)) (Linus doesn't like it[1] and
with hundreds of calls to convert it wouldn't be acceptable).
2. Use keywords in MAINTAINERS entries (this sounds like an abuse of
what this file is really for and can sometimes be hard to get right.
Also: see above about it not being very efficient).
3. Make checkpatch.pl check the patches for new uses of deprecated
APIs (similarly to what it does for invalid usage of memory and log
helpers)
4. Make build bots detect it.

And probably many more I haven't thought of.

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.

Best Regards,
Bartosz Golaszewski

[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=771c035372a036f83353eef46dbb829780330234