Re: [Ksummit-discuss] [MAINTAINER TOPIC] ABI feature gates?

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 08/09/2017 02:00 AM, NeilBrown wrote:
> On Thu, Aug 03 2017, Andy Lutomirski wrote:
> 

[...]

> My other strawman is to declare that if an API is not documented, then
> it isn't stable.  People are welcome to use undocumented APIs, but when
> their app breaks, they get to keep both parts.  Of course, if the
> documentation is wrong, that puts us in an awkward place - especially if
> the documented behaviour is impossible to implement.  We can then
> schedule the release of the documentation at whatever time seems
> appropriate given the complexity and utility of the particular API.

Given that features sometimes exist for years (and in rare cases
decades) before they are documented, and many longstanding features
remain incompletely documented, the notion that "if an API is not
documented, then it isn't stable" makes no sense, really.

> My main point here is that I think the only real solution here is to
> revise the current social contract.  Trying to use technology to detect
> API changes - as has been suggested in this thread - is not a bad idea,
> but is unlikely to catch the really important problems.

Agreed. There are existing techniques (thorough documentation, more tests)
that, if adhered to more strictly, could certainly alleviate many of the
API design mess-ups. That sort of stuff requires people to really
think about what they are doing, and gives other people greater
insight into what they are doing, and in the process uncovers
implementation and design bugs. (I can't count the number of times
I discovered implementation bugs while I wrote manual pages.)

Some technology to discover API changes would certainly be helpful, but
it doesn't solve the deeper problem. It needs human beings to look
at this stuff. We seem to have learned the lesson that ungoverned API
design leads to chaos in the case of cgroups v1. And the approach in
cgroups v2 made a critical change: there are actually individuals
with overall design responsibility for the interface.

I think that solution could be applied more generally. Have a *paid*
user-space ABI maintainer whose job is to track ABI changes, make sure
that someone has documented them sufficiently well, and that thorough
tests have been written, before the interface can be released in the
mainline kernel.  Ideally, documented real-world use cases, along with
real-world applications using the new interface would also be part of
the package required for acceptance of a new interface.[*]

Cheers,

Michael

[*] Note, by the way, that I'm not proposing that the ABI maintainer
should write the docs or tests (although they might on occasion), 
just that they act as the gatekeeper to make sure that someone has 
done those tasks to a sufficient standard.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/