[PATCH] Improve Documentation/stable_api_nonsense.txt v2

[PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Heikki Orsila]

This is version 2 of the patch. Address Gregs, Matts and Andis comments.
Retain the word "exact" due to request of Greg. Use "the exact
same" as per "Matt Mackall".

* Change wording
* Make a remark about necessary changes in interfaces

Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>
---
 Documentation/stable_api_nonsense.txt |   10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
index 847b342..a7c29ad 100644
--- a/Documentation/stable_api_nonsense.txt
+++ b/Documentation/stable_api_nonsense.txt
@@ -19,7 +19,7 @@ Executive Summary
 You think you want a stable kernel interface, but you really do not, and
 you don't even know it.  What you want is a stable running driver, and
 you get that only if your driver is in the main kernel tree.  You also
-get lots of other good benefits if your driver is in the main kernel
+get lots of other benefits if your driver is in the main kernel
 tree, all of which has made Linux into such a strong, stable, and mature
 operating system which is the reason you are using it in the first
 place.
@@ -69,7 +69,7 @@ consider the following facts about the Linux kernel:
     on another architecture properly.
 
 Now a number of these issues can be addressed by simply compiling your
-module for the exact specific kernel configuration, using the same exact
+module for the exact same kernel configuration, using the exact same
 C compiler that the kernel was built with.  This is sufficient if you
 want to provide a module for a specific release version of a specific
 Linux distribution.  But multiply that single build by the number of
@@ -116,7 +116,7 @@ issues:
 
 This is in stark contrast to a number of closed source operating systems
 which have had to maintain their older USB interfaces over time.  This
-provides the ability for new developers to accidentally use the old
+has the risk for new developers to accidentally use the old
 interfaces and do things in improper ways, causing the stability of the
 operating system to suffer.
 
@@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
 well as they can be (unused interfaces are pretty much impossible to
 test for validity.)
 
+However, changing an interface can be delicate work and it can take
+significant amount of developer effort. Therefore, an interface is
+not changed unless the change is regarded as very important by the
+developers.
 
 What to do
 ----------
-- 
1.5.3.4.GIT

Re: [PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Greg KH]

On Sat, Feb 02, 2008 at 04:44:57PM +0200, Heikki Orsila wrote:
> This is version 2 of the patch. Address Gregs, Matts and Andis comments.
> Retain the word "exact" due to request of Greg. Use "the exact
> same" as per "Matt Mackall".
> 
> * Change wording
> * Make a remark about necessary changes in interfaces
> 
> Signed-off-by: Heikki Orsila <heikki.orsila@iki.fi>
> ---
>  Documentation/stable_api_nonsense.txt |   10 +++++++---
>  1 files changed, 7 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
> index 847b342..a7c29ad 100644
> --- a/Documentation/stable_api_nonsense.txt
> +++ b/Documentation/stable_api_nonsense.txt
> @@ -19,7 +19,7 @@ Executive Summary
>  You think you want a stable kernel interface, but you really do not, and
>  you don't even know it.  What you want is a stable running driver, and
>  you get that only if your driver is in the main kernel tree.  You also
> -get lots of other good benefits if your driver is in the main kernel
> +get lots of other benefits if your driver is in the main kernel
>  tree, all of which has made Linux into such a strong, stable, and mature
>  operating system which is the reason you are using it in the first
>  place.

That's fine.

> @@ -69,7 +69,7 @@ consider the following facts about the Linux kernel:
>      on another architecture properly.
>  
>  Now a number of these issues can be addressed by simply compiling your
> -module for the exact specific kernel configuration, using the same exact
> +module for the exact same kernel configuration, using the exact same
>  C compiler that the kernel was built with.  This is sufficient if you
>  want to provide a module for a specific release version of a specific
>  Linux distribution.  But multiply that single build by the number of

fine.

> @@ -116,7 +116,7 @@ issues:
>  
>  This is in stark contrast to a number of closed source operating systems
>  which have had to maintain their older USB interfaces over time.  This
> -provides the ability for new developers to accidentally use the old
> +has the risk for new developers to accidentally use the old
>  interfaces and do things in improper ways, causing the stability of the
>  operating system to suffer.
>  

fine.

> @@ -145,6 +145,10 @@ as small as possible, and that all potential interfaces are tested as
>  well as they can be (unused interfaces are pretty much impossible to
>  test for validity.)
>  
> +However, changing an interface can be delicate work and it can take
> +significant amount of developer effort. Therefore, an interface is
> +not changed unless the change is regarded as very important by the
> +developers.
>  
>  What to do
>  ----------

I still don't understand why you want to add these sentances.  Why are
they needed?  Are people thinking that the kernel developers just
randomly change things just because they are bored and have nothing else
to do at the moment?  Do people think that our changes are gratuitous?

