Toward a kernel maintainer's guide

Posted Nov 27, 2018 7:28 UTC (Tue) by marcH (subscriber, #57642)
Parent article: Toward a kernel maintainer's guide

> 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

Posted Dec 15, 2018 5:12 UTC (Sat) by djbw (subscriber, #78104) [Link] (2 responses)

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

Toward a kernel maintainer's guide

Posted Dec 16, 2018 1:24 UTC (Sun) by marcH (subscriber, #57642) [Link] (1 responses)

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

Toward a kernel maintainer's guide

Posted Dec 16, 2018 2:06 UTC (Sun) by djbw (subscriber, #78104) [Link]

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.