Standard indentation of arguments

Standard indentation of arguments.
I use right blank space to displace the last table, in order to make the arguments alining. For example:

old:
extern void test_fun(struct list_head *new,

			struct list_head *prev,
			struct list_head *next);
new:
extern void test_fun(struct list_head *new,
		     struct list_head *prev,
		     struct list_head *next);

---
 include/linux/list.h |   27 ++++++++++++++-------------
 1 files changed, 14 insertions(+), 13 deletions(-)

index 08cf4f6..6d16696 100644
@@ -49,8 +49,8 @@ static inline void __list_add(struct list_head *new,
 }
 #else
 extern void __list_add(struct list_head *new,
-			      struct list_head *prev,
-			      struct list_head *next);
+		       struct list_head *prev,
+		       struct list_head *next);
 #endif
 
 /**

@@ -91,7 +91,8 @@ static inline void list_add_tail(struct list_head *new, struct list_head *head)
  * the prev/next entries already!
  */
 static inline void __list_add_rcu(struct list_head * new,
-		struct list_head * prev, struct list_head * next)
+				  struct list_head * prev,
+				  struct list_head * next)
 {
 	new->next = next;
 	new->prev = prev;

@@ -138,7 +139,7 @@ static inline void list_add_rcu(struct list_head *new, struct list_head *head)
  * list_for_each_entry_rcu().
  */
 static inline void list_add_tail_rcu(struct list_head *new,
-					struct list_head *head)
+				     struct list_head *head)
 {
 	__list_add_rcu(new, head->prev, head);
 }

