* [PATCH] Documentation: kernel-hacking: minor edits for style
@ 2022-03-29 19:51 Konstantin Ryabitsev
2022-03-30 0:50 ` Daniel Axtens
2022-04-05 15:54 ` Jonathan Corbet
0 siblings, 2 replies; 3+ messages in thread
From: Konstantin Ryabitsev @ 2022-03-29 19:51 UTC (permalink / raw)
To: corbet; +Cc: linux-doc, linux-kernel, patches
Rusty's kernel-hacking guides provide important information, however
they are written in a narrative style that some readers may interpret as
off-putting. Since the goal is to make kernel documentation accessible
to as many new developers as possible, it's best to avoid the turns of
phrase that require a specific cultural context to properly understand.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
Documentation/kernel-hacking/hacking.rst | 36 ++++++++++++------------
Documentation/kernel-hacking/locking.rst | 5 +---
2 files changed, 19 insertions(+), 22 deletions(-)
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index 55bd37a2efb0..ebd9d90882ea 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -112,8 +112,7 @@ time, although different tasklets can run simultaneously.
.. warning::
The name 'tasklet' is misleading: they have nothing to do with
- 'tasks', and probably more to do with some bad vodka Alexey
- Kuznetsov had at the time.
+ 'tasks'.
You can tell you are in a softirq (or tasklet) using the
:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
@@ -290,8 +289,8 @@ userspace.
Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
return the amount of uncopied data (ie. 0 still means success).
-[Yes, this moronic interface makes me cringe. The flamewar comes up
-every year or so. --RR.]
+[Yes, this objectionable interface makes me cringe. The flamewar comes
+up every year or so. --RR.]
The functions may sleep implicitly. This should never be called outside
user context (it makes no sense), with interrupts disabled, or a
@@ -645,8 +644,9 @@ names in development kernels; this is not done just to keep everyone on
their toes: it reflects a fundamental change (eg. can no longer be
called with interrupts on, or does extra checks, or doesn't do checks
which were caught before). Usually this is accompanied by a fairly
-complete note to the linux-kernel mailing list; search the archive.
-Simply doing a global replace on the file usually makes things **worse**.
+complete note to the appropriate kernel development mailing list; search
+the archives. Simply doing a global replace on the file usually makes
+things **worse**.
Initializing structure members
------------------------------
@@ -723,14 +723,14 @@ 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.
+- Figure out who are the owners of the code you've been modifying. Look
+ at the top of the source files, inside the ``MAINTAINERS`` file, and
+ last of all in the ``CREDITS`` file. You should coordinate with these
+ people 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
+ Make sure you put your name and email address at the top of any files
+ you create or modify significantly. This is the first place people
will look when they find a bug, or when **they** want to make a change.
- Usually you want a configuration option for your kernel hack. Edit
@@ -748,11 +748,11 @@ 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``.
-- 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.
+- Put yourself in ``CREDITS`` if you consider what you've done
+ 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
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index 4cbd50edf277..6805ae6e86e6 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -941,8 +941,7 @@ lock.
A classic problem here is when you provide callbacks or hooks: if you
call these with the lock held, you risk simple deadlock, or a deadly
-embrace (who knows what the callback will do?). Remember, the other
-programmers are out to get you, so don't do this.
+embrace (who knows what the callback will do?).
Overzealous Prevention Of Deadlocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -952,8 +951,6 @@ grabs a read lock, searches a list, fails to find what it wants, drops
the read lock, grabs a write lock and inserts the object has a race
condition.
-If you don't see why, please stay away from my code.
-
Racing Timers: A Kernel Pastime
-------------------------------
--
2.35.1
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: kernel-hacking: minor edits for style
2022-03-29 19:51 [PATCH] Documentation: kernel-hacking: minor edits for style Konstantin Ryabitsev
@ 2022-03-30 0:50 ` Daniel Axtens
2022-04-05 15:54 ` Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Daniel Axtens @ 2022-03-30 0:50 UTC (permalink / raw)
To: konstantin
Cc: corbet, linux-doc, linux-kernel, patches, Daniel Axtens,
Emily Strickland
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@emily.st>
Signed-off-by: Daniel Axtens <dja@axtens.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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: kernel-hacking: minor edits for style
2022-03-29 19:51 [PATCH] Documentation: kernel-hacking: minor edits for style Konstantin Ryabitsev
2022-03-30 0:50 ` Daniel Axtens
@ 2022-04-05 15:54 ` Jonathan Corbet
1 sibling, 0 replies; 3+ messages in thread
From: Jonathan Corbet @ 2022-04-05 15:54 UTC (permalink / raw)
To: Konstantin Ryabitsev; +Cc: linux-doc, linux-kernel, patches
Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
> Rusty's kernel-hacking guides provide important information, however
> they are written in a narrative style that some readers may interpret as
> off-putting. Since the goal is to make kernel documentation accessible
> to as many new developers as possible, it's best to avoid the turns of
> phrase that require a specific cultural context to properly understand.
>
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
> Documentation/kernel-hacking/hacking.rst | 36 ++++++++++++------------
> Documentation/kernel-hacking/locking.rst | 5 +---
> 2 files changed, 19 insertions(+), 22 deletions(-)
*Sigh*...it's kind of sad to see the character of Rusty's writing being
chipped away over time; this isn't the first sanitization patch applied
to this file. It certainly needs a lot more work than this to match
current practice. Oh well, I've applied it, thanks.
jon
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2022-04-05 21:09 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-03-29 19:51 [PATCH] Documentation: kernel-hacking: minor edits for style Konstantin Ryabitsev
2022-03-30 0:50 ` Daniel Axtens
2022-04-05 15:54 ` Jonathan Corbet
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).