Message-Id: <20220330005012.3899821-1-dja@axtens.net>
Date:   Wed, 30 Mar 2022 11:50:12 +1100
From:   Daniel Axtens <dja@...ens.net>
To:     konstantin@...uxfoundation.org
Cc:     corbet@....net, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, patches@...ts.linux.dev,
        Daniel Axtens <dja@...ens.net>,
        Emily Strickland <linux@...ly.st>
Subject: Re: [PATCH] Documentation: kernel-hacking: minor edits for style

Hi Konstantin,

I agree the document could do with some love. I've got some suggestions to
make the tips a bit more useful, regardless of where we land on Rusty's
'iconic' prose.

---

Subject: [PATCH] hacking.rst: update for modern git-based workflows

The tips are fun, but they predate git. With git we do things differently.
Document something closer to what we do.

Reported-by: Emily Strickland <linux@...ly.st>
Signed-off-by: Daniel Axtens <dja@...ens.net>
---
 Documentation/kernel-hacking/hacking.rst | 59 +++++++++++++++++++-----
 1 file changed, 47 insertions(+), 12 deletions(-)

diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index 55bd37a2efb0..a4f7d717de3c 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -723,15 +723,9 @@ Putting Your Stuff in the Kernel
 In order to get your stuff into shape for official inclusion, or even to
 make a neat patch, there's administrative work to be done:
 
--  Figure out whose pond you've been pissing in. Look at the top of the
-   source files, inside the ``MAINTAINERS`` file, and last of all in the
-   ``CREDITS`` file. You should coordinate with this person to make sure
-   you're not duplicating effort, or trying something that's already
-   been rejected.
-
-   Make sure you put your name and EMail address at the top of any files
-   you create or mangle significantly. This is the first place people
-   will look when they find a bug, or when **they** want to make a change.
+-  Read ``Documentation/process/submitting-patches.rst``. Kernel developers are
+   a picky bunch, and that document attempts to list what we do and do not like
+   in our patches.
 
 -  Usually you want a configuration option for your kernel hack. Edit
    ``Kconfig`` in the appropriate directory. The Config language is
@@ -748,15 +742,56 @@ make a neat patch, there's administrative work to be done:
    can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
    is documented in ``Documentation/kbuild/makefiles.rst``.
 
+- Finally, re-read
+  ``Documentation/process/submitting-patches.rst``. Seriously. Do it.
+
+
+Historical Notes
+----------------
+
+These were previous tips. They've largely become outdated by the adoption of git
+in the kernel, and creation better tooling generally, but in homage to Rusty's
+iconic prose, you can still read them here in annotated form.
+
+-  Figure out whose pond you've been pissing in. Look at the top of the
+   source files, inside the ``MAINTAINERS`` file, and last of all in the
+   ``CREDITS`` file. You should coordinate with this person to make sure
+   you're not duplicating effort, or trying something that's already
+   been rejected.
+
+.. note::
+
+    Use ``scripts/get_maintainer.pl`` these days, don't try to read
+    ``MAINTAINERS`` manually. Coordinating big changes is still a good idea: use
+    a mailing list suggested by the script for this purpose. The lists should
+    have searchable archives as well.
+
+   Make sure you put your name and EMail address at the top of any files
+   you create or mangle significantly. This is the first place people
+   will look when they find a bug, or when **they** want to make a change.
+
+.. note::
+
+    With git, putting your name at the top of the file is now less useful.
+    People will do ``git log`` and ``git blame`` to if they need to find a
+    specific individual. Still put your name on new files, but only add it to
+    existing files if you've done really significant changes.
+
 -  Put yourself in ``CREDITS`` if you've done something noteworthy,
    usually beyond a single file (your name should be at the top of the
    source files anyway). ``MAINTAINERS`` means you want to be consulted
    when changes are made to a subsystem, and hear about bugs; it implies
    a more-than-passing commitment to some part of the code.
 
--  Finally, don't forget to read
-   ``Documentation/process/submitting-patches.rst`` and possibly
-   ``Documentation/process/submitting-drivers.rst``.
+.. note::
+
+    ``CREDITS`` is now more of a honour roll of former maintainers. Your
+    contribution will be immortalised in the git history, you don't need to add
+    yourself to ``CREDITS`` as well.
+
+- As well as reading ``Documentation/process/submitting-patches.rst``,
+  ``Documentation/process/submitting-drivers.rst`` is possibly useful.
+
 
 Kernel Cantrips
 ===============
-- 
2.32.0

Powered by blists - more mailing lists