Documentation/process: Add subsystem/tree handbook

Add a document to the subsystem/maintainer handbook section, which explains what the tip tree is, how it operates and what rules and expectations it has.

Quoted 3 lines · Thomas Gleixner

Add a document to the subsystem/maintainer handbook section, which explains what the tip tree is, how it operates and what rules and expectations it has.

Peter asked me to add a section about locking comments. I added it and forgot to refresh the patch before sending. Delta patch below.

Thanks,

tglx
---

Documentation/process/maintainer-tip.rst +12 -0

@@ -578,6 +578,29 @@ Sentences in comments start with a upper
   usage of descriptive function names often replaces these tiny comments.
   Apply common sense as always.
 
+ 
+Documenting locking requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  Documenting locking requirements is a good thing, but comments are not
+  necessarily the best choice. Instead of writing::
+
+    	/* Caller must hold foo->lock */
+	void func(struct foo *foo)
+	{
+		...
+	}
+

Add a document to the subsystem/maintainer handbook section, which explains what the tip tree is, how it operates and what rules and expectations it has.

Signed-off-by Thomas Gleixner <[email protected]>

---
 Documentation/process/maintainer-handbooks.rst |    2 
 Documentation/process/maintainer-tip.rst       |  796 +++++++++++++++++++++++++
 2 files changed, 798 insertions(+)

Documentation/process/maintainer-handbooks.rst +2 -0

@@ -12,3 +12,5 @@ which is supplementary to the general de
 .. toctree::
    :numbered:
    :maxdepth: 2
+
+   maintainer-tip

Documentation/process/maintainer-tip.rst new file +32 -0

@@ -0,0 +1,796 @@
+The tip tree handbook
+=====================
+
+What is the tip tree?
+---------------------
+
+The tip tree is a collection of several subsystems and areas of
+development. The tip tree is both a direct development tree and a
+aggregation tree for several sub-maintainer trees. The tip tree gitweb URL
+is: https://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git
+
+The tip tree contains the following subsystems:
+
+   - **x86 architecture**
+
+     The x86 architecture development takes place in the tip tree except
+     for the x86 KVM and XEN specific parts which are maintained in the
+     corresponding subsystems and routed directly to mainline from
+     there. It's still good practice to Cc the x86 maintainers on
+     x86-specific KVM and XEN patches.
+
+     Some x86 subsystems have their own maintainers in addition to the
+     overall x86 maintainers.  Please Cc the overall x86 maintainers on
+     patches touching files in arch/x86 even when they are not called out
+     by the MAINTAINER file.
+
+     Note, that ``[email protected]`` is not a mailing list. It is merely a
+     mail alias which distributes mails to the x86 top-level maintainer
+     team. Please always Cc the Linux Kernel mailing list (LKML)
+     ``[email protected]``, otherwise your mail ends up only in
+     the private inboxes of the maintainers.
+

Documentation/process/maintainer-tip.rst new file +25 -0

+       a separate maintainer tree and then aggregated into timers/core
+
+     - clocksource/event driver development happens in the timers/core
+       branch, but patches are mostly applied in a separate maintainer tree
+       and then aggregated into timers/core
+
+   - **Performance counters core, architecture support and tooling**:
+
+     - perf core and architecture support development happens in the
+       perf/core branch
+
+     - perf tooling development happens in the perf tools maintainer
+       tree and is aggregated into the tip tree.
+
+   - **CPU hotplug core**
+
+   - **RAS core**
+
+   - **EFI core**
+
+     EFI development in the efi git tree. The collected patches are
+     aggregated in the tip efi/core branch.
+
+   - **RCU**
+

Documentation/process/maintainer-tip.rst new file +17 -0

+As always apply common sense and aim for consistency and readability.
+
+
+Commit notifications
+--------------------
+
+The tip tree is monitored by a bot for new commits. The bot sends an email
+for each new commit to a dedicated mailing list
+(``[email protected]``) and Cc's all people who are
+mentioned in one of the commit tags. It uses the email message id from the
+Link tag at the end of the tag list to set the In-Reply-To email header so
+the message is properly threaded with the patch submission email.
+
+The maintainers try to reply to the submitter when merging a patch, but
+they sometimes forget or it does not fit the workflow of the moment. While
+the bot message is purely mechanical assume it implies a 'Thank you!
+Applied.'.

