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 teh 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 -- To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