Even so, I don't think this needs to be added, we have already stated
many good reasons why changing apis are necessary and good.  Do need to
add another one?

thanks,

greg k-h

Re: [PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Daniel Hazelton]

On Saturday 02 February 2008 19:22:49 Greg KH wrote:
> On Sat, Feb 02, 2008 at 04:44:57PM +0200, Heikki Orsila wrote:
<snip>
> > @@ -145,6 +145,10 @@ as small as possible, and that all potential
> > interfaces are tested as well as they can be (unused interfaces are
> > pretty much impossible to test for validity.)
> >
> > +However, changing an interface can be delicate work and it can take
> > +significant amount of developer effort. Therefore, an interface is
> > +not changed unless the change is regarded as very important by the
> > +developers.
> >
> >  What to do
> >  ----------
>
> I still don't understand why you want to add these sentances.  Why are
> they needed?  Are people thinking that the kernel developers just
> randomly change things just because they are bored and have nothing else
> to do at the moment?  Do people think that our changes are gratuitous?
>
> Even so, I don't think this needs to be added, we have already stated
> many good reasons why changing apis are necessary and good.  Do need to
> add another one?
>
> thanks,
>
> greg k-h

Actually, Greg, a hell of a lot of people that don't track linux kernel 
development do think that way. And there are always going to be people that 
think that way.

As it stands the recommended paragraph does clarify that, while the interfaces 
aren't stable, can and will change as needed, there are some core interfaces 
that *WON'T* change without a very good reason. Having such a public 
statement that anyone can see and people can point to is another weapon to 
help people fight the FUD that exists around Linux.

DRH
(And yes, I do fight anti-linux FUD all the time. My parents have been using 
my laptops and can actually be quoted as saying that the next computer they 
buy will run Linux! My family mostly runs Windows - my brothers because their 
kids would complain about not being able to play their games and my sister 
because her husband is so computer illiterate I'm amazed he actually knows 
how to do a Google search)

-- 
Dialup is like pissing through a pipette. Slow and excruciatingly painful.

Re: [PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Greg KH]

On Sat, Feb 02, 2008 at 07:52:37PM -0500, Daniel Hazelton wrote:
> On Saturday 02 February 2008 19:22:49 Greg KH wrote:
> > On Sat, Feb 02, 2008 at 04:44:57PM +0200, Heikki Orsila wrote:
> <snip>
> > > @@ -145,6 +145,10 @@ as small as possible, and that all potential
> > > interfaces are tested as well as they can be (unused interfaces are
> > > pretty much impossible to test for validity.)
> > >
> > > +However, changing an interface can be delicate work and it can take
> > > +significant amount of developer effort. Therefore, an interface is
> > > +not changed unless the change is regarded as very important by the
> > > +developers.
> > >
> > >  What to do
> > >  ----------
> >
> > I still don't understand why you want to add these sentances.  Why are
> > they needed?  Are people thinking that the kernel developers just
> > randomly change things just because they are bored and have nothing else
> > to do at the moment?  Do people think that our changes are gratuitous?
> >
> > Even so, I don't think this needs to be added, we have already stated
> > many good reasons why changing apis are necessary and good.  Do need to
> > add another one?
> >
> 
> Actually, Greg, a hell of a lot of people that don't track linux kernel 
> development do think that way. And there are always going to be people that 
> think that way.