Documentation/process/maintainer-tip.rst new file +31 -0

+Coding style notes
+------------------
+
+Comment style
+^^^^^^^^^^^^^
+
+Sentences in comments start with a uppercase letter.
+
+Single line comments::
+
+	/* This is a single line comment */
+
+Multi-line comments::
+
+	/*
+	 * This is a properly formatted
+	 * multi-line comment.
+	 *
+	 * Larger multi-line comments should be split into paragraphs.
+	 */
+
+No tail comments:
+
+  Please refrain from using tail comments. Tail comments disturb the
+  reading flow in almost all contexts, but especially in code::
+
+  	if (somecondition_is_true) /* Don't put a comment here */
+		dostuff(); /* Neither here */
+
+	seed = MAGIC_CONSTANT; /* Nor here */
+

With tail comments the code looks like this:

	res = dostuff(); /* We explain something here. */

	seed = 1; /* Another explanation. */

	mod_timer(&our_object->our_timer, jiffies + OUR_INTERVAL); /* We like to talk */

	res = check_stuff(our_object); /* We explain something here. */
	if (res)
		return -EINVAL;

	interval = nontrivial_calculation(); /* Another explanation. */

	mod_timer(&our_object->our_timer, jiffies + interval); /* This doesn't race, because. */

... while with freestanding comments it's:

	/* We explain something here: */
	res = check_stuff(our_object);
	if (res)
		return -EINVAL;

	/* Another explanation: */
	interval = nontrivial_calculation();

	/* This doesn't race with init_our_stuff(), because: */
	mod_timer(&our_object->our_timer, jiffies + interval);

This comment placement style has several advantages:

- Comments precede actual code - while in tail comments it's exactly the wrong way around.

- We don't create over-long lines nor artificially short tail comments just because we were trying to stay within the col80 limit with the "this doesn't race" comment. The full-line comment was able to explain that the race is with init_our_stuff().

- Freestanding oneliner comments are much better aligned as well: note how ever comment starts at the exact same column, making it very easy to read (or not to read) these comments.

- In short: predictable visual parsing rules and proper semantic ordering of information is good, random joining of typographical elements just to create marginally more compact source code is bad.

- Just *look* at the tail comments example: it's a visually diffuse, jumble of statements and misaligned comments with good structure.

Documentation/process/maintainer-tip.rst new file +9 -0

+Backtraces in changelogs
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Backtraces can be useful to document the call chain which led to a
+problem. Though not all back traces are really valuable because the call
+chain is unique and obvious, e.g. in early boot code. Just copying the full
+dmesg output is adding a lot of distracting information like timestamps,
+module lists, register and stack dumps etc.
+

+ - Fixes: 12char-SHA1 ("sub/sys: Original subject line")

Documentation/process/maintainer-tip.rst new file +16 -0

+
+   A Fixes tag should be added even for changes which do not need to be
+   backported to stable kernels, i.e. when addressing a recently introduced
+   issue which only affects tip or the current head of mainline. These tags
+   are helpful to identify the original commit and are much more valuable
+   than prominently mentioning the commit which introduced a problem in the
+   text of the changelog itself because they can be automatically
+   extracted.
+
+   The following example illustrates the difference::
+
+     Commit
+
+       abcdef012345678 ("x86/xxx: Replace foo with bar")
+
+     left an unused instance of variable foo around. Remove it.

+ - Signed-off-by: ``Patch handler <handler@mail>``

Documentation/process/maintainer-tip.rst new file +5 -0

+
+   SOBs after the author SOB are from people handling and transporting the
+   patch, but were not involved in development. If the handler made
+   modifications to the patch or the changelog, then this should be
+   mentioned **after** the changelog text and **above** all commit tags in

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

Quoted 8 lines · Ingo Molnar

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Quoted 4 lines

Cc <[email protected]> # v4.18 and later kernels

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I think Greg actually prefers we use [email protected], which is a /dev/null target. His bot will then pick up on the tag once it hits Linus' tree.

Quoted 6 lines · Ingo Molnar

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Quoted 6 lines

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable.

