Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <390abb1b-6d85-e6fe-ba0e-c47f7c80fca2@leemhuis.info>
Date:   Thu, 24 Feb 2022 11:10:53 +0100
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.5.0
Content-Language: en-BS
To:     Alexander Dahl <ada@thorsis.com>
References: <20220224001403.1307377-1-keescook@chromium.org>
 <974cf8f2-06f3-99a5-9a77-6d7b7cc8271a@leemhuis.info>
 <YhdWa41bXssNVrE3@ada-deb-carambola.ifak-system.com>
From:   Thorsten Leemhuis <linux@leemhuis.info>
Cc:     Kees Cook <keescook@chromium.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Stefano Zacchiroli <zack@upsilon.cc>,
        Steven Rostedt <rostedt@goodmis.org>,
        Laura Abbott <labbott@kernel.org>,
        Julia Lawall <julia.lawall@inria.fr>,
        Wenwen Wang <wenwen@cs.uga.edu>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org, linux-hardening@vger.kernel.org
Subject: Re: [PATCH] Documentation/process: Add Researcher Guidelines
In-Reply-To: <YhdWa41bXssNVrE3@ada-deb-carambola.ifak-system.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 24.02.22 10:56, Alexander Dahl wrote:
> Hello Thorsten,
> 
> Am Thu, Feb 24, 2022 at 09:19:24AM +0100 schrieb Thorsten Leemhuis:
>> On 24.02.22 01:14, Kees Cook wrote:
>>> +If you are a first time contributor it is recommended that the patch
>>> +itself be vetted by others privately before being posted to public lists.
>>> +(This is required if you have been explicitly told your patches need
>>> +more careful internal review.) These people are expected to have their
>>> +"Reviewed-by" tag included in the resulting patch. Finding another
>>> +developer familiar with Linux contribution, especially within your own
>>> +organization, and having them help with reviews before sending them to
>>> +the public mailing lists tends to significantly improve the quality of the
>>> +resulting patches, and there by reduces the burden on other developers.
>>
>> I like the section, but I wonder why it's needed here. Is there anything
>> specific to patches produced from research in it there I missed when
>> reading it? If not: Wouldn't it be better to include that section as a
>> TLDR in Documentation/process/submitting-patches.rst and point there
>> instead? We already have at least two places describing how to submit
>> patches, creating yet another one (even if it's just in such a brief
>> version) somehow feels slightly wrong to me.
>>
>> OTOH I fully understand that having things in one place has it's
>> benefits. If that's wanted, why not put that text as TLDR in
>> submitting-patches.rst and maintain a copy here? Sure, keeping things in
>> sync has downsides, but I'd say it's the lesser evil. A copy could also
>> be avoided by briefly mentioning some of the important bits found in
>> another document; that's the approach I took in my patches regarding
>> regressions. To quote:
> 
> Without further opinion on the topic or content itself: 
> If there's need to have "copied" parts of the documentation available
> in different places, why not put that to a separate file and include
> it in all places which need it?  [...]

Yeah, I already wondered if that's possible, but never actually
investigated, as I assume the "separate file" aspect you mentioned is a
show-stopper: it makes reading hard for everyone that looks at the rst
files directly -- and that's something we afaics want to support.

Ciao, Thorsten