So why would to more sentances trying to say "see, we really do know
what we are doing, we aren't idiots" make things any better to these
people?  (hint, it wouldn't...)

> As it stands the recommended paragraph does clarify that, while the interfaces 
> aren't stable, can and will change as needed, there are some core interfaces 
> that *WON'T* change without a very good reason.

Again, do you think we kernel developers just randomly change core apis
because we are bored and want something to do late at night when we
can't sleep and are tired of playing Rock Band?

> Having such a public statement that anyone can see and people can
> point to is another weapon to help people fight the FUD that exists
> around Linux.

The whole article explains why apis are change for very good reasons
(evolution of hardware, security, we now know better, etc.)  That's the
whole point of the document...

thanks,

greg k-h

Re: [PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Daniel Hazelton]

On Sunday 03 February 2008 00:03:10 Greg KH wrote:
> On Sat, Feb 02, 2008 at 07:52:37PM -0500, Daniel Hazelton wrote:
> > On Saturday 02 February 2008 19:22:49 Greg KH wrote:
> > > On Sat, Feb 02, 2008 at 04:44:57PM +0200, Heikki Orsila wrote:
> >
> > <snip>
> >
> > > > @@ -145,6 +145,10 @@ as small as possible, and that all potential
> > > > interfaces are tested as well as they can be (unused interfaces are
> > > > pretty much impossible to test for validity.)
> > > >
> > > > +However, changing an interface can be delicate work and it can take
> > > > +significant amount of developer effort. Therefore, an interface is
> > > > +not changed unless the change is regarded as very important by the
> > > > +developers.
> > > >
> > > >  What to do
> > > >  ----------
> > >
> > > I still don't understand why you want to add these sentances.  Why are
> > > they needed?  Are people thinking that the kernel developers just
> > > randomly change things just because they are bored and have nothing
> > > else to do at the moment?  Do people think that our changes are
> > > gratuitous?
> > >
> > > Even so, I don't think this needs to be added, we have already stated
> > > many good reasons why changing apis are necessary and good.  Do need to
> > > add another one?
> >
> > Actually, Greg, a hell of a lot of people that don't track linux kernel
> > development do think that way. And there are always going to be people
> > that think that way.
>
> So why would to more sentances trying to say "see, we really do know
> what we are doing, we aren't idiots" make things any better to these
> people?  (hint, it wouldn't...)

I know this, because I've never needed to even read the document to understand 
why the API may have to change. But there are people that are very brain 
dead - I mean *EXTREMELY* brain dead who will start drooling and not 
understand the whole point of the document without a simple statement like 
the above.

It is those people - and I've had a hell of a lot of contact with them 
(including people manning the phones in tech support departments!) - that 
wouldn't understand that the reason for the lack of a "fixed, stable API" is 
because of the various API changes that add capacity.

(Instead they'd say "But MS does it with Windows" - ignoring the fact that the 
Windows API changed when NT3.51 was released, changed again when Win95 was 
released and has changed with *EVERY* release of Windows since - to the point 
that there are programs written for Win95 that can't/won't run on an XP 
machine.)

> > As it stands the recommended paragraph does clarify that, while the
> > interfaces aren't stable, can and will change as needed, there are some
> > core interfaces that *WON'T* change without a very good reason.
>
> Again, do you think we kernel developers just randomly change core apis
> because we are bored and want something to do late at night when we
> can't sleep and are tired of playing Rock Band?

No, I don't. Never have. But the fact is that there *ARE* people who do think 
that way. I've had a hell of a lot of contact with them. When I talk to 
people about using Linux (locally - I get "pinged" by someone every time I 
walk into a store to buy something, anymore) there is at least one person who 
complains that they can't run Linux because required hardware X isn't 
supported, and the manufacturer says its because there isn't a stable API to 
write the driver against. (though it's usually a lot coarser and less 
technical - I'm sure you understand)

> > Having such a public statement that anyone can see and people can
> > point to is another weapon to help people fight the FUD that exists
> > around Linux.
>
> The whole article explains why apis are change for very good reasons
> (evolution of hardware, security, we now know better, etc.)  That's the
> whole point of the document...

Yes, it does, but you are making the mistake I used to make all the time and 
assuming that most people are going to actually have the ability to take the 
information in the document and comprehend that any *ONE* of the reasons that 
a stable API is bad is enough to not have one.

Having such a paragraph to point to - or just having it there when those 
dead-brained people actually find and read the document - will definitely be 
a good thing.

...

And now that I've re-iterated and explained the rather poor opinion I have of 
most people in the world and how it applies to this situation, I'm going to 
shut up and not say another word about this.

DRH

-- 
Dialup is like pissing through a pipette. Slow and excruciatingly painful.

Re: [PATCH] Improve Documentation/stable_api_nonsense.txt v2

[Heikki Orsila]

On Sat, Feb 02, 2008 at 09:03:10PM -0800, Greg KH wrote:
> On Sat, Feb 02, 2008 at 07:52:37PM -0500, Daniel Hazelton wrote:
> > Actually, Greg, a hell of a lot of people that don't track linux kernel 
> > development do think that way. And there are always going to be people that 
> > think that way.
> 
> So why would to more sentances trying to say "see, we really do know
> what we are doing, we aren't idiots" make things any better to these
> people?  (hint, it wouldn't...)

I have similar experience as Daniel..

It seems we need to say that because I have heard some people complain
about the lack of stable interfaces. In fact, I wrote the original patch
just after one person blamed Linux for not having stable interfaces,
and that Linux people just change those APIs to be mean for third 
parties (which is obviously false).

> The whole article explains why apis are change for very good reasons
> (evolution of hardware, security, we now know better, etc.)  That's the
> whole point of the document...

... And the new paragraph supports that goal by assuring others that 
we don't do unnecessary changes.

-- 
Heikki Orsila			Barbie's law:
heikki.orsila@iki.fi		"Math is hard, let's go shopping!"
http://www.iki.fi/shd