Quoted 12 lines · Peter Zijlstra

Quoted 10 lines · Ingo Molnar

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

Quoted 2 lines

Quoted 2 lines

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

Quoted 13 lines · Dan Williams

Quoted 12 lines · Peter Zijlstra

Quoted 10 lines · Ingo Molnar

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

Quoted 8 lines

Quoted 2 lines

Quoted 2 lines

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

I sometimes have fixes that need to be different for different past releases. And there have been cases where RCU patches would apply and build cleanly against releases for which it was not appropriate, but would have some low-probability failure. Which meant that it could be expected to pass light testing. :-/

So I sometimes need a way of saying which versions a given patch applies to, independent of the version into which the bug was introduced.

Quoted 23 lines · Paul E. McKenney

Quoted 13 lines · Dan Williams

Quoted 12 lines · Peter Zijlstra

Quoted 10 lines · Ingo Molnar

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

Quoted 8 lines

Quoted 2 lines

Quoted 2 lines

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

Quoted 8 lines

I sometimes have fixes that need to be different for different past releases. And there have been cases where RCU patches would apply and build cleanly against releases for which it was not appropriate, but would have some low-probability failure. Which meant that it could be expected to pass light testing. :-/

So I sometimes need a way of saying which versions a given patch applies to, independent of the version into which the bug was introduced.

I can understand that you want to limit the scope of automatic backports.

But we really should try to always use of the Fixes: tag. In most cases the SHA1 of the commit in the fixes tag defines the backport scope.

For the rare cases where the buggy commit is really old, but you want to limit the backport scope for a reason then I really like to avoid to overload the Cc stable tag and have a dedicated tag instead. Something like:

    Fixes: 1234567890AB ("subsys/comp: Short summary")
    Backport-to: 4.14

and have that backport tag right under the Fixes tag. If the Backport-to tag is ommitted, the SHA1 defines the scope, but I'm fine with making it mandatory.

If there is really the special RCU case where each and every stable version needs some special treatment then say:

Backport-to: Manual

or whatever sensible word would express it correctly.

The Fixes tag is really valuable when you need to make connections and I know that the people who are looking into safety-critical Linux value the tag because it can be used for tracking and for metrics.

Quoted 23 lines · Paul E. McKenney

Quoted 13 lines · Dan Williams

Quoted 12 lines · Peter Zijlstra

Quoted 10 lines · Ingo Molnar

Documentation/process/maintainer-tip.rst line 366

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

Documentation/process/maintainer-tip.rst new file +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

Quoted 8 lines

Quoted 2 lines

Quoted 2 lines

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

Quoted 8 lines

I sometimes have fixes that need to be different for different past releases. And there have been cases where RCU patches would apply and build cleanly against releases for which it was not appropriate, but would have some low-probability failure. Which meant that it could be expected to pass light testing. :-/

So I sometimes need a way of saying which versions a given patch applies to, independent of the version into which the bug was introduced.

I can understand that you want to limit the scope of automatic backports.

But we really should try to always use of the Fixes: tag. In most cases the SHA1 of the commit in the fixes tag defines the backport scope.

For the rare cases where the buggy commit is really old, but you want to limit the backport scope for a reason then I really like to avoid to overload the Cc stable tag and have a dedicated tag instead. Something like:

    Fixes: 1234567890AB ("subsys/comp: Short summary")
    Backport-to: 4.14

Quoted 38 lines · Thomas Gleixner

Quoted 23 lines · Paul E. McKenney

Quoted 13 lines · Dan Williams

Quoted 12 lines · Peter Zijlstra

Quoted 10 lines · Ingo Molnar

Review

Quoted 5 lines

+ - Cc: ``cc-ed-person <person@mail>``

(quoted diff) +4 -0

+
+   If the patch should be backported to stable, then please add a '``Cc:
+   [email protected]``' tag, but do not Cc stable when sending your
+   mail.

Can I suggest a more canonical form:

Cc <[email protected]> # v4.18 and later kernels

Quoted 8 lines

Quoted 2 lines

Quoted 2 lines

It would be nice if people adding Cc: stable lines would actually try to figure out which exact kernel versions are affected.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

Quoted 8 lines

