From: Linus Torvalds <torvalds@linux-foundation.org>
Newsgroups: fa.linux.kernel
Subject: Re: [RESEND][PATCH] Add /proc/mempool to display mempool usage
Date: Mon, 01 Dec 2008 20:13:32 UTC
Message-ID: <fa.cGd676wsVHtO1iqNmLOjrnz6Qbw@ifi.uio.no>

On Mon, 1 Dec 2008, Pekka Enberg wrote:
>
> Hmm, I thought Documentation/ABI/ was supposed to tell us what's an
> ABI you can depend on and what's not. I mean, you shouldn't be
> depending on anything but the interfaces documented in
> Documentation/ABI/stable/, no?

Who is the f*cking MORON that thinks that "documentation" has any meaning
what-so-ever?

The fact that something is documented (whether correctly or not) has
absolutely _zero_ impact on anything at all. What makes something an ABI
is that it's useful and available. The only way something isn't an ABI is
by _explicitly_ making sure that it's not available even by mistake in a
stable form for binary use.

Example: kernel internal data structures and function calls. We make sure
that you simply _cannot_ make a binary that works across kernel versions.
That is the only way for an ABI to not form.

		Linus

From: Linus Torvalds <torvalds@linux-foundation.org>
Newsgroups: fa.linux.kernel
Subject: Re: [RESEND][PATCH] Add /proc/mempool to display mempool usage
Date: Mon, 01 Dec 2008 20:24:08 UTC
Message-ID: <fa.uRqfZ3b677RhfGkhLzcwYHCCF+8@ifi.uio.no>

On Mon, 1 Dec 2008, Linus Torvalds wrote:
>
> The fact that something is documented (whether correctly or not) has
> absolutely _zero_ impact on anything at all. What makes something an ABI
> is that it's useful and available. The only way something isn't an ABI is
> by _explicitly_ making sure that it's not available even by mistake in a
> stable form for binary use.

Of course, the alternate form is to make it so _useless_ that people won't
use it even if it's available, and I guess we do have those kinds of
interfaces too. But we generally don't need to worry about unused and
useless interfaces very much, so it doesn't tend to matter much.

			Linus

From: Linus Torvalds <torvalds@linux-foundation.org>
Newsgroups: fa.linux.kernel
Subject: Re: [RESEND][PATCH] Add /proc/mempool to display mempool usage
Date: Tue, 02 Dec 2008 02:55:50 UTC
Message-ID: <fa.K1tS4BoXQ2DeWiEIVUzF+Yjk1mI@ifi.uio.no>

On Tue, 2 Dec 2008, Pekka Enberg wrote:
>
> OK, but why do we have those different ABI "stages" in
> Documentation/ABI then? The README file there seems to contradict what
> you say. Or maybe I'm reading it wrong...

I think that whole Documentation/ABI stuff is utter tosh, and should just
be thrown out, whenever it talks about interfaces that are _not_ ABI's.

IOW, it's fine to document things that are actually supposed to be stable,
but:

 - assuming that non-documentation means that it's not an ABI is bogus
   and wrong.

 - explicitly documenting something as "not an ABI" is wrongheaded and
   stupid, because it's meaningless and only sets people up for being
   disappointed later.

So yeah, I think we might as well remove the "testing" one. Right now it
can act in two ways:

 - as documentation on how to use it (ie as "stable").

   This is fine, but then it shouldn't be called "testing", should it?

 - as an excuse for whining later when it _did_ get used, and people break
   exported ABI's, and we need to revert the breakage.

   And this is the one that I don't think is valid. No amount of
   documentation will ever make something less stable.

So as far as I'm concerned, "testing" should either go away (as a way to
discourage people from even _knowing_ about the things, and hoping that
they never get used), or it should be moved to "stable".

And in the end, nothing is ever totally black-and-white or quite that
simple, but that's the mindset you should have.

Finally, when it comes to documentation as a bigger issue:

 - wrong documentation is irrelevant. It doesn't matter if the
   documentation says "X", when the code does "Y".

   If people rely on "Y", then pointing at the docs and saying "but you
   should never have relied on it, because the docs say X" is totally and
   utterly bogus. The _documentation_ was wrong. Don't ever use incorrect
   documentation as an excuse.

Too many people seem to think that documentation is the "final" argument.
It's not. Not even close. It's a hint and a help, but it's _secondary_ to
code. Anybody who doesn't understand that should never be allowed to write
code (or documentation, for that matte).

[ The same is true of assert()'s in code too - I've seen too many damn
  asserts that were simply _wrong_, and then when they triggered, people
  would always blindly assume that the assert() was right, and try to
  change the code to suit. For some reason people have a hard time asking
  themselves whether perhaps the bug was in the assertion itself. ]

			Linus