[Ksummit-discuss] [CORE TOPIC] Reviewing new API/ABI

[Andy Lutomirski <luto@amacapital.net>]

There doesn't currently seem to be any real process for reviewing new
core APIs for sanity of design, appropriateness to solve the problem
they're targetting, or correctness of implementation.  Some examples
that come to mind recently:

 - A lot of people seem to think that O_TMPFILE is a terrible
interface, despite the fact that the functionality it provides is very
useful.  It was also rather badly broken until -rc8 or so.

 - The x86 32-bit vdso clock functions almost made it in with a
questionable symbol version.

 - 3.15 is currently slated to include an unfortunate ABI glitch in
the MIPS seccomp filter interface.  There's a patch.

 - There are some aspects of the keyring API that seem to me to be quite bad.

 - An impressive number of new APIs are missing -EINVAL returns if
reserved parameters are set.

(I'm not trying to point a finger at anyone with these examples;
they're just things that I was involved in to some extent.)

The current process is confused.   For example, I currently plan on
trying to remember to ask Linus to revert the MIPS seccomp stuff or
fix it sometime around -rc6 if the patch hasn't landed, but this
sucks.

I think that the process could be improved.  I think that there are
people who are willing to spend time to read API docs and thinking
about these kinds of issues.  (I am, and Michael Kerrisk seems to do a
fair amount of it.)

I would like to discuss what we could change to make this work better
in the future.  In an ideal world, I would like to see every core API
change come with documentation, tests (possibly simple ones), and a
post, with acks, to a list that covers just API changes.  This might
be tough, but it could add a lot of value.

I've occasionally thought that API docs should live in the kernel tree
in some reasonably well organized place so that patch sets can include
doc patches.  I realize that this is contentious.

I'm sure that other people have other suggestions here.

--Andy

P.S.  I'm not on the invitation nominee list, so if people like this
topic, I'd appreciate a nomination :)