LWN: Comments on "Toward a kernel maintainer's guide"

Local customs as signalling mechanism

sdalley — Mon, 17 Dec 2018 11:02:33 +0000

Well, yes indeed. Absence of the smiley amplified the LOL by enhancing the image of the rule being uttered with the utmost seriousness by some po-faced pompous twit.
[pauses to collect myself]

Toward a kernel maintainer's guide

djbw — Sun, 16 Dec 2018 02:06:30 +0000

Ah, it's a fair point, especially how long it has taken to find time to get this going, i.e. just start collecting links to lore.kernel.org archives of these examples. I do think there is some value to writing a preface, but probably less than I think. I'll start with that with some rough categories to gather the links I know about and worry about longer winded curation later.

Toward a kernel maintainer's guide

marcH — Sun, 16 Dec 2018 01:24:04 +0000

> "Don't Repeat Yourself" (DRY) is a good principle, but when the document is not written yet, please do repeat until someone takes the initiative and writes it down.

The point I tried to make: it's barely more effort to wrap an email answer / "upgrade" it to a documentation patch (submitted by... email?). So little more that it pays off as soon as the second time the same question comes again.

Now of course I forgot the whole documentation system has to be implemented in the first place: https://xkcd.com/974/
Cheap shot sorry, I can imagine there's a real effort to get all this started and fair play Dan.

PS: I'm considering my next Linux distro to be Arch purely based on their... wiki.

Local customs as signalling mechanism

marcH — Sun, 16 Dec 2018 01:12:02 +0000

I normally refrain from posting this type of comments on LWN but sorry can't resist this time: ROFL.

Lame excuse: the previous comment "forgot" a smiley.

Local customs as signalling mechanism

excors — Sun, 16 Dec 2018 00:47:40 +0000

Surely the position of the rule in the document should depend entirely on the length of the rule, rather than attempting any sort of logical ordering based on the meanings of the rules.

Local customs as signalling mechanism

marcH — Sun, 16 Dec 2018 00:05:27 +0000

> If this theory is correct, then making these "local customs" more publicly visible could undermine their purpose,

I doubt Dan or anyone else will ever surface a "reverse Christmas tree rule" at the very *top* of any new documentation, it'll be buried somewhere in the middle as it should. So gathering and structuring this sort of documentation will only make it look *more* like a [Van Halen] contract that is finally possible to read entirely and will make complying with some "brown M&Ms clause" easier if any.

Toward a kernel maintainer's guide

djbw — Sat, 15 Dec 2018 05:12:01 +0000

"Don't Repeat Yourself" (DRY) is a good principle, but when the document is not written yet, please do repeat until someone takes the initiative and writes it down.

The details on the git repo and a repo map are a good idea. They also dovetail with the recent addition of a kernel.org patchwork-bot that uses a map of the maintainer's git repo to determine when to mark patches "Accepted" vs "Mainline".

Local customs as signalling mechanism

ecree — Mon, 03 Dec 2018 19:20:10 +0000

I have long suspected that the reverse xmas tree rule is a "no brown M&Ms clause"⁽¹⁾. I.e. it's there to give maintainers an easy way to tell whether a submitter has taken the effort to learn and follow the subsystem's rules and practices. One could also look at this as a kind of shibboleth.
If this theory is correct, then making these "local customs" more publicly visible could undermine their purpose, and drive maintainers to impose ever more obscure requirements in an arms race against the people documenting them.

[1] https://en.wikipedia.org/wiki/Van_Halen#Contract_riders

Toward a kernel maintainer's guide

ale2018 — Fri, 30 Nov 2018 11:30:39 +0000

Questions about reasons for doing x or y should always be welcome. In practice, they sound so marginal that readers just skip. Walking through the code together seems to be gone for good, or perhaps it's just not supported by the tools?

Toward a kernel maintainer's guide

karkhaz — Thu, 29 Nov 2018 17:53:14 +0000

Yes, I felt like I was missing something during this whole discussion. The example that keeps coming up is reverse Christmas tree, but that's surely something that can be added to checkpatch.pl or a similar per-subsystem script. Why do maintainers ever need to think about this stuff? Same thing for the suggestion of a maintainer SLA, which will immediately go out-of-date as soon as it's written down---why not an automatic tool that displays maintainers' mean email response time over the past few months, the variance, as well as any recent break in responses that might indicate that they're currently on holiday or otherwise indisposed?