@@ -220,7 +221,7 @@ static inline void list_replace(struct list_head *old,
 }
 
 static inline void list_replace_init(struct list_head *old,
-					struct list_head *new)
+				     struct list_head *new)
 {
 	list_replace(old, new);
 	INIT_LIST_HEAD(old);

@@ -235,7 +236,7 @@ static inline void list_replace_init(struct list_head *old,
  * Note: @old should not be empty.
  */
 static inline void list_replace_rcu(struct list_head *old,
-				struct list_head *new)
+				    struct list_head *new)
 {
 	new->next = old->next;
 	new->prev = old->prev;

@@ -284,7 +285,7 @@ static inline void list_move_tail(struct list_head *list,
  * @head: the head of the list
  */
 static inline int list_is_last(const struct list_head *list,
-				const struct list_head *head)
+			       const struct list_head *head)
 {
 	return list->next == head;
 }

@@ -346,7 +347,7 @@ static inline void __list_splice(const struct list_head *list,
  * @head: the place to add it in the first list.
  */
 static inline void list_splice(const struct list_head *list,
-				struct list_head *head)
+			       struct list_head *head)
 {
 	if (!list_empty(list))
 		__list_splice(list, head);

@@ -696,7 +697,7 @@ struct hlist_node {
 };
 
 #define HLIST_HEAD_INIT { .first = NULL }
-#define HLIST_HEAD(name) struct hlist_head name = {  .first = NULL }
+#define HLIST_HEAD(name) struct hlist_head name = { .first = NULL }
 #define INIT_HLIST_HEAD(ptr) ((ptr)->first = NULL)
 static inline void INIT_HLIST_NODE(struct hlist_node *h)
 {

@@ -771,7 +772,7 @@ static inline void hlist_del_init(struct hlist_node *n)
  * The @old entry will be replaced with the @new entry atomically.
  */
 static inline void hlist_replace_rcu(struct hlist_node *old,
-					struct hlist_node *new)
+				     struct hlist_node *new)
 {
 	struct hlist_node *next = old->next;
 

@@ -815,7 +816,7 @@ static inline void hlist_add_head(struct hlist_node *n, struct hlist_head *h)
  * list-traversal primitive must be guarded by rcu_read_lock().
  */
 static inline void hlist_add_head_rcu(struct hlist_node *n,
-					struct hlist_head *h)
+				      struct hlist_head *h)
 {
 	struct hlist_node *first = h->first;
 	n->next = first;

@@ -828,7 +829,7 @@ static inline void hlist_add_head_rcu(struct hlist_node *n,
 
 /* next must be != NULL */
 static inline void hlist_add_before(struct hlist_node *n,
-					struct hlist_node *next)
+				    struct hlist_node *next)
 {
 	n->pprev = next->pprev;
 	n->next = next;

@@ -837,7 +838,7 @@ static inline void hlist_add_before(struct hlist_node *n,
 }
 
 static inline void hlist_add_after(struct hlist_node *n,
-					struct hlist_node *next)
+				   struct hlist_node *next)
 {
 	next->next = n->next;
 	n->next = next;

1.5.2.5

I think, there is no "standard" on this. I personally do prefer indentation by tabs.

So do I, but that pales compared to how annoying I find patches that can best be described as anal-retentive. Let the person who writes the code decide how to lay it out.

This is a call for discussion for new maillist on vger.

List name: [email protected]

Rationale: the need for such list has been demonstrated during the last few months by rapid increase in the amount of traffic topical for such list (and completely unrelated to any kind of kernel development) misposted on linux-kernel. A separate list dedicated to this kind of self-gratification would hopefully
* reduce the gag reflex among the l-k readers
* provide a forum where such activity could be indulged in comfort
and safety from mocking
* in cases inspiring Ingo's theory of spontaneous onset of sanity,
shield the emerging sentients from the prejudice created by their previous output.

Exhibit A:

Further examples can be trivially found in l-k archives and will be provided on demand.

Oh, what a marvellous way to encourage new contributors that was. Thank you so much.

For the record: Al speaks only for himself and a lack of expressed disagrement from others should not be taken as agreement.

Sheesh.

From: Andrew Morton <[email protected]>
Date: Wed, 21 May 2008 01:50:37 -0700

Al may not have expressed himself the most pleasant way, but I do agree on some fundamental level with him.

There is way to much useless crap being discussed on this list, and this is a list where the signal level is of an utmost importance for the lists usability.

After deleting all of the noise posted here, I'm often too burnt out to do real work with what's left and just delete that too. :-/ It's worse than the postmaster and list owner mail I process each day for vger.kernel.org

Wouldn't you like me to instead have the energy left to review some useful patches?

As one example, coding style is important and has it's place, but some of these threads get way out of hand. I don't give a flying crap how people want to tab their code when I have some OOPS reports and bug fixes to process!

The priorities are often all wrong, and this isn't the place for inversed prioriries. In that sense Al is totally right on the money.

At times you'd think there wasn't even a kernel newbies list.

Of course I speak for myself. And I am absolutely open about my belief that such _contribution_s_ need to be discouraged. Actively.

Hell, a month ago I mentioned right-justifying text in comments as "we'll never reach _that_" kind of pointless idiocy. And there we are, much closer to that than I ever expected.

I have nothing against contributors. I *DO* have a lot against a very specific class of contributions. Exactly because they actively prevent people from moving on to saner stuff. Rule of the thumb: if a pointless activity can be carried indefinitely long and creates an impression of busy doing something, it ought to be discouraged.

Basically, something one could do as infinitely stretchable time-filler when one _really_ doesn't feel like doing anything that might require thinking. Think of this situations like "I need to write the next part of paper, but I just can't get around to starting it; anything but that - let's rearrange the order of references, rearrange the pencils, whatever".

And that is where I believe Ingo is wrong - dropping the level of acceptable pointlessness of patches does *not* encourage meaningful contributions; it discourages them. Ladder doesn't become more accessible if you extend it down into swamp; there's a reasonable starting level from which one _does_ go up. It's impossible to define formally, but it's quite real and I'm very afraid that it's rapidly getting harder to find. Harder for newbies.

Sheesh, indeed.

There are good ways in which to communicate that and there are bad ways.

Look. This has absolutely nothing to do with that patch. Don't care, doesn't matter, irrelevant, not even going to discuss it in this context.

I have spoken with engineers both individual and within companies who have developed and who plan to develop substantial kernel features. I'm forever explaining to people why they should work to get that code merged up. One reason for their not yet having done so which comes up again and again is apprehension at the reception they will receive. In public. This problem appears to be especially strong in Asian countries. You have just made the situation worse.

But it's not just a self-interest thing. It is inevitably and unavoidably the case that when one senior kernel developer acts like an arrogant hostile dickhead, we will all be increasingly regarded as arrogant hostile dickheads.

It probably did make things marginally worse from that standpoint, but the code style weanies also make things worse, so at least IMHO it's a wash.

I'd suggest that the more aggressive public code reviews and the perception that it is highly painful, time-consuming, and expensive to get code merged up. But of course we need that to maintain quality. Even if we eliminated all code style weanies slapdowns, if a Asian Engineer submits a patchset, and it gets (rightly) ripped to pieces by Cristoph for all sorts of code quality problems, and by Al Viro because it intrdoces tons and tons of deadlocks, we'll still have the potential problem that the Asian engineer feels that he has shamed his company and has to resign or will get fired by his management.

The only way to solve that problem is either to change the perception of Asian engineers and at their companies (and there has been some success along that line that what is being attacked is the code, not the submitter), and we could meet them halfway by offering to do an initial code reivew privately so they don't have to feel that they are getting publically humiliated. (And there is a little of that going on, informally, as well.)

So yes, it's a problem, and I'd agree if this was an gratuitously mean code review. i.e., the difference between, "isn't this a locking hierarchy violation?" vs "Congratulations! You've just completely screwed up VM locking hierarchy, you idiot!".

People have been a bit frustrated by the stupid patches and people who waste time with whitespace patches or running checkpatch.pl on random files, so it's a bit understandable that they might slap down those folks --- and I would hope that one of these Asian engineers would be able to see the difference between a desperately needed slapdown and the reception they might get when they submit a patch to be merged up. (But if they are getting their patches ripped apart during the code review, and that's causing them to lose face inside their company, that's a different problem.)

- Ted

Yes. Their company's problem. I must say I'm getting rather sick of this hiding behind culture. Does anyone think it's good for _anyone_ from any culture to be publicly called upon their mistakes? Public is simply what this development is and what makes it different from other types.

People who can't deal with it either grow up, go away or better still, try their damndest to minimise mistakes to avoid the experience in the first place. That last one in fact is one of the fundamental reason why open source works.

Do feel free to call me a culturally insensitive clod -- I'll wear the badge with pride...

Rene.

Sigh.

There are kernel contributions which have not been submitted partly because their developers are apprehensive about the way in which they will be treated.

This is not theory. It is not a guess. It is not speculation. It is empirical observation.

We have a bad reputation. I think it is largely undeserved nowadays, because things have got a lot better. But once a reputation has stuck, it is hard to get it unstuck.

When I am on the podium and this problem is brought up by an audience member (as regularly happens), my usual response is to say that things have become better, that the problem was discussed at some length at kernel summit a few years ago (as it was) and that people generally agreed that it was a problem and that we should do better and that we are doing better.

And we _are_ doing better. On average. But in this area, averages do not count. It's the maxima which are noticed.

Do note that in the above I did not suggest that the problem isn't real. I'm just suggesting that it's not the _kernel's_ problem. The openness adds significant value to the kernel. I'd say more value then would be brought in by developers who now shy away from the process.

And yes, it's general openness. Noone is being ripped apart when they actually listen to feedback.

The actual case in point was a little odd though. I do not for a minute believe that any serious developer is going to shy away from submitting serious code due to an alignment patch getting a cynical slapdown.

Rene.

Well you should. One person makes a mistake and gets horridly treated in public and this will make others fear the consequences of any mistake they might make.

This could have been handled better, don't you think?

I myself tend be rather apprehensive about making an ass of myself in public as well but the only thing I'm taking away from this particular thread is that not everyone is going to appreciate argument alignment patches. So I'll not submit those. Maybe I'll go to work on rewriting the VM now...

I'm not sure. Triggered myself into this thread mostly due to recent pussy-footing around another culturally biased developer in a thread I was in and the most definite impression I got there was that if it had been me, I'd have been mightely offended. No greater offense than people believing they need to fight your fights for you.

Yes, by now I feel sorry for the poor chap that submitted the patch and now has to sit through this thread and I'd definitely like you even more than I already do (kissy!) if you'd just pick up the bloody thing but telling the Linux citzenship that they can't be... open would be taking too much away I feel.

Rene.

You are joking right?

Thanks,
jaya

But I'd like to second the opinion. This is getting a little too far. We should rather try to at least enforce very basic standards a lot of the crap shoved in doesn't follow instead of wanking around about exact placement of whitespaces.

The real question is whether people who are wanking about whitespace and spelling fixes in comments will graduate to writing real, useful patches. If they won't, there's no point to encouraging them.

- Ted

Guys, get a clue. It doesn't matter what that person did. It is the effect upon *all* other potential developers which is so damaging here. Not upon this individual.

[Andrew Morton - Wed, May 21, 2008 at 10:46:44AM -0700]

| On Wed, 21 May 2008 08:09:39 -0400 Theodore Tso <[email protected]> wrote:
| 
| > On Wed, May 21, 2008 at 06:32:06AM -0400, Christoph Hellwig wrote:
| > > On Wed, May 21, 2008 at 01:50:37AM -0700, Andrew Morton wrote:
| > > > Oh, what a marvellous way to encourage new contributors that was. Thank
| > > > you so much.
| > > > 
| > > > For the record: Al speaks only for himself and a lack of expressed
| > > > disagrement from others should not be taken as agreement.
| > > 
| > > But I'd like to second the opinion.  This is getting a little too far.
| > > We should rather try to at least enforce very basic standards a lot of
| > > the crap shoved in doesn't follow instead of wanking around about exact
| > > placement of whitespaces.
| > 
| > The real question is whether people who are wanking about whitespace
| > and spelling fixes in comments will graduate to writing real, useful
| > patches.  If they won't, there's no point to encouraging them.
| > 
| 
| Guys, get a clue.  It doesn't matter what that person did.  It is the
| effect upon *all* other potential developers which is so damaging here.
| Not upon this individual.
| 

Btw, we have CodingStyle, SubmittingPatches and other, but why don't we have something like KernelNewbieGuide? Don't get me wrong, but there could be written all rules about - what is good to do, what is bad. So a newbiew who wants to be usefull for kernel could read it and decide what should be done. /Don't beat me ;) / And of course I know about kernelnewbie.org but this (even quite short) document could help I think.

- Cyrill -

There are a lot of people out there who would like to try their hands at kernel.org development but who just aren't sure how to start, nor where to start.

One could understand a developer deciding to write a do-nothing whitespace patch as a general throat-clearing exercise, but when asked, I recommend against that. I generally recommend that people just download and test the latest -rc, linux-next and -mm kernels and build and run them. Because they surely will find things which need fixing. Often simple little things like compilation errors, sometimes things which need a bisection search.

For more substantial starter projects the best we have (as far as I know) is http://kernelnewbies.org/KernelProjects, but that's just a teeny subset.

We're not very good at this, I'm afraid. I seem to recall that Rik has offered to help out here, so perhaps whenever one notices a hey-someone-should-do-this project, it could be forwarded to Rik and he can put it up there.

The #1 project for all kernel beginners should surely be "make sure that the kernel runs perfectly at all times on all machines which you can lay your hands on". Usually the way to do this is to work with others on getting things fixed up (this can require persistence!) but that's fine - it's a part of kernel development.

From: Andrew Morton <[email protected]>
Date: Wed, 21 May 2008 12:31:27 -0700

Indeed. A lot of the time I see new people, or people making suggestions to them, so fixated on wanting to implement new features.

To me that is absolutely the wrong way to go about this.

It's so much more useful, for both the community and the individual, to fix bugs. Fixing a bug forces you to learn how the kernel works at least on some level, and fixing a bug always makes Linux better.

Implementing a new feature does not necessarily have either of those two important qualities, so it is never the place for new people to start.

Fixing bugs will give someone a real identity and place in the community.

You want real Linux kernel "street cred"? Fix a lot of bugs, then you can implement a thousand new features and people will take you seriously because you've shown that you can and will fix things.

I think that they are often young and want to get their name associated to something their friends can touch.

Not that much for newbies. Linux is thought^Wknown to be bug-free. People don't get a name by claiming everywhere "hey, I found bug X which I could trigger by doing stupid thing Y, and I could fix it, I've contributed".

On the opposite, they have the ability to say "hey friends, now you can buy webcam XX, I have implemented support for it" (often meaning "I send a PCI ID update"). This is a lot more rewarding for them. I've encountered a lot of them. There is a general culture of visible and measurable results, and that's why people focus more on creating than fixing.

Speaking for myself, I clearly prefer being responsible of getting something to work very well and have happy users than to have a ton of users whine about my bugs. But I know this is not common, and I often see people asking what motivates me in stabilizing things and even if I get paid for this ! On the other side, when the same people see my name on some doc, they suddenly look at me as someone very clever, which is completely stupid, given the fact that I'm probably one of the smallest contributors of new code. But that's the way people compare themselves and judge their fellow men, and it's not going to change :-(

Git certainly has made things worse. We're not as careful as we used to be about credits in the files since everything is in the changelogs. And since it's easier to post 3 whitespace patches than 1 bug fix, there are people posting stupid patches to get their name in a shortlog and tell their friends.

If we want to get more manpower on bug hunting, we should really think about what type of work we need, and simply assign credit to people. Let's maintain scores for people doing painful bisect, posting fixes for real bugs, etc... and get this file directly linked to from kernel.org.

I'm really really sure we'd suddenly get more people working on regressions and provide a fix for their oopses (or even their friends'). Also attribute "tested-by" credits. We need people to test the fixes. Let's incitate them.

I don't know what workflow we could use for this, as it is probably not easy and will require more manual work (or maybe have scripts look for particular tags ?). But I'm sure it works. We should not try to change contributors, just take what is good in them and bring them what they seek.

Willy

People fix bugs when they realize that nobody else is going to do it for them.

Stefan Richter
-=====-==--- -=-= =-=-=
http://arcgraph.de/sr/

That's partly true. But we don't need people to fix all bugs by themselves, otherwise we might take more time trying to fix their own fixes. We most of all need them to *work* on bugs, which is not the same. Actively participating to tests and bug hunting is a very important activity. Let's get the original code author propose a fix once the bug is pointed to.

Willy

Some of us never manage to escape from that level. I dug around, and I've been playing the "What did -mm break on me *this* time?" since 2.5.55-mm1. :)

Let's look at it from another angle:

We should not aim at being good at this.

What do we need more in the kernel:
- people testing development kernels
- people fixing bugs
- people maintaining code
- people reviewing code

What do we already have more than enough:
- people developing new bugs^Wfeatures

If someone wants to do a project that's OK.
And if some kernel developer wants to assist him that's OK.

But in my opinion stuff like "I need a project for university" requests are not our problem, and they tend to not bring much for us.

Offering any serious mentoring for newbies will only keep developers busy who could otherwise do things that would bring more value to the kernel.

And we've just seen that having people who do not even know the basics of C sending dozens of checkpatch cleanups doesn't bring us any gain.

There are many other open source projects where it might be easier to get started and that are really looking for people wanting to get involved.

Fully agreed, and this is the only area I see where a newbie can be a net win for us from the first second.

cu
Adrian

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

There is the question of exactly how long you'd like this project to survive though (in a vibrant form).

Remarked elsewhere recently that a downside of the new development model seems to be missing opportunity for new editions of books with "all new! covers 2.8!" blurps on the cover.

That is, not seeing quality documentation emerge, not seeing mentoring from experienced developers... -- where and how do you want the new developers to come from? If only from business linux as a community thing is as dead as when you'd just close shop.

Rene.

We are drowning in new code, and our biggest problem is to get it properly integrated.

We don't have any shortage in the sheer number of people, and it doesn't seem we'll ever have.

And we have many newbies who come and find themselves areas for useful contributions.

cu
Adrian

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

No, your biggest problem is getting _quality_ new code submitted.

I'd worry that it does seem exactly like that. This thread is (again) about newbies being distracted by the robotic aspects and not moving out
of that easily or quickly -- about a worry that too few new developers
appear.

Useful contributions don't translate one on one into capable future developers.

Rene.

We must also somehow manage to integrate hardware drivers that are initially submitted in a less than optimal state.

But even in the worst case they are a net win.

cu
Adrian

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

*blink*

OK, I give up; how was it supposed to be parsed? I can't come up with any way of reading that sentence that would not be an obvious glaring idiocy and I don't see any obvious typos or word omissions that could have created that.

Surely you are not saying that we are not really looking for more people doing useful work? And doing that without "getting involved"... could any resident Zen master enlighten me? I seem to be unable to figure out how the hell one could pull off such a feat...

Sorry, I am not a native English speaker.

Perhaps my phrase was too long?
Or did I take a word wrongly from the dictionary?

Is it perhaps better understandable as follows:

There are many other open source projects where it might be easier to get started. This is since they are really (=desperately) looking for more people who want to get involved (=want to participate).

Or completely paraphrased:

We cannot offer intensive mentoring for everyone.

But people looking for more mentoring can find this in other open source projects.

cu
Adrian

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

You don't need too - see kernel-newbies and the kernel janitors projects. Especially the former. Give people a bit of support and they'll tend to mentor each other.

Alan

- encouragement to develop in the mainline rather than out-of-tree

- companies being content with out-of-tree drivers or even closed source drivers or no drivers at all, and users having to put up with it

Stefan Richter
-=====-==--- -=-= =-==-
http://arcgraph.de/sr/

I did a talk on Linux "social engineering" at {OSCON, IEEE NW something, and SCALE}. All about what (not) to do, how to do it, etc. Slides for it are available in http://www.xenotime.net/linux/mentor/ .

---
~Randy

[Randy Dunlap - Wed, May 21, 2008 at 12:33:55PM -0700]

| On Wed, 21 May 2008 22:57:25 +0400 Cyrill Gorcunov wrote:
| 
| > [Andrew Morton - Wed, May 21, 2008 at 10:46:44AM -0700]
| > | On Wed, 21 May 2008 08:09:39 -0400 Theodore Tso <[email protected]> wrote:
| > | 
| > | > On Wed, May 21, 2008 at 06:32:06AM -0400, Christoph Hellwig wrote:
| > | > > On Wed, May 21, 2008 at 01:50:37AM -0700, Andrew Morton wrote:
| > | > > > Oh, what a marvellous way to encourage new contributors that was. Thank
| > | > > > you so much.
| > | > > > 
| > | > > > For the record: Al speaks only for himself and a lack of expressed
| > | > > > disagrement from others should not be taken as agreement.
| > | > > 
| > | > > But I'd like to second the opinion.  This is getting a little too far.
| > | > > We should rather try to at least enforce very basic standards a lot of
| > | > > the crap shoved in doesn't follow instead of wanking around about exact
| > | > > placement of whitespaces.
| > | > 
| > | > The real question is whether people who are wanking about whitespace
| > | > and spelling fixes in comments will graduate to writing real, useful
| > | > patches.  If they won't, there's no point to encouraging them.
| > | > 
| > | 
| > | Guys, get a clue.  It doesn't matter what that person did.  It is the
| > | effect upon *all* other potential developers which is so damaging here.
| > | Not upon this individual.
| > | 
| > 
| > Btw, we have CodingStyle, SubmittingPatches and other, but why don't
| > we have something like KernelNewbieGuide? Don't get me wrong, but
| > there could be written all rules about - what is good to do, what is bad.
| > So a newbiew who wants to be usefull for kernel could read it and decide
| > what should be done. /Don't beat me ;) / And of course I know about
| > kernelnewbie.org but this (even quite short) document could help I think.
| 
| I did a talk on Linux "social engineering" at {OSCON, IEEE NW something,
| and SCALE}.  All about what (not) to do, how to do it, etc.
| Slides for it are available in http://www.xenotime.net/linux/mentor/ .
| 
| 
| ---
| ~Randy
|

Anrew, Randy, you just wrote KernelNewbiesGuide I think ;) There are lot of internet sites which could help with what-to-do, and linux-mm.org and kernel.bugzilla.org and more BUT what I've tried to say is that we really have such document inside kernel tree (it could be really short) like:

Which patches are not good for sending to LKML
----------------------------------------------

- Plain whitespace cleanup

Some rules just *known* only if you have an experience in LKML mailing but if someone is sending _first_ patch he ever made he just doesn't know that. That is all. So we need not a link to some inet resource BUT written in file inside of kernel tree. But that is just my (personal) opinion.

- Cyrill -

Yes, a general GettingStarted document would probably be useful. It would hopefully have more what-to-do content than what-not-to-do.

2008/5/21 Andrew Morton <[email protected]>:

I'm in the process of trying to write an initial draft of just such a document right now. I'll post it once I'm a bit more done (gimme an hour or two).

Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

Jesper Juhl:

In theory, that's Documentation/HOWTO. In practice, quite a bit more is needed. I'm actually in the process of writing such a thing as well, with some support from the Linux Foundation. I'll not have it done in an hour or two, though; a version for review in June is more likely...

jon

2008/5/21 Jonathan Corbet <[email protected]>:

Documentation/HOWTO is indeed a very good place to start.

What I'm doing right now is basically reformatting my own notes, emails I've written on the subject, pieces of other documents I've written etc etc and trying to put them in the shape of a Getting Started document. Perhaps getting that compiled into a reasonable document in a few hours is a bit too optimistic, but I'll give it a go, post what I have for review and we can take it from there. :-)

I'd love to read your document once it's ready for review.

Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

2008/5/21 Jesper Juhl <[email protected]>:

Ok, here's a first (very) rough draft of a KernelNewbieGuide document. It can certainly be expanded a lot and my grammar and spelling is far from perfect, but hey, it's a first rough draft :)

Comments are very welcome.

-----8<-----[ cut here ]----->8-----

Kernel Newbie Guide - where to start?
=====================================

New kernel hackers can start here.

A commonly asked question, in many different shapes, on the Linux kernel mailing list is how to get started contributing to the kernel. This document tries to answer some of the common questions, offer some advice, list some do's and do-not's and provide a list of other good resources to visit.

Table of contents
-----
0. Must read documents
1. Documentation
2. How to find things to work on as a beginner?
3. Do I need special hardware or tools to do kernel development?
4. What sort of testing should I do before submitting a change?
5. What version of the kernel should I develop my patch against?
6. My patch was ignored, NACK'ed or flamed, what do I do?

0. Must read documents
---

Every project has some rules about how things are done, what's acceptable and what's not, some expectations about contributers etc. A lot of those rules, recommendations and expectations as far as concerns the Linux kernel are available in a few documents in the source tree.

A list of the "required reading" documents can be found in Documentation/HOWTO in the "Documentation" section, so it will not be repeated here, but please go and find the list of files and do read them (in addition to this document) - you'll be glad you did.

1. Documentation
---

A commonly asked question is what skills are needed in order to contribute meaningfully to the kernel.

The answer depends on what areas of the kernel you want to work on. A good working knowledge of C is a requirement if you want to work with the code, since the kernel is mostly written in C with a little bit of asm thrown in. But you don't have to be a programmer in order to contribute. There are lots of documentation files that need to be kept up-to-date or need to be written, so there's also lots of work to do for a competent writer. And the kernel can always use more testers to make sure the quality is high and bugs are found, reported and fixed.

Another question that gets asked a lot is where to find documentation on the kernel.

The main repository of documentation is the Documentation/ directory inside the kernel source, but there are many other sources.

Many people have written books about the Linux kernel, some are pretty advanced and some are well suited for a new user. Here's a short list of good books to start reading:
Linux Kernel Development, second edition
by Robert Love
Linux Device Drivers, 3rd Edition
by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman
Understanding the Linux Kernel, Third Edition
by Daniel Bovet and Marco Cesati

There are also online resources for documentation - here's one of the better collections:
The kernel documentation list at KernelNewbies
http://kernelnewbies.org/Documents

2. How to find things to work on as a beginner
---

Many people new to kernel development have a hard time finding projects to start out with. The kernel is a large project and it's not surprising that some people find it hard to work out where to begin.

A good way to start is by trying to fix some bugs.

There are plenty of bugs to go around and fixing bugs is a great way to learn since you need to understand (and thus learn) the code surrounding the bug in order to fix it properly, so it usually teaches a lot. Submitting small bug fixes is also a great way to get comfortable with the patch submission process.

Finding bugs to fix is easy. Here are some ways to find useful work to do:

- Build a bunch of 'randconfig' kernels and log the output from the build. Building some 10-20 randconfig kernels usually exposes plenty of warnings and/or errors during the build. Fixing some of those should keep you busy for a while.

- Grep the kernel source for "FIXME", "XXX" and similar comments. They often describe areas of the code that has known bugs, could be optimized, needs review etc. Lots of work to do can be found that way.

- Look through the Kernel Janitors TODO list
(http://kernelnewbies.org/KernelJanitors/Todo) for items of interest, then try to fix some of the issues on the list.

- Go through the kernel Bugzilla (http://bugzilla.kernel.org/) and see if you can fix any of the many bugs filed in it. There's a metric butload of bugs filed in there that need attention.

- Run the 'sparse' tool
(http://www.kernel.org/pub/software/devel/sparse/) against the kernel source and evaluate the problems it finds. Try and fix any real problems it reports.

- Sign up with Coverity (http://www.coverity.com/) to get access to the results of their regular runs of Coverity Prevent against the kernel source. Their static analysis of the kernel source finds many bugs that need fixing. There is lots of good work there that needs doing.

Naturally there's also other work that can be done, like writing a driver for some, currently unsupported, hardware etc, but its probably best to get your feet wet with some bug fixing first.

Try to stay away from doing pointless work, like just fixing up the coding style in a file, reformatting comments etc - it's not worth the effort and your patch is likely to be rejected. Fixing up incorrect comments to be correct, fixing up references to removed or renamed functions/arguments etc is, however, useful and worth doing.

3. Do I need special hardware or tools to do kernel development?
---

In most cases you don't need any special hardware to hack the kernel. Unless you are developing a driver, in which case you need access to the hardware in question, naturally - or if you want to hack on architecture specific code it's probably a very good idea to have access to at least one machine of the type.

As far as tools go, all you really need are the tools compile the kernel (gcc, make etc) and a text editor to edit the source - vi, emacs, joe, almost anything will do fine.

However, while you can do kernel development just fine on your regular desktop/laptop PC, there are some things about having a second PC available that can sometimes make your life easier. When the kernel crashes or just misbehaves slightly (for example if your patch has a bug) it may leave your system in a state where it's difficult to get access to log output or other debug information. In those cases, having a second PC connected to the one running the faulty kernel via ethernet or serial cable and having a netconsole or serial console setup to capture kernel messages remotely can be of great value.

Its also important to remember that a faulty kernel might do anything to your system, so keeping backups of important data if you don't have a dedicated kernel development machine is stongly recommended - if your change (or just the experimental kernel of the day you decided to test) causes data loss and you don't have backups, that's entirely your responsability (and headache).

4. What sort of testing should I do before submitting a change?
---

Testing patches before submitting them is important. Very important. You can't test a patch too much.

At a bare minimum you should test that your patch compiles cleanly without errors or warnings from the compiler and you should at least try booting a kernel with your patch applied to see that it doesn't blow up instantly at runtime.

For some patches it can also be sensible to write a test program to test kernel behaviour with and without your patch. This is especially true for patches that touch user visible interfaces, like modify system call code, change files in ProcFS or SysFS or similar. If there is a way to write a program that tests the impact of your patch, then doing so is a good idea and submitting your test program along with your patch (so other people can test as well and verify the patch) is a great thing to do.

When you submit your change, listing in the submission email exactely what testing you have done is important. The more testing a patch has seen the more likely it will be accepted.

5. What version of the kernel should I develop my patch against?
---

There are many versions of the kernel. Development is happening at a very rapid pace and there are many people maintaining development kernel trees for various purposes. Knowing which one to develop against can be difficult to determine when you are just starting out.

In some cases it's easy; if you are working on a very specific area like the real-time properties of the kernel, then the experimental -tr tree is probably what you want to develop against. In most cases however, you probably want to develop your changes against a reasonably up-to-date snapshot of the mainline kernel (Linus' git tree). Or at least, the latest release-candidate (-rc) development kernel available. If for some reason you can't use a recent snapshot or the most recent -rc kernel, then the most recent stable kernel version is your best bet.

Developing against anything older than the latest stable kernel is likely to be a waste of effort due to the rapid pace of development. Once you finish your patch against a several months (or even weeks) old kernel, your patch runs a great risk of being obsolete or impossible to apply (this greatly depends on the area you work on ofcours cince some areas change more rapidly than others, but do try to submit patches against recent development kernels).

6. My patch was ignored, NACK'ed or flamed, what do I do?
---

When you submit a patch, naturally you hope that the patch gets applied either directly to mainline or to a subsystem tree or testing tree that will eventually carry it to mainline. That, however, doesn't always happen. Sometimes your patch doesn't get any feedback at all or someone comments on it with a NACK (meaning they disagree with the patch and vote that it does not get merged) or you get a bunch of (more or less serious) negative feedback on the patch.

The thing to do when your patch gets no feedback at all and seems to have been ignored by everyone is to, first of all, let some time pass. Not everyone read email daily, so you may get the feedback in a few days.

If some days pass and there's still no response it's time to resubmit the patch. First of all you should check that the patch still applies to the latest development kernel and re-spin it against a recent kernel if it doesn't. The next thing to do is consider whether your subject was good enough; did it clearly state the nature of the patch? You also need to consider whether you submitted the patch to the proper people. You should spend a bit of time trying to work out who's responsible for the code your patch modifies - most areas of the kernel have maintainers, listed in the MAINTAINERS file - look up the maintainer for the area you are modifying and make sure that person (or persons) is on the To: or Cc: list of your email. Adding the author of the original code (sometimes, but not always, the same as the maintainer) to Cc: is usually also a good idea. Authors are often listed at the top of the source files, so look there for a name. You should also generally (unless there's a very specific reason not to) add the linux kernel mailing list and any subsystem specific lists to Cc. Now re-submit your patch with an improved subject and recipient list and see if you get a reply. Sometimes you may have to resend your patch multiple times (putting a week between resubmissions is a good rule of thumb) before someone picks it up - don't give up.

If your patch did not get applied and you recieved an ACK or some criticism about your patch, then your job is easy. If there's a very explicit rejection of the patch by the maintainer of the code with a good reason, then don't bother sending it again, it probably will never be applied. If the patch received improvement suggestions or other review comments, then you should create a new version of your patch that adresses the feedback you get and then re-submit (it's usually a good idea to list what stuff you've adressed when re-submitting).

Hopefully the above has helped you get started with the kernel. Happy hacking. We look forward to your first patch.

=====
Written by: Jesper Juhl, May 2008.

-----8<-----[ cut here ]----->8-----

Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

On Thu, May 22, 2008 at 01:46:28AM +0200, Jesper Juhl wrote:

0. Use your common sense. No hard rules will ever replace that.

If you are familiar with C, reading the kernel source (e.g. starting at system call and going down from there) can be very useful; you will need such skills anyway and you might actually find real bugs.

Asking the questions along the lines "code seems to assume that <this> never happens; why can't it happen and what happens if it does?" is generally welcome, assuming that question is more or less coherent. "I do not understand this code at all" will be less useful and "<this> is <expletives> BROKEN!!! I've found a major hole!!!" would better be right - which is not impossible. Use common sense; if you turn out to be wrong (which is also quite possible), the size of crow you'll have to eat will be directly proportional to the vehemence of the original posting. That applies to all of us - pretty much everyone had been there and probably will be there again and again. On the other hand, do not be surprised if the answer will be "It's because... Umm... Oh, !@#!@#, looks like you've spotted a nasty hole". It also happens and assuming that code is correct just because it is in the tree is a bad mistake. Newbies can and do find serious bugs and doing that can earn one a lot of good will.

Note that fixing up coding style in the code you are modifying is fine, provided that coding style part does not obscure the real changes you are making and the scale of coding style changes is not wildly out of proportion. Again, use the common sense - changing two lines in a function is not a reason to reformat every file in directory while you are at it.

2008/5/22 Al Viro <[email protected]>:

Thanks a lot for your comments Al.
I'll try to incorporate most of it in the next revision of the document.

Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

But fixing them is not so easy...

Sorry for being destructive, but we do not have easy coding tasks for newbies.

If it's easy it's already fixed, and dozens of people following your advice to look at e.g. compile or sparse warnings will only generate much noise, but they'll have a hard time finding anything they are capable to fix.

cu
Adrian

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

2008/5/22 Adrian Bunk <[email protected]>:

A) You are not being destructive, you are doing exactely what I hoped people would do, which is comment on my draft so I can make it better :)

B) You are absolutely right in saying that fixing bugs is not (always) easy. But it's a fact that many people ask questions along the lines of "where do I start?", "where can I find something useful to work on?", "I want to learn, is there some code that needs attention I can start reading?" and similar. I'm simply trying to help the people who ask that sort of questions by providing them with a source of stuff to attack. Whether or not someone will be able to fix a bug is a different issue to whether or not a person can find somewhere to start getting into kernel development in a useful way.

True, and then again, not always. Do 100 randconfig builds and I'm willing to bet that at least a handful of the compiler errors or warnings you encounter can be fixed by simply including a header, moving an #ifdef, fixing a cast, fixing a printk format string or similar.
There are many difficult to fix bugs in the kernel, but there's also still some low-hanging fruit left (and I suspect there will always be).

You may be right, but personally I'm not so sure. The kernel is a large project and we have many people who want to get involved but give up when hitting the very first barrier to entry; finding somewhere to start. Sure, there will be some noise, but I would hope that there would also be many good (if somewhat trivial) patches - and once people get one or two trivial patches accepted they may be encouraged to delve in deeper and do more useful work. Those that can't even fix a simple warning or missing include file error will probably give up whether or not we provide this document or not.

Jesper Juhl <[email protected]>
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

Really. I'd go read some of the less maintained driver code for an afternoon.

Alan

Hmm... yes, we do have easy coding tasks, but you need the hardware.

For example w35und wireless driver is in desperate need of few developers. Many more such projects exist... but you need the hardware.
Pavel

(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

math is hard, lets go shopping -- Barbie

Sorry but if it's too easy, you don't learn from it. If it's not a challenge .... you're going to get stuck and never really learn.

If they only go where they are already capable.. no gain for anyone. A bug can be a challenge, and need a lot of learning and investigating. And that's *FINE*. That's what you learn from. Not from the actual fix itself.

Hi,

- Run a recent development kernel. If you already know an area that might interest you, use the tree of that subsystem. Otherwise Linus' tree. Or the -mm tree.

- Read the mailing list. Again, if you are interested in a specific area, there are also subsystem-related mailing lists, check
http://vger.kernel.org/vger-lists.html.

Probably needs some rephrasing...

Hannes

On Thu, May 22, 2008 at 3:46 AM, Jesper Juhl <[email protected]> wrote:
[...]

[...]

Quite good document, I must say. Jesper, I think that part of text (what to stay away from) *must* be marked special somehow. I'm not sure if every newbie would read this document before sending patch but we will be able to say "Hey, we warned you not the once about useless work! Don't do that again!" (maybe it should be even CAPITALIZED)

On Thu, 22 May 2008, Jesper Juhl wrote:

a couple minor corrections

here you mean the -rt tree, not the -tr tree

here you mean NACK not ACK

David Lang

Suggestions ...

[...]

"buttload"

"tools _to_ compile the kernel"

"of course, since"

"received"

"addressed".

I'd probably make a few grammatical changes too. When you're happy with the content and your document is in the tree, I'll submit a patch :-)

Nick.

PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

Hi,

How about the following?

---

From: Johannes Weiner <[email protected]>
Subject: [PATCH] CodingStyle: no more trivial coding style fixes, please

Add a note to CodingStyle that style cleanups should only be done if the code is really offending and violating the kernel conventions heavily. But no more oneliners fixing indentation and the like.

---

 Documentation/CodingStyle |   12 ++++++++++++
 1 file changed, 12 insertions(+)

@@ -783,6 +783,18 @@ own custom mode, or may have some other 
 work correctly.
 
 
+		Chapter 19:  No coding style patches, please
+
+While all these conventions should be honored when writing new code
+please do not send patches that fix minimal coding style issues only.
+
+If a whole file or several logically connected ones are in a really
+bad shape (i.e. violating several points named here), a patch cleaning
+them up in one go is okay.
+
+But do not send patches that fix indentation of two lines.  It is not
+worth the effort.
+
 
 		Appendix I: References
 

[Johannes Weiner - Wed, May 21, 2008 at 09:42:32PM +0200]

| Hi,
| 
| Cyrill Gorcunov <[email protected]> writes:
| 
| > [Andrew Morton - Wed, May 21, 2008 at 10:46:44AM -0700]
| > | On Wed, 21 May 2008 08:09:39 -0400 Theodore Tso <[email protected]> wrote:
| > | 
| > | > On Wed, May 21, 2008 at 06:32:06AM -0400, Christoph Hellwig wrote:
| > | > > On Wed, May 21, 2008 at 01:50:37AM -0700, Andrew Morton wrote:
| > | > > > Oh, what a marvellous way to encourage new contributors that was. Thank
| > | > > > you so much.
| > | > > > 
| > | > > > For the record: Al speaks only for himself and a lack of expressed
| > | > > > disagrement from others should not be taken as agreement.
| > | > > 
| > | > > But I'd like to second the opinion.  This is getting a little too far.
| > | > > We should rather try to at least enforce very basic standards a lot of
| > | > > the crap shoved in doesn't follow instead of wanking around about exact
| > | > > placement of whitespaces.
| > | > 
| > | > The real question is whether people who are wanking about whitespace
| > | > and spelling fixes in comments will graduate to writing real, useful
| > | > patches.  If they won't, there's no point to encouraging them.
| > | > 
| > | 
| > | Guys, get a clue.  It doesn't matter what that person did.  It is the
| > | effect upon *all* other potential developers which is so damaging here.
| > | Not upon this individual.
| > | 
| >
| > Btw, we have CodingStyle, SubmittingPatches and other, but why don't
| > we have something like KernelNewbieGuide? Don't get me wrong, but
| > there could be written all rules about - what is good to do, what is bad.
| > So a newbiew who wants to be usefull for kernel could read it and decide
| > what should be done. /Don't beat me ;) / And of course I know about
| > kernelnewbie.org but this (even quite short) document could help I
| > think.
| 
| How about the following?
| 
| ---
| 
| From: Johannes Weiner <[email protected]>
| Subject: [PATCH] CodingStyle: no more trivial coding style fixes, please
| 
| Add a note to CodingStyle that style cleanups should only be done if the
| code is really offending and violating the kernel conventions heavily.
| But no more oneliners fixing indentation and the like.
| 
| Signed-off-by: Johannes Weiner <[email protected]>
| ---
| 
|  Documentation/CodingStyle |   12 ++++++++++++
|  1 file changed, 12 insertions(+)
| 
| --- a/Documentation/CodingStyle
| +++ b/Documentation/CodingStyle
| @@ -783,6 +783,18 @@ own custom mode, or may have some other 
|  work correctly.
|  
|  
| +		Chapter 19:  No coding style patches, please
| +
| +While all these conventions should be honored when writing new code
| +please do not send patches that fix minimal coding style issues only.
| +
| +If a whole file or several logically connected ones are in a really
| +bad shape (i.e. violating several points named here), a patch cleaning
| +them up in one go is okay.
| +
| +But do not send patches that fix indentation of two lines.  It is not
| +worth the effort.
| +
|  
|  		Appendix I: References
| 

I liked it, really. Thanks!

- Cyrill -

From: Andrew Morton <[email protected]>
Date: Wed, 21 May 2008 10:46:44 -0700

You can't have your cake and eat it too Andrew.

It's only a half-story to talk about future contributors when current trends on this list are making things bad for existing folks doing useful work.

You make it sound like it's this one sided story where we have to be all nicey nicey to everybody so that new contributors aren't discouraged, and that's where it ends.

But we're currently encouraging a society of bottom feeders. And bottom feeders, although erroneously perceived as being good for the fish tank, actually end up making the tank more dirty in the end. So this is a trend we have to reverse now.

And we're not going to close cultural gaps by making Al Viro or any other major kernel contributor quiet about things like this. Don't be so naive Andrew. The problem is so much larger than that.

Sigh... <mode=Andrew> Let me make it clear that Davem is not speaking for me </mode>.

It's NOT about personalities of people submitting patches. I don't know them and I absolutely do not believe that either personality per se or expected future behaviour can be derived from the fact of having sent this kind of junk.

So "bottom-feeders" is IMO uncalled for - it presumes far more personal and permanent features that simply are not in evidence.

Moreover, I'm less concerned about demoralizing effects of any description on the existing developers. Sure, that stuff is annoying, but it takes more than that to really screw us.

I *am* concerned about new contributors. Especially ones doing janitor-style work, and yes, it's a great way to get started and it's very much needed. What I've been seeing during the last months is continued devaluation of such work in general. By mixing really worthwhile things with more and more pointless ones in the same bag and by trends that make the low-end side of that more visible at the expense of those newbies who actually do something. I'll abstain from naming names, since I rather doubt that anyone would appreciate being brought into this flamefest in any capacity, let alone as an exhibit of what one _should_ do in opinion of some participants, but we still get new people who move on to doing sane work.

Look at that as a dynamic system. Most of us do different kinds of work - a mix of various tree- or subsystem-wide janitorial stuff, diving into isolated drivers, API cleanups, bug hunting of various kinds, regression tracking, development of new code, be it individual drivers or new features in subsystems, etc. The mix varies from person to person and from week to week. Right? Maintaining subsystems is just one more thing in the mix - it's not something inherently special or permanent, BTW.

We all keep moving on to some extent; what matters is the dynamics of that. At some point things get interesting enough to encourage one to keep going - and to go for non-trivial work, simply because one stumbles across the things that need to be done, because one gets a neat idea and knows enough to start making it work, because one runs into things that are challenging enough to make it tempting to pull them off and see what else becomes possible. That's the steady state.

Again, that applies to newbies as well as those who'd been at that for more than a decade. Hell, for more than a decade and half, while we are at it. And we need more people entering and staying in that state - I hope everyone agrees with that.

Now look at what's outside that area; for one thing, there are all kinds of burnouts. Some are handled by changing the area, with or without pyrotechnical effects; some end up with developer simply walking away. Some simply switch to lower and lower activity levels without anything burnout-like and fade away, completely or not.

On the other end there are folks who hadn't entered the aforementioned steady state yet, but are interested in trying to do something. And *that* is where we have a growing mess that scares the living hell out of me. We are getting another self-contained area. Namely, "pick a pointless mechanical work out of ever-growing pile, do it, learn nothing, pick more, maybe look into finding new classes of such mindless stuff". Of course it always had been there; what changes is that now it's not just a transient state one might hit on the way in to be slightly embarrassed about years later. It gets more visible, it gets self-sustained and it gets more and more sticky - it became a subculture in its own right and as far as I can see it is offering more and more incentives to stay in it instead of moving on.

And it sits right on the way (OK, one of the ways - the widest one) into the community. Andrew, please realize that it's not a rethorical exercise - I'm trying to explain what is really, honestly scaring me a lot about the current situation. Do you see any ways to deal with that mess? Do you at least agree that we have a problem there?