Skip to content

Commit f09f6f9

Browse files
keesJonathan Corbet
kees
authored and
Jonathan Corbet
committed
Documentation/process: Add Researcher Guidelines
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> 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> Link: https://lore.kernel.org/r/20220304181418.1692016-1-keescook@chromium.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
1 parent 0d6356d commit f09f6f9

2 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎Documentation/process/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ Other guides to the community that are of interest to most developers are:
4949
deprecated
5050
embargoed-hardware-issues
5151
maintainers
52+
researcher-guidelines
5253

5354
These are some overall technical guides that have been put here for now for
5455
lack of a better place.

‎Documentation/process/researcher-guidelines.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
.. _researcher_guidelines:
4+
5+
Researcher Guidelines
6+
+++++++++++++++++++++
7+
8+
The Linux kernel community welcomes transparent research on the Linux
9+
kernel, the activities involved in producing it, and any other byproducts
10+
of its development. Linux benefits greatly from this kind of research, and
11+
most aspects of Linux are driven by research in one form or another.
12+
13+
The community greatly appreciates if researchers can share preliminary
14+
findings before making their results public, especially if such research
15+
involves security. Getting involved early helps both improve the quality
16+
of research and ability for Linux to improve from it. In any case,
17+
sharing open access copies of the published research with the community
18+
is recommended.
19+
20+
This document seeks to clarify what the Linux kernel community considers
21+
acceptable and non-acceptable practices when conducting such research. At
22+
the very least, such research and related activities should follow
23+
standard research ethics rules. For more background on research ethics
24+
generally, ethics in technology, and research of developer communities
25+
in particular, see:
26+
27+
* `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
28+
* `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_
29+
* `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_
30+
31+
The Linux kernel community expects that everyone interacting with the
32+
project is participating in good faith to make Linux better. Research on
33+
any publicly-available artifact (including, but not limited to source
34+
code) produced by the Linux kernel community is welcome, though research
35+
on developers must be distinctly opt-in.
36+
37+
Passive research that is based entirely on publicly available sources,
38+
including posts to public mailing lists and commits to public
39+
repositories, is clearly permissible. Though, as with any research,
40+
standard ethics must still be followed.
41+
42+
Active research on developer behavior, however, must be done with the
43+
explicit agreement of, and full disclosure to, the individual developers
44+
involved. Developers cannot be interacted with/experimented on without
45+
consent; this, too, is standard research ethics.
46+
47+
To help clarify: sending patches to developers *is* interacting
48+
with them, but they have already consented to receiving *good faith
49+
contributions*. Sending intentionally flawed/vulnerable patches or
50+
contributing misleading information to discussions is not consented
51+
to. Such communication can be damaging to the developer (e.g. draining
52+
time, effort, and morale) and damaging to the project by eroding
53+
the entire developer community's trust in the contributor (and the
54+
contributor's organization as a whole), undermining efforts to provide
55+
constructive feedback to contributors, and putting end users at risk of
56+
software flaws.
57+
58+
Participation in the development of Linux itself by researchers, as
59+
with anyone, is welcomed and encouraged. Research into Linux code is
60+
a common practice, especially when it comes to developing or running
61+
analysis tools that produce actionable results.
62+
63+
When engaging with the developer community, sending a patch has
64+
traditionally been the best way to make an impact. Linux already has
65+
plenty of known bugs -- what's much more helpful is having vetted fixes.
66+
Before contributing, carefully read the appropriate documentation:
67+
68+
* Documentation/process/development-process.rst
69+
* Documentation/process/submitting-patches.rst
70+
* Documentation/admin-guide/reporting-issues.rst
71+
* Documentation/admin-guide/security-bugs.rst
72+
73+
Then send a patch (including a commit log with all the details listed
74+
below) and follow up on any feedback from other developers.
75+
76+
When sending patches produced from research, the commit logs should
77+
contain at least the following details, so that developers have
78+
appropriate context for understanding the contribution. Answer:
79+
80+
* What is the specific problem that has been found?
81+
* How could the problem be reached on a running system?
82+
* What effect would encountering the problem have on the system?
83+
* How was the problem found? Specifically include details about any
84+
testing, static or dynamic analysis programs, and any other tools or
85+
methods used to perform the work.
86+
* Which version of Linux was the problem found on? Using the most recent
87+
release or a recent linux-next branch is strongly preferred (see
88+
Documentation/process/howto.rst).
89+
* What was changed to fix the problem, and why it is believed to be correct?
90+
* How was the change build tested and run-time tested?
91+
* What prior commit does this change fix? This should go in a "Fixes:"
92+
tag as the documentation describes.
93+
* Who else has reviewed this patch? This should go in appropriate
94+
"Reviewed-by:" tags; see below.
95+
96+
For example::
97+
98+
From: Author <author@email>
99+
Subject: [PATCH] drivers/foo_bar: Add missing kfree()
100+
101+
The error path in foo_bar driver does not correctly free the allocated
102+
struct foo_bar_info. This can happen if the attached foo_bar device
103+
rejects the initialization packets sent during foo_bar_probe(). This
104+
would result in a 64 byte slab memory leak once per device attach,
105+
wasting memory resources over time.
106+
107+
This flaw was found using an experimental static analysis tool we are
108+
developing, LeakMagic[1], which reported the following warning when
109+
analyzing the v5.15 kernel release:
110+
111+
path/to/foo_bar.c:187: missing kfree() call?
112+
113+
Add the missing kfree() to the error path. No other references to
114+
this memory exist outside the probe function, so this is the only
115+
place it can be freed.
116+
117+
x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
118+
11.2 show no new warnings, and LeakMagic no longer warns about this
119+
code path. As we don't have a FooBar device to test with, no runtime
120+
testing was able to be performed.
121+
122+
[1] https://url/to/leakmagic/details
123+
124+
Reported-by: Researcher <researcher@email>
125+
Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
126+
Signed-off-by: Author <author@email>
127+
Reviewed-by: Reviewer <reviewer@email>
128+
129+
If you are a first time contributor it is recommended that the patch
130+
itself be vetted by others privately before being posted to public lists.
131+
(This is required if you have been explicitly told your patches need
132+
more careful internal review.) These people are expected to have their
133+
"Reviewed-by" tag included in the resulting patch. Finding another
134+
developer familiar with Linux contribution, especially within your own
135+
organization, and having them help with reviews before sending them to
136+
the public mailing lists tends to significantly improve the quality of the
137+
resulting patches, and there by reduces the burden on other developers.
138+
139+
If no one can be found to internally review patches and you need
140+
help finding such a person, or if you have any other questions
141+
related to this document and the developer community's expectations,
142+
please reach out to the private Technical Advisory Board mailing list:
143+
<tech-board@lists.linux-foundation.org>.

0 commit comments

Comments
 (0)