I sometimes have fixes that need to be different for different past releases. And there have been cases where RCU patches would apply and build cleanly against releases for which it was not appropriate, but would have some low-probability failure. Which meant that it could be expected to pass light testing. :-/

So I sometimes need a way of saying which versions a given patch applies to, independent of the version into which the bug was introduced.

I can understand that you want to limit the scope of automatic backports.

But we really should try to always use of the Fixes: tag. In most cases the SHA1 of the commit in the fixes tag defines the backport scope.

Quoted 7 lines

For the rare cases where the buggy commit is really old, but you want to limit the backport scope for a reason then I really like to avoid to overload the Cc stable tag and have a dedicated tag instead. Something like:

    Fixes: 1234567890AB ("subsys/comp: Short summary")
    Backport-to: 4.14

Ick, no. Just stick to the "Fixes:" tag. My scripts can now track when a patch is backported to a stable tree so that I know to apply it to older ones despite the original patch showing up in a newer release.

And yes, those scripts are new, as Sasha is about to point out all of the places where I missed this in the past :)

Quoted 2 lines · Thomas Gleixner

    Fixes: 1234567890AB ("subsys/comp: Short summary")
    Backport-to: 4.14

Ick, no. Just stick to the "Fixes:" tag. My scripts can now track when a patch is backported to a stable tree so that I know to apply it to older ones despite the original patch showing up in a newer release.

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

Quoted 6 lines · Dan Williams

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

The main annoyance I have with Fixes is because it can be a pain to figure out what the "# <KVER>" would be. Something like:

% tag --contains DEADBEEF | grep ^v | head

doesn't work because kernel version numbers don't sort obviously. So v4.10 comes before v4.3 using a normal sort, and even sort -n doesn't do the right.

I suppose it wouldn't be that hard to write a perl/python script that correctly sorts kernel version numbers, but when the "# <KVER>" is present, I find it convenient.