There are probably a few tiny cases where an automated tool wouldn't suffice or should be overridden, but I don't see why a lot of this work can't be replaced with a very small shell script.

Toward a kernel maintainer's guide

bored — Thu, 29 Nov 2018 16:44:26 +0000

If the goal is to remove the no trespassing signs, and reduce the amount of bikesheding, then the solution is an authoritative automated style test and appropriate shaming of people complaining about style violations not enforced by said test.

Humans are error prone, and don't generally enforce rules consistently ("do as I say, not as I do"), no amount of subsystem specific style guides/etc is going to change that unless its programmatically enforced.

Toward a kernel maintainer's guide

ncm — Wed, 28 Nov 2018 21:41:32 +0000

The problem with most coding conventions is that many entries legislate superstitions, often long-debunked ones.

The most pervasive and harmful of these is that programmers get confused by seeing more than one style. Appeals to this myth block improvements. In fact it is always easy to tell which of two styles in a file is the new one, and which is legacy. The useful unit of consistency is the equivalent of a paragraph -- a function, or a block in a bigger function.

The second is that any rule is as good as any another -- that all that matters is consistency. Not having objective evidence for one or other is not the same as that no such evidence is possible. Usually it would be way more work to collect than the difference is worth to one project, but there are plenty of projects conducting the experiment. So, sometimes any rule is better than no rule, but then comes time to step to a better rule. Take it, because it will make a difference.

Toward a kernel maintainer's guide

rweikusat2 — Tue, 27 Nov 2018 22:59:10 +0000

> Indeed, I completely agree with this. I wasn't suggesting that there should be a great "christmas tree debate" kernel wide.
> But that a rule should either be considered sufficiently important to be in the global CodingStyle or it should not exist.

I don't think that's realistic, especially considering that some maintainers enforce coding style regulations which contradict what's written in the CodingStyle text (Patrick "This function is used only once. Get rid of it" McHardy being an example I personally encountered). OTOH, expecting outside contributors (or prospective outside contributors) to read throuhg a few years of a large number of high-volume mailing lists in order to discover "undocumented preferences" of over 1000 people is also not realistic. That's nothing but a camouflaged and guarded "No entry"-sign.

There must be a way for someone to determine which guidelines to follow, ie, a document listing them. Otherwise, one can only try to imitate how the other code is written and that's not a trusty guide: Some "style regulations" are actually not about style at all, they mandate functional differences, even to the point of requiring that code works in an unlogical way. Eg, some people are strongly convinced that all loops ought to be pre-test loops. I don't think so because the initial state is often known and testing a condition known be either true or false seems absurd to me. Nevertheless, I'd gladly follow such a rule if someone considered it important. But there's no way to infer this from code.

Toward a kernel maintainer's guide

nilsmeyer — Tue, 27 Nov 2018 19:19:47 +0000

Since the wiki is disconnected from the code, it may be better to add this Documentation to the source tree.

Toward a kernel maintainer's guide

mfuzzey — Tue, 27 Nov 2018 16:56:19 +0000

> Empirically, this model has worked exceedingly well for a long time, hence, there's no reasonable justification to change it now just because that's unfamiliar to certain people.

Yes, that's what I meant by inertia

>The only "pain" involved here is if style conventions are being enforced (or sometimes enforced, depending on the social situation) which aren't documented anywhere

Obviously if they aren't being enforced there is no pain :)
But if they are enforced, even if documented, it is a pain to those that work in multiple subsystems whereas those that only work in one probably never notice.

>As the paragraph above probably does (and certainly should) suggest, ideally, there would be no (or at least as few as possible) petty regulations at all. That different >
>conventions about these can successfully coexist suggests that they aren't really necessary.

Indeed, I completely agree with this. I wasn't suggesting that there should be a great "christmas tree debate" kernel wide. But that a rule should either be considered sufficiently important to be in the global CodingStyle or it should not exist.

Toward a kernel maintainer's guide

rweikusat2 — Tue, 27 Nov 2018 16:01:16 +0000

> Having different coding style rules for different parts of the kernel seems to be mostly a pain for everyone involved and I don't see > any reasonable justification other than inertia.

Empirically, this model has worked exceedingly well for a long time, hence, there's no reasonable justification to change it now just because that's unfamiliar to certain people. The only "pain" involved here is if style conventions are being enforced (or sometimes enforced, depending on the social situation) which aren't documented anywhere: There's no way someone who isn't already familiar with whatever petty regulations are considered important can divine knowledge about them. Hence, trainwrecks are guaranteed to occur: Someone's being annoyed that things were done differently despite "everybody knows that THIS is the proper colour for a bikeshed!", someone else finds himself suddenly stepping on hidden landmines despite painstakingly trying to do everything "in the right way".

