linux-kernel - Re: [PATCH v4 00/29] Create a book for Kernel development

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20160920184454.0b5ae2a0@lwn.net>
Date:   Tue, 20 Sep 2016 18:44:54 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        LKML <linux-kernel@...r.kernel.org>, Greg KH <greg@...ah.com>
Subject: Re: [PATCH v4 00/29] Create a book for Kernel development

On Mon, 19 Sep 2016 08:07:34 -0300
Mauro Carvalho Chehab <mchehab@...pensource.com> wrote:

> That's the 4th version of this series. It also contains a second patch series
> with more ReST conversions and documentation improvements.
> This patchset merges the content of a second patch series:
> 
> 	[PATCH 00/17] Improve documentation for the development-process
> 

OK, I'm applying these through 28; I'm going to hold off on #29.  Thanks
for separating that part out so nicely.

> I opted to keep the patch changing the  kernel-docs.txt changes
> (patch 21/29). The patch is already written and another patch
> (patch 22/29)  depends on it, because there are references to
> this file at Documentation/HOWTO.
>
> It shouldn't be hard  to get rid of it, but I'm not sure if worths
> the effort. As I commented, people might find useful to update
> it to point to more modern documents. If people won't do it,
> it can still be removed from the Kernel a the next Kernel version.

I'll take them for now, since there seems to be interest in doing something
with this document.  I kept the applying-patches one as well.  But I do
think that we need to start being a bit more willing to get rid of musty
old docs.  We don't carry unused code because "it might be useful to
somebody"; I think we should take the same approach to docs.  Out-of-date
or irrelevant docs are a maintenance burden, and they impose a heavy burden
on the people the docs are most meant to help...

A few notes:

#1 didn't apply, I had to do it by hand.  I suspect my late application of
Marcus's work got in the way there.

#2 had this:

> Content-Type: text/plain; charset=true

...which threw git am for a loop; I had to fix it manually.  What gives
there?

#4 didn't apply and had to be done by hand.

#10 (CodingStyle) has a lot of ".. code-block:: c" constructs.  Why are
those needed?  We're still using C by default for literal blocks, right?

#15 (SecurityBugs) leaves the section numbers in place; did you intend
that?

#21 (kernel-docs.txt) had the charset=true weirdness

#28 actually, I balked at applying this one, since it assumes that
    the great renaming is taking place, and that hasn't happened yet.

So actually I only went through #27, but that took a long time - seemingly
longer than it takes you to create them! :)

A few of the patches still have the bare "::" lines in them; I think I'll
just add a patch to fix those up real quick.

Thanks,

jon