Re: [patch 2/2] Documentation/process: Add tip tree handbook

[Paul E. McKenney]

On Wed, Nov 07, 2018 at 06:10:12PM +0100, Thomas Gleixner wrote:
> 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 <tglx@xxxxxxxxxxxxx>

A few more suggestions below, again to new text.  I have, admittedly
uncharacteristically, trimmed the patch.  ;-)

Reviewed-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxx>

> ---
>  Documentation/process/maintainer-handbooks.rst |    2 
>  Documentation/process/maintainer-tip.rst       |  796 +++++++++++++++++++++++++
>  2 files changed, 798 insertions(+)
> 
> --- a/Documentation/process/maintainer-handbooks.rst
> +++ b/Documentation/process/maintainer-handbooks.rst
> @@ -12,3 +12,5 @@ which is supplementary to the general de
>  .. toctree::
>     :numbered:
>     :maxdepth: 2
> +
> +   maintainer-tip
> --- /dev/null
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -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 ``x86@xxxxxxxxxx`` 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)
> +     ``linux-kernel@xxxxxxxxxxxxxxx``, otherwise your mail ends up only in
> +     the private inboxes of the maintainers.
> +
> +   - **Scheduler**
> +
> +   - **Locking and atomics**
> +
> +   - **Generic interrupt subsystem and interrupt chip drivers**:
> +
> +     - interrupt core development happens in the irq/core branch
> +
> +     - interrupt chip driver development happens also in the irq/core
> +       branch, but the patches are mostly applied in a separate maintainer

        - interrupt chip driver development also happens in the irq/core
          branch, but the patches are usually applied in a separate maintainer

> +       tree and then aggregated into irq/core
> +
> +   - **Time, timers, timekeeping, NOHZ and related chip drivers**:
> +
> +     - timekeeping, clocksource core, NTP and alarmtimer development
> +       happens in the timers/core branch, but patches are mostly applied in

          happens in the timers/core branch, but patches are usually applied in

> +       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**
> +
> +     RCU development happens in the linux-rcu tree. The resulting changes
> +     are aggregated into the tip core/rcu branch.
> +
> +   - **Various core code components**:
> +
> +       - debugobjects
> +
> +       - objtool
> +
> +       - random bits and pieces

[ . . . ]

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

   Backtraces help document the call chain leading to a problem. However,
   not all back traces are helpful, for example. early boot call chains
   are unique and obvious. Furthermore, copying the full dmesg output
   adds distracting information like timestamps, module lists, register
   and stack dumps.

> +Reducing the backtrace to the real relevant data helps to concentrate on
> +the issue and not being distracted by destilling the relevant information
> +out of the dump. Here is an example of a well trimmed backtrace::

   In constrast, the most useful backtraces distill the relevant
   information from the dump, which makes it easier to focus on the
   real issue.  Here is an example of a well-trimmed backtrace::

> +  unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000
> +  000000000064) at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
> +  Call Trace:
> +  mba_wrmsr+0x41/0x80
> +  update_domains+0x125/0x130
> +  rdtgroup_mkdir+0x270/0x500

[ . . . ]

> +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
> +component name, e.g. 'x86_comp\_', 'sched\_', 'irq\_', 'mutex\_', etc. For
> +static functions and variables the namespace prefix can be omitted.

   Function/variable namespaces improve readability and allow easy
   grepping.  These namespaces are prefixes for globally visible function
   and variable names, including inlines.  These prefixes should combine
   the subsystem and the component name such as 'x86_comp\_', 'sched\_',
   'irq\_', and 'mutex\_'.  Namespace prefixes may be omitted for local
   static functions and variables.

> +Also be careful when using vendor names in namespaces. There is no value of
> +having 'xxx_vendor\_' or 'vendor_xxx_` as prefix for all static functions
> +of a vendor specific file as it is already clear that the code is vendor
> +specific. Aside of that vendor names should only be used when it is really
> +vendor specific functionality.

   Please note that 'xxx_vendor\_' and 'vendor_xxx_` prefixes are not
   helpful for static functions in vendor-specific files. After all,
   it is already clear that the code is vendor specific. In addition,
   vendor names should only be for truly vendor-specific functionality.

> +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
> +(``linux-tip-commits@xxxxxxxxxxxxxxx``) 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.'.
> 
>