As the paragraph above probably does (and certainly should) suggest, ideally, there would be no (or at least as few as possible) petty regulations at all. That different conventions about these can successfully coexist suggests that they aren't really necessary.

Toward a kernel maintainer's guide

kdave — Tue, 27 Nov 2018 15:31:00 +0000

I've written 2 wiki pages about process and good practices, and another oriented to coding practices, regarding the btrfs development. They're incomplete, there are namely the recurring topics or things that I'd like people to know before contributing. This should supplement the well known CodingStyle and SubmittinPatch documents, yet many of style or subsystem coding practices get pointed out way too often. This makes me think that nobody reads the pages, unless pointed to. I for one welcome the initiative to gather and document the maintainers' pracitces and preferences so it's more discoverable.

Toward a kernel maintainer's guide

bfields — Tue, 27 Nov 2018 15:29:17 +0000

Having different coding style rules for different parts of the kernel seems to be mostly a pain for everyone involved and I don't see any reasonable justification other than inertia.

I can think of a few.

It takes effort to reach consensus: is a flame war on Christmas-tree declaration ordering really such a high priority?

People have more fun if they're given a little leeway.

The original Documentation/CodingStyle was 193 lines. Looks like currently Documentation/process/codingstyle.rst is 1079 lines. I wonder if people read it.

Toward a kernel maintainer's guide

mfuzzey — Tue, 27 Nov 2018 11:21:06 +0000

I think not all differences are equal.

Having different coding style rules for different parts of the kernel seems to be mostly a pain for everyone involved and I don't see any reasonable justification other than inertia.

On the other hand having somewhat different *processes* in terms of git trees, review rules, cycle time etc for different subsystems makes a lot more sense since maintainers do have different workflows and the "best" workflow is certainly also very dependent on the size of the subsystem (in terms of patch volume and number of developers).

Toward a kernel maintainer's guide

k3ninho — Tue, 27 Nov 2018 10:25:25 +0000

>"why do we have these differences in the first place?"
...should always draw the answer that we're adults working together in the varied ways that different people do.

Even if you find a common structure to the workflow, each person will deliver it in their own unique way, from their perspective on the tasks at hand or their understanding of the problem and its solutions to how they work through each task -- the challenge is to share enough information among a team responsible for common success so that people can make progress.

Cat herding teaches us that cats are going to be cats, so let's work with that to communicate and interact in ways which get the best from each kitteh.

K3n.

Toward a kernel maintainer's guide

marcH — Tue, 27 Nov 2018 07:28:26 +0000

> Torvalds, Williams said, provides great explanations of how things should be done "after the storm passes"; he does so patiently, repeatedly, as the same mistakes are discovered anew. Why, Williams asked, isn't this information written down anywhere?

Why indeed?

I almost never answer generic questions directly; I just hate repeating myself too much. I update or submit a documentation update instead and answer with a one-line pointer to the update.

https://en.wikipedia.org/wiki/Don%27t_repeat_yourself

> It would include information like:

As a (former) "consumer" of code freshly merged by maintainers, I would recommend adding the following information:

- where is the git repo where maintainer X shares code he or she just merged, on its way up(stream)
- short "map" of said git repo, notably which git branches are "volatile" versus not (in other words: does using the cherry-pick "-x" option make sense or not)

These seem to be highly maintainer-dependent.

https://chromium.googlesource.com/chromiumos/docs/+/maste...
https://public-inbox.org/git/70ccb8fc-30f2-5b23-a832-9e47...

> It drew the obvious question ("why do we have these differences in the first place?") from the audience, but there isn't really an answer beyond "it has always been that way".

"awareness" is always the first step and documentation achieves that (and more)

Toward a kernel maintainer's guide

unixbhaskar — Tue, 27 Nov 2018 02:54:47 +0000

Sounds interesting though. But, in practice "that's the way it is" is very difficult to get rid of and it will take way more time than one can imagine. And if it does, it will be a damn good thing to happen too.

Toward a kernel maintainer's guide

l1k — Mon, 26 Nov 2018 19:59:02 +0000

FWIW, a document that might be called a "subsystem profile" exists for the PCI subsystem, but isn't part of the tree yet, it was only posted to the list so far.