As a follow-up to the UMN incident[1], the TAB took the responsibility
to document Researcher Guidelines so there would be a common place to
point for describing our expectations as a developer community.

Document best practices researchers should follow to participate
successfully with the Linux developer community.

[1] https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/

Co-developed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Co-developed-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Co-developed-by: Stefano Zacchiroli <zack@upsilon.cc>
Signed-off-by: Stefano Zacchiroli <zack@upsilon.cc>
Co-developed-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Steven Rostedt <rostedt@goodmis.org>
Acked-by: Steve Rostedt <rostedt@goodmis.org>
Acked-by: Laura Abbott <labbott@kernel.org>
Reviewed-by: Julia Lawall <julia.lawall@inria.fr>
Reviewed-by: Wenwen Wang <wenwen@cs.uga.edu>
Signed-off-by: Kees Cook <keescook@chromium.org>
---
v1: https://lore.kernel.org/lkml/20220224001403.1307377-1-keescook@chromium.org
v2: https://lore.kernel.org/lkml/20220225201424.3430857-1-keescook@chromium.org
v3:
 - move to /process
---
 Documentation/process/index.rst               |   1 +
 .../process/researcher-guidelines.rst         | 143 ++++++++++++++++++
 2 files changed, 144 insertions(+)
 create mode 100644 Documentation/process/researcher-guidelines.rst

diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 9f1b88492bb3..f7664a1db8b8 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -48,6 +48,7 @@ Other guides to the community that are of interest to most developers are:
    deprecated
    embargoed-hardware-issues
    maintainers
+   researcher-guidelines
 
 These are some overall technical guides that have been put here for now for
 lack of a better place.
diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst
new file mode 100644
index 000000000000..afc944e0e898
--- /dev/null
+++ b/Documentation/process/researcher-guidelines.rst
@@ -0,0 +1,143 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _researcher_guidelines:
+
+Researcher Guidelines
++++++++++++++++++++++
+
+The Linux kernel community welcomes transparent research on the Linux
+kernel, the activities involved in producing it, and any other byproducts
+of its development. Linux benefits greatly from this kind of research, and
+most aspects of Linux are driven by research in one form or another.
+
+The community greatly appreciates if researchers can share preliminary
+findings before making their results public, especially if such research
+involves security. Getting involved early helps both improve the quality
+of research and ability for Linux to improve from it. In any case,
+sharing open access copies of the published research with the community
+is recommended.
+
+This document seeks to clarify what the Linux kernel community considers
+acceptable and non-acceptable practices when conducting such research. At
+the very least, such research and related activities should follow
+standard research ethics rules. For more background on research ethics
+generally, ethics in technology, and research of developer communities
+in particular, see:
+
+* `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
+* `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_
+* `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_
+
+The Linux kernel community expects that everyone interacting with the
+project is participating in good faith to make Linux better. Research on
+any publicly-available artifact (including, but not limited to source
+code) produced by the Linux kernel community is welcome, though research
+on developers must be distinctly opt-in.
+
+Passive research that is based entirely on publicly available sources,
+including posts to public mailing lists and commits to public
+repositories, is clearly permissible. Though, as with any research,
+standard ethics must still be followed.
+
+Active research on developer behavior, however, must be done with the
+explicit agreement of, and full disclosure to, the individual developers
+involved. Developers cannot be interacted with/experimented on without
+consent; this, too, is standard research ethics.
+
+To help clarify: sending patches to developers *is* interacting
+with them, but they have already consented to receiving *good faith
+contributions*. Sending intentionally flawed/vulnerable patches or
+contributing misleading information to discussions is not consented
+to. Such communication can be damaging to the developer (e.g. draining
+time, effort, and morale) and damaging to the project by eroding
+the entire developer community's trust in the contributor (and the
+contributor's organization as a whole), undermining efforts to provide
+constructive feedback to contributors, and putting end users at risk of
+software flaws.
+
+Participation in the development of Linux itself by researchers, as
+with anyone, is welcomed and encouraged. Research into Linux code is
+a common practice, especially when it comes to developing or running
+analysis tools that produce actionable results.
+
+When engaging with the developer community, sending a patch has
+traditionally been the best way to make an impact. Linux already has
+plenty of known bugs -- what's much more helpful is having vetted fixes.
+Before contributing, carefully read the appropriate documentation:
+
+* Documentation/process/development-process.rst
+* Documentation/process/submitting-patches.rst
+* Documentation/admin-guide/reporting-issues.rst
+* Documentation/admin-guide/security-bugs.rst
+
+Then send a patch (including a commit log with all the details listed
+below) and follow up on any feedback from other developers.
+
+When sending patches produced from research, the commit logs should
+contain at least the following details, so that developers have
+appropriate context for understanding the contribution. Answer:
+
+* What is the specific problem that has been found?
+* How could the problem be reached on a running system?
+* What effect would encountering the problem have on the system?
+* How was the problem found? Specifically include details about any
+  testing, static or dynamic analysis programs, and any other tools or
+  methods used to perform the work.
+* Which version of Linux was the problem found on? Using the most recent
+  release or a recent linux-next branch is strongly preferred (see
+  Documentation/process/howto.rst).
+* What was changed to fix the problem, and why it is believed to be correct?
+* How was the change build tested and run-time tested?
+* What prior commit does this change fix? This should go in a "Fixes:"
+  tag as the documentation describes.
+* Who else has reviewed this patch? This should go in appropriate
+  "Reviewed-by:" tags; see below.
+
+For example::
+
+  From: Author <author@email>
+  Subject: [PATCH] drivers/foo_bar: Add missing kfree()
+
+  The error path in foo_bar driver does not correctly free the allocated
+  struct foo_bar_info. This can happen if the attached foo_bar device
+  rejects the initialization packets sent during foo_bar_probe(). This
+  would result in a 64 byte slab memory leak once per device attach,
+  wasting memory resources over time.
+
+  This flaw was found using an experimental static analysis tool we are
+  developing, LeakMagic[1], which reported the following warning when
+  analyzing the v5.15 kernel release:
+
+   path/to/foo_bar.c:187: missing kfree() call?
+
+  Add the missing kfree() to the error path. No other references to
+  this memory exist outside the probe function, so this is the only
+  place it can be freed.
+
+  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
+  11.2 show no new warnings, and LeakMagic no longer warns about this
+  code path. As we don't have a FooBar device to test with, no runtime
+  testing was able to be performed.
+
+  [1] https://url/to/leakmagic/details
+
+  Reported-by: Researcher <researcher@email>
+  Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
+  Signed-off-by: Author <author@email>
+  Reviewed-by: Reviewer <reviewer@email>
+
+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.
+
+If no one can be found to internally review patches and you need
+help finding such a person, or if you have any other questions
+related to this document and the developer community's expectations,
+please reach out to the private Technical Advisory Board mailing list:
+<tech-board@lists.linux-foundation.org>.
-- 
2.32.0

On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:
> +For example::
> +
> +  From: Author <author@email>
> +  Subject: [PATCH] drivers/foo_bar: Add missing kfree()
> +
> +  The error path in foo_bar driver does not correctly free the allocated
> +  struct foo_bar_info. This can happen if the attached foo_bar device
> +  rejects the initialization packets sent during foo_bar_probe(). This
> +  would result in a 64 byte slab memory leak once per device attach,
> +  wasting memory resources over time.
> +
> +  This flaw was found using an experimental static analysis tool we are
> +  developing, LeakMagic[1], which reported the following warning when
> +  analyzing the v5.15 kernel release:
> +
> +   path/to/foo_bar.c:187: missing kfree() call?
> +
> +  Add the missing kfree() to the error path. No other references to
> +  this memory exist outside the probe function, so this is the only
> +  place it can be freed.
> +
> +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
> +  11.2 show no new warnings, and LeakMagic no longer warns about this
> +  code path. As we don't have a FooBar device to test with, no runtime
> +  testing was able to be performed.

People have started sending commit messages in this exact template and
normally I would ask them resend with the meta commentary from this
paragraph below the --- cut off line.

Do we really want this "Compile tested only" stuff in the permanent git
log?

regards,
dan carpenter

> +
> +  [1] https://url/to/leakmagic/details
> +
> +  Reported-by: Researcher <researcher@email>
> +  Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
> +  Signed-off-by: Author <author@email>
> +  Reviewed-by: Reviewer <reviewer@email>
> +

On Thu, May 28, 2026 at 01:34:34PM +0300, Dan Carpenter wrote:
> On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:

...

> > +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
> > +  11.2 show no new warnings, and LeakMagic no longer warns about this
> > +  code path. As we don't have a FooBar device to test with, no runtime
> > +  testing was able to be performed.
> 
> People have started sending commit messages in this exact template and
> normally I would ask them resend with the meta commentary from this
> paragraph below the --- cut off line.
> 
> Do we really want this "Compile tested only" stuff in the permanent git
> log?

+1 here, can we rather avoid flooding commit messages with the meta, that
anyways is available in lore.kernel.org archives?

-- 
With Best Regards,
Andy Shevchenko

On Mon, Jun 15, 2026 at 03:48:22PM +0200, Andy Shevchenko wrote:
> On Thu, May 28, 2026 at 01:34:34PM +0300, Dan Carpenter wrote:
> > On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:
> 
> ...
> 
> > > +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
> > > +  11.2 show no new warnings, and LeakMagic no longer warns about this
> > > +  code path. As we don't have a FooBar device to test with, no runtime
> > > +  testing was able to be performed.
> > 
> > People have started sending commit messages in this exact template and
> > normally I would ask them resend with the meta commentary from this
> > paragraph below the --- cut off line.
> > 
> > Do we really want this "Compile tested only" stuff in the permanent git
> > log?
> 
> +1 here, can we rather avoid flooding commit messages with the meta, that
> anyways is available in lore.kernel.org archives?

Hm, I have gotten a lot of push-back from maintainers (reasonablly)
wanting to know the specific level of testing patches get. In the case
of lacking hardware, this seems like useful information still.

-- 
Kees Cook

On Mon, Jun 15, 2026 at 03:48:02PM -0700, Kees Cook wrote:
> On Mon, Jun 15, 2026 at 03:48:22PM +0200, Andy Shevchenko wrote:
> > On Thu, May 28, 2026 at 01:34:34PM +0300, Dan Carpenter wrote:
> > > On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:

...

> > > > +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
> > > > +  11.2 show no new warnings, and LeakMagic no longer warns about this
> > > > +  code path. As we don't have a FooBar device to test with, no runtime
> > > > +  testing was able to be performed.
> > > 
> > > People have started sending commit messages in this exact template and
> > > normally I would ask them resend with the meta commentary from this
> > > paragraph below the --- cut off line.
> > > 
> > > Do we really want this "Compile tested only" stuff in the permanent git
> > > log?
> > 
> > +1 here, can we rather avoid flooding commit messages with the meta, that
> > anyways is available in lore.kernel.org archives?
> 
> Hm, I have gotten a lot of push-back from maintainers (reasonablly)
> wanting to know the specific level of testing patches get. In the case
> of lacking hardware, this seems like useful information still.

I am *not* against providing this information (actually I on the same page),
I'm just against putting it into the commit message! We have a comment block
put it there, please.

-- 
With Best Regards,
Andy Shevchenko

Andy Shevchenko <andriy.shevchenko@intel.com> writes:

> On Thu, May 28, 2026 at 01:34:34PM +0300, Dan Carpenter wrote:
>> On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:
>
> ...
>
>> > +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
>> > +  11.2 show no new warnings, and LeakMagic no longer warns about this
>> > +  code path. As we don't have a FooBar device to test with, no runtime
>> > +  testing was able to be performed.
>> 
>> People have started sending commit messages in this exact template and
>> normally I would ask them resend with the meta commentary from this
>> paragraph below the --- cut off line.
>> 
>> Do we really want this "Compile tested only" stuff in the permanent git
>> log?
>
> +1 here, can we rather avoid flooding commit messages with the meta, that
> anyways is available in lore.kernel.org archives?

Perhaps somebody should send a patch correcting the wording to how they
think it should be...?

Thanks,

jon

On Mon, Jun 15, 2026 at 08:58:34AM -0600, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@intel.com> writes:
> > On Thu, May 28, 2026 at 01:34:34PM +0300, Dan Carpenter wrote:
> >> On Fri, Mar 04, 2022 at 10:14:18AM -0800, Kees Cook wrote:

...

> >> > +  x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
> >> > +  11.2 show no new warnings, and LeakMagic no longer warns about this
> >> > +  code path. As we don't have a FooBar device to test with, no runtime
> >> > +  testing was able to be performed.
> >> 
> >> People have started sending commit messages in this exact template and
> >> normally I would ask them resend with the meta commentary from this
> >> paragraph below the --- cut off line.
> >> 
> >> Do we really want this "Compile tested only" stuff in the permanent git
> >> log?
> >
> > +1 here, can we rather avoid flooding commit messages with the meta, that
> > anyways is available in lore.kernel.org archives?
> 
> Perhaps somebody should send a patch correcting the wording to how they
> think it should be...?

Perhaps Dan as native speaker can do it better or others who were involved in
this?

-- 
With Best Regards,
Andy Shevchenko

Kees Cook <keescook@chromium.org> writes:

> As a follow-up to the UMN incident[1], the TAB took the responsibility
> to document Researcher Guidelines so there would be a common place to
> point for describing our expectations as a developer community.
>
> Document best practices researchers should follow to participate
> successfully with the Linux developer community.
>
> [1] https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/
>
> Co-developed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Co-developed-by: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> Co-developed-by: Stefano Zacchiroli <zack@upsilon.cc>
> Signed-off-by: Stefano Zacchiroli <zack@upsilon.cc>
> Co-developed-by: Steven Rostedt <rostedt@goodmis.org>
> Signed-off-by: Steven Rostedt <rostedt@goodmis.org>
> Acked-by: Steve Rostedt <rostedt@goodmis.org>
> Acked-by: Laura Abbott <labbott@kernel.org>
> Reviewed-by: Julia Lawall <julia.lawall@inria.fr>
> Reviewed-by: Wenwen Wang <wenwen@cs.uga.edu>
> Signed-off-by: Kees Cook <keescook@chromium.org>
> ---
> v1: https://lore.kernel.org/lkml/20220224001403.1307377-1-keescook@chromium.org
> v2: https://lore.kernel.org/lkml/20220225201424.3430857-1-keescook@chromium.org
> v3:
>  - move to /process

I've applied this, thanks.

jon