Re: [PATCH] submitting-patches.rst: streamline for git usage

Jonathan Corbet
2020-08-31T22:26:43Z

On Thu, 27 Aug 2020 13:42:37 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> This document is a bit intimidating to new patch submitters, and this
> change streamlines it a bit. We presume git usage, because it's much
> easier to use and most devs coming at the kernel are likely to be
> familiar with it.
>
> I've also added a couple of links to third-party resources which I have
> built, namely the following:
>
> https://git-send-email.io
> https://useplaintext.email
>
> I additionally removed information designed for subsystem and branch
> maintainers, as it's unlikely to be useful for a first-time contributor.
> Perhaps this documentation should be moved elsewhere?
> ---
> Documentation/process/submitting-patches.rst | 169 +++++--------------
> 1 file changed, 40 insertions(+), 129 deletions(-)

So I am absolutely sympathetic with the idea of simplifying this
document... you should have seen it before the last pass I made. I think
we want a number of these changes, but I do have some requests.

- Assuming use of Git makes sense to me; I don't think we need to be
suggesting (or documenting) creating patches by hand at this point. So
that's all good.

- We have a document on configuring email clients for use in kernel
development; we should be pointing there rather than to outside sites.
There might well be a place for a pointer to useplaintext.email in
Documentation/process/email-clients.rst, but that's a separate patch.

- In general we've been removing manual section numbers for the reasons
amply demonstrated in this patch; maintaining them is a pain and, once
you've gone through and changed them all, referring to sections by
number doesn't work as well anymore. My own feeling is that they should
come out.

- Please don't just remove maintainer information like that. If it needs
a new home, fine, find a new home for it. We have a nascent maintainers
manual that could certainly use some help.

- Please split your work into multiple, single-purpose patches so that
they can be reviewed more easily.

Thanks,

jon