On Wed, 7 Nov 2018 21:51:38 +0100 (CET) Thomas Gleixner <t...@linutronix.de> wrote:
> So I agree with Dan, that we should collect as much documentation from > subsystems/maintainers and get it into the tree so we can: > > - give contributors immediate access to subsystem/maintainer specific > quirks > > - extract common views and move them into the general guidelines > > - have a clear idea which kind of things need to be discussed and agreed > on and what might be left in the susbsystem/maintainer specific > interpretation/expectation realm. Ah, but Dan said: > Not at all, and this is one of the thrusts of my talk next week at > Plumbers. I *do* want to propose that sub-systems document all their > local quirks. My concern is that you're going far beyond "local quirks" here, and actually hiding the real quirks in the process. Just one example from Ingo's email storm this (US/Mountain) morning: > Even after a decade of introducing Git I still see Signed-off-by used as > an Acked-by or Reviewed-by substitutes, so I'd suggest adding this small > explanation as well: > > + SOB chains should reflect the *real* route a patch took as it was > + propagated to us, with the first SOB entry signalling primary > + authorship of a single author. Acks should be given as Acked-by > + lines and review approvals as Reviewed-by lines. If SOB means anything like what it's supposed to mean, this *can't* be a "local quirk" - we have to agree on it globally. If you want to push this into the tree in something like its current form, I'm not going to resist too hard - far be it from me to say we don't want more documentation! But allow me to complain a little. Suppose I came along with my nifty new architecture, and it dragged in a whole new set of timer and interrupt subsystems that duplicated a lot of what's in the kernel now, but buried a few "local quirks" deep in the middle. "Don't worry", I say, "we'll factor out the common stuff later once we figure out what it is; I'd rather not deal with the bikeshedding now". Correct me if I'm wrong, but I suspect I might just get a response back from you. That's not how we normally do things. This proposal takes a similar approach to the documentation. Changelog rules, your comment rules (other than tail comments), brace rules, line breaks, etc. are common stuff; if they are not well-enough documented in the global docs, the fix should really be applied there. If it lands in the current form, you know as well as I do that it will almost certainly stay there for years, if not indefinitely. IMO, the subsystem-specific documentation should be something that an existing kernel developer can use to quickly learn how to avoid surprises when wandering into a different subsystem. So it should be concise and strongly focused on the local customs. If we don't start that way, I'm afraid we'll never have that. Then developers will miss the important information, and we'll reinforce the image of the kernel project as a collection of little fiefdoms that one wanders into at one's own risk. And Documentation/ will continue to be a painful mess. </soapbox> Might it be worth asking Ted for a kernel summit slot to talk about this next week? (And thanks again for doing this! I like the material and think we definitely want it.) jon
