Skip to contentSkip to conversation

Improve Documentation/stable_api_nonsense.txt v2

PATCH In review Heikki Orsila 3 participants 6 messages Feb 2, 2008 – Feb 3, 2008 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Improve Documentation/stable_api_nonsense.txt v2

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

---
 Documentation/stable_api_nonsense.txt |   10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)
Documentation/stable_api_nonsense.txt +7 -3
index 847b342..a7c29ad 100644
@@ -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
 ----------
Signature · 1 line
1.5.3.4.GIT
#1 lore raw
Quoted 17 lines · 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

---
 Documentation/stable_api_nonsense.txt |   10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)
Documentation/stable_api_nonsense.txt +0 -0
index 847b342..a7c29ad 100644

Documentation/stable_api_nonsense.txt Executive Summary · line 25

Quoted 8 lines
Documentation/stable_api_nonsense.txt +1 -1
@@ -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.

Documentation/stable_api_nonsense.txt consider the following facts about the Linux kernel: · line 75

Quoted 9 lines
Documentation/stable_api_nonsense.txt +1 -1
@@ -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.

Documentation/stable_api_nonsense.txt issues: · line 122

Quoted 9 lines
Documentation/stable_api_nonsense.txt +1 -1
@@ -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.

Documentation/stable_api_nonsense.txt as small as possible, and that all potential interfaces are tested as · line 154

Quoted 11 lines
Documentation/stable_api_nonsense.txt +4 -0
@@ -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

#2 lore raw
Quoted 1 line · 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>

Quoted 17 lines

Documentation/stable_api_nonsense.txt as small as possible, and that all potential interfaces are tested as · line 154

Quoted 11 lines
(quoted diff) +0 -0
@@ -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.)

Documentation/stable_api_nonsense.txt +4 -0
+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?

Quoted 7 lines

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)

Signature · 1 line
Dialup is like pissing through a pipette. Slow and excruciatingly painful.
#3 lore raw
Quoted 20 lines · Daniel Hazelton
Quoted 1 line · 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>

Quoted 17 lines

Documentation/stable_api_nonsense.txt as small as possible, and that all potential interfaces are tested as · line 154

Quoted 11 lines
(quoted diff) +0 -0
@@ -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.)

Documentation/stable_api_nonsense.txt +4 -0
+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?

Quoted 8 lines
Quoted 4 lines

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...)

Quoted 3 lines

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?

Quoted 3 lines

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

#4 lore raw
Quoted 28 lines · On Sunday 03 February 2008 00:03:10 Greg KH wrote:
Quoted 27 lines · Daniel Hazelton
Quoted 1 line · 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>

Quoted 21 lines

Documentation/stable_api_nonsense.txt as small as possible, and that all potential interfaces are tested as · line 154

Quoted 11 lines
(quoted diff) +0 -0
@@ -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.)

Documentation/stable_api_nonsense.txt +4 -0
+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?

Quoted 7 lines
Quoted 3 lines

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.)

Quoted 7 lines
Quoted 3 lines

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)

Quoted 7 lines
Quoted 3 lines

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

Signature · 1 line
Dialup is like pissing through a pipette. Slow and excruciatingly painful.
#5 lore raw
In reply to Greg KH
Quoted 8 lines · Greg KH
Quoted 3 lines · Daniel Hazelton

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).

Quoted 3 lines

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.

Signature · 3 lines
Heikki Orsila			Barbie's law:
[email protected]		"Math is hard, let's go shopping!"
http://www.iki.fi/shd