linux-kernel - Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next

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: <20160629102426.08570878@lwn.net>
Date:	Wed, 29 Jun 2016 10:24:26 -0600
From:	Jonathan Corbet <corbet@....net>
To:	Markus Heiser <markus.heiser@...marit.de>
Cc:	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Dave Airlie <airlied@...il.com>,
	Jani Nikula <jani.nikula@...el.com>,
	Grant Likely <grant.likely@...retlab.ca>,
	Keith Packard <keithp@...thp.com>,
	LKML Mailing List <linux-kernel@...r.kernel.org>,
	"linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
	Hans Verkuil <hverkuil@...all.nl>,
	Randy Dunlap <rdunlap@...radead.org>
Subject: Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's
 docs-next

Hi, Markus,

I was glad to hear from you, but I have to agree with Jani: this is not
how things are done.  Consider this one line:

> 706 files changed, 123369 insertions(+), 752 deletions(-)

Something like that will be a huge red flag to any kernel maintainer!

In the kernel community, we have spent the last 25 years figuring out a
development model that is based on gradual, incremental changes, each of
which can be reviewed on its own merits.  It does *not* encompass
wholesale replacements of existing code — even in situations where that
code was not just merged after a year of discussions, negotiations, and
false starts.

I simply cannot accept this pull request.

Markus, we all very much want your help in this work.  You have expertise
and energy that could really push the documentation effort forward.  But
it needs to be done the way kernel developers do it: cooperatively,
incrementally, and always mindful of the entire community's needs.

I would love it if you would take the flat-table and man-page work,
separate them out, and make them work with the *existing* Sphinx-based
scheme.  If you can do it soon, we can maybe get it into 4.8.  Can you
focus on that for now, please?

As for the rest, what we have now is certainly far from perfect; we're
figuring a lot of this out as we go.  Incremental improvements are
welcome, and each will be evaluated independently.  Please help us to
make the kernel's documentation better that way.

Thanks,

jon