(Also note that even with fast SSD's and/or everything in page cache, runnning "tag --contains <COMMITID>" will take a good 3-4 seconds, and if the git packs are not in the page cache, and/or you're unfortunate enough to have your git trees on an HDD.... it's not pretty.)

Quoted 6 lines · Dan Williams

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

The main annoyance I have with Fixes is because it can be a pain to figure out what the "# <KVER>" would be. Something like:

% tag --contains DEADBEEF | grep ^v | head

doesn't work because kernel version numbers don't sort obviously. So v4.10 comes before v4.3 using a normal sort, and even sort -n doesn't do the right.

I suppose it wouldn't be that hard to write a perl/python script that correctly sorts kernel version numbers, but when the "# <KVER>" is present, I find it convenient.

(Also note that even with fast SSD's and/or everything in page cache, runnning "tag --contains <COMMITID>" will take a good 3-4 seconds, and if the git packs are not in the page cache, and/or you're unfortunate enough to have your git trees on an HDD.... it's not pretty.)

Quoted 4 lines

(Also note that even with fast SSD's and/or everything in page cache, runnning "tag --contains <COMMITID>" will take a good 3-4 seconds, and if the git packs are not in the page cache, and/or you're unfortunate enough to have your git trees on an HDD.... it's not pretty.)

I recommend the "static cache" or whatever that thing is called, that helps out a _LOT_ with stuff like this. For the kernel tree, which is never rebased, it speeds up this so much.

Quoted 5 lines · Greg KH

Quoted 4 lines

(Also note that even with fast SSD's and/or everything in page cache, runnning "tag --contains <COMMITID>" will take a good 3-4 seconds, and if the git packs are not in the page cache, and/or you're unfortunate enough to have your git trees on an HDD.... it's not pretty.)

Quoted 3 lines

I recommend the "static cache" or whatever that thing is called, that helps out a _LOT_ with stuff like this. For the kernel tree, which is never rebased, it speeds up this so much.

At the risk of asking a stupid question, which cache is this? I don't think it's the untrackedCache; is it the BitmapHashCache?

Quoted 6 lines · Dan Williams

I know at least StGit mail does not grok that "#"notation. I've stopped using it in favor of a "Fixes:" tag. I would think "Fixes:" is preferred over "# <KVER>" if only because it can be used to track fixes to commits that have been backported to stable. Is there any reason for "# <KVER>" to continue in a world where we have "Fixes:"?

The main annoyance I have with Fixes is because it can be a pain to figure out what the "# <KVER>" would be. Something like:

% tag --contains DEADBEEF | grep ^v | head

doesn't work because kernel version numbers don't sort obviously. So v4.10 comes before v4.3 using a normal sort, and even sort -n doesn't do the right.

Documentation/process/maintainer-tip.rst new file +12 -0

+The tip tree contains the following subsystems:
+
+   - **x86 architecture**
+
+     The x86 architecture development takes place in the tip tree except
+     for the x86 KVM and XEN specific parts which are maintained in the
+     corresponding subsystems and routed directly to mainline from
+     there. It's still good practice to Cc the x86 maintainers on
+     x86-specific KVM and XEN patches.
+
+     Some x86 subsystems have their own maintainers in addition to the
+     overall x86 maintainers.  Please Cc the overall x86 maintainers on

Documentation/process/maintainer-tip.rst new file +5 -0

+Variable types
+^^^^^^^^^^^^^^
+
+Please use the proper u8, u16, u32, u64 types for variables which are meant
+to describe hardware or are used as arguments for functions which access

Documentation/process/maintainer-tip.rst new file +10 -0

+
+
+Struct declarations and initializers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Struct declarations should align the struct member names in a tabular
+fashion::
+
+	struct bar_order {
+		unsigned int	guest_id;

Documentation/process/maintainer-tip.rst new file +7 -0

+Namespaces
+^^^^^^^^^^
+
+To improve readability and to allow easy grepping for information the usage
+of consistent namespaces is important. The namespace should be used as a
+prefix for globally visible (inline) functions and variables. A simple rule
+for chosing a namespace prefix is to combine the subsystem and the

Mark recently suggested in one of the ksummit discussions to add subsystem or tree specific maintainer handbooks to document subsystem/tree specific development process information.

The following series adds the general section and the tip tree specific handbook.

Quoted 6 lines · On Wed, 07 Nov 2018 18:10:10 +0100 Thomas Gleixner <[email protected]> wrote:

Mark recently suggested in one of the ksummit discussions to add subsystem or tree specific maintainer handbooks to document subsystem/tree specific development process information.

The following series adds the general section and the tip tree specific handbook.

So this is an idea that has gone around for a while; developers often get into trouble when wandering into an unfamiliar part of the kernel, so documenting the quaint local customs might help. Assuming people actually read the documentation, of course.

What's here seems generally good, but I do have an overall worry that we may want to consider:

- How much do we want to support and document subsystem-specific quirks vs. promoting reasonable and consistent rules kernel-wide?

There is a *lot* of stuff in the new tip manual. Much of it, regarding coding style and the writing of changelogs, really seems like it should be global; if we need better documentation of that stuff, I'd really rather see that advice folded into the central documents. Having two (or more) extensive coding-style documents doesn't seem like it's going to help us.

The stuff that is truly specific to tip seems fairly minimal:

- what goes into tip
- the reverse fir tree thing
- tail comments, or the distaste thereabouts
- subject-line prefixes

Having a tip-specific document that contains only those (plus whatever else I forgot to list) would, IMO, make it much more likely that readers would actually notice (and follow) the stuff that's specific to tip.

See what I'm getting at here? Am I totally out to lunch on this?

Quoted 11 lines · Jonathan Corbet

The stuff that is truly specific to tip seems fairly minimal:

- what goes into tip
- the reverse fir tree thing
- tail comments, or the distaste thereabouts
- subject-line prefixes

Having a tip-specific document that contains only those (plus whatever else I forgot to list) would, IMO, make it much more likely that readers would actually notice (and follow) the stuff that's specific to tip.

Quoted 1 line

See what I'm getting at here? Am I totally out to lunch on this?

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. Then we can refactor the common ones into a global document, have some discussion fodder if some sub-system specific rules can be unified, and otherwise leave the freedom for individual sub-systems to be different as long as it's documented.

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.

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.

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.

Might it be worth asking Ted for a kernel summit slot to talk about this next week?

Quoted 2 lines · Jonathan Corbet

Might it be worth asking Ted for a kernel summit slot to talk about this next week?

Ah, on that, let me complain :-)

My plumbers schedule is already 100% booked with MCs and other things. There is no kernel-summit schedule details available as of yet, but it is already almost certain that I will not have time for anything in that track anyway :/

Quoted 10 lines · On Thu, 8 Nov 2018 16:05:17 +0100 Peter Zijlstra <[email protected]> wrote:

Quoted 2 lines · Jonathan Corbet

Might it be worth asking Ted for a kernel summit slot to talk about this next week?

Ah, on that, let me complain :-)

My plumbers schedule is already 100% booked with MCs and other things. There is no kernel-summit schedule details available as of yet, but it is already almost certain that I will not have time for anything in that track anyway :/

But surely you can find a few minutes to drop by and throw catchboxes at the docs maintainer? :)

I do understand, though, it's going to be a crazy week.

Quoted 2 lines · Jonathan Corbet

Might it be worth asking Ted for a kernel summit slot to talk about this next week?

Ah, on that, let me complain :-)

My plumbers schedule is already 100% booked with MCs and other things. There is no kernel-summit schedule details available as of yet, but it is already almost certain that I will not have time for anything in that track anyway :/

Quoted 4 lines · Peter Zijlstra

My plumbers schedule is already 100% booked with MCs and other things. There is no kernel-summit schedule details available as of yet, but it is already almost certain that I will not have time for anything in that track anyway :/

I thought there was a slot already scheduled on the refereed track, "Towards a Linux Kernel Mainainer Handbook" (Tuesday at 4:45pm) for this purpose?

Quoted 6 lines · Theodore Y. Ts'o

Quoted 4 lines · Peter Zijlstra

My plumbers schedule is already 100% booked with MCs and other things. There is no kernel-summit schedule details available as of yet, but it is already almost certain that I will not have time for anything in that track anyway :/

Quoted 3 lines

I thought there was a slot already scheduled on the refereed track, "Towards a Linux Kernel Mainainer Handbook" (Tuesday at 4:45pm) for this purpose?

I'm not 100% sure that people will pick up that the topic is about a handbook for working with maintainers rather than a handbook for being a maintainer from that title...

Quoted 3 lines · Mark Brown

I'm not 100% sure that people will pick up that the topic is about a handbook for working with maintainers rather than a handbook for being a maintainer from that title...

The intent is a handbook for being a maintainer. However, in the process of describing how a given sub-system is maintained one also needs to describe the local rules. So contributors should be able to glean what matters to a sub-system from a description of how that sub-system is maintained. In other words the direct audience is maintainers, but it also hopefully makes the process more transparent for contributors.

I thought there was a slot already scheduled on the refereed track, "Towards a Linux Kernel Mainainer Handbook" (Tuesday at 4:45pm) for this purpose?

Quoted 4 lines

I thought there was a slot already scheduled on the refereed track, "Towards a Linux Kernel Mainainer Handbook" (Tuesday at 4:45pm) for this purpose?

My expectation is that this will be an actual talk; it seemed rude to assume that Dan had penciled in a block of time for open arguments about the tip-tree handbook :) That said, I'm not feeling a groundswell of support for scheduling another session at this point...

Quoted 4 lines · On Wed, 7 Nov 2018 21:51:38 +0100 (CET) Thomas Gleixner <[email protected]>…

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

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

Quoted 7 lines

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.

Darn. Not much I can argue about.

So, that thing.

I have this ontop of 5.10 along with most comments integrated.

Now, I'm thinking if I start sending those pieces which belong into the main process documentation, the bikeshedding that is going to ensue is going to be insane. And we have day jobs too, you know. :)

Thus, I'm also thinking that I should do this piecemeal and once we've all agreed on one aspect and you've applied it, Jon, I'll carve out and send the next. Rinse and repeat.

How does that sound, makes sense?

Gee...a response from a two-year-old thread...

it's taking me a while to page all of that back in :)

I'd love to see this work get in, I still feel bad about my part in stalling it before.

Piecemeal could certainly work, or we could just try the whole thing and see what happens. We got Thorsten's reporting-issues tome in without much trouble, after all, and that's bikeshed territory if anything is. But whatever works is fine; send stuff and I'll gladly look at it.

Quoted 8 lines

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>