1.. SPDX-License-Identifier: GPL-2.0
2
3.. _researcher_guidelines:
4
5Researcher Guidelines
6+++++++++++++++++++++
7
8The Linux kernel community welcomes transparent research on the Linux
9kernel, the activities involved in producing it, and any other byproducts
10of its development. Linux benefits greatly from this kind of research, and
11most aspects of Linux are driven by research in one form or another.
12
13The community greatly appreciates if researchers can share preliminary
14findings before making their results public, especially if such research
15involves security. Getting involved early helps both improve the quality
16of research and ability for Linux to improve from it. In any case,
17sharing open access copies of the published research with the community
18is recommended.
19
20This document seeks to clarify what the Linux kernel community considers
21acceptable and non-acceptable practices when conducting such research. At
22the very least, such research and related activities should follow
23standard research ethics rules. For more background on research ethics
24generally, ethics in technology, and research of developer communities
25in 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
31The Linux kernel community expects that everyone interacting with the
32project is participating in good faith to make Linux better. Research on
33any publicly-available artifact (including, but not limited to source
34code) produced by the Linux kernel community is welcome, though research
35on developers must be distinctly opt-in.
36
37Passive research that is based entirely on publicly available sources,
38including posts to public mailing lists and commits to public
39repositories, is clearly permissible. Though, as with any research,
40standard ethics must still be followed.
41
42Active research on developer behavior, however, must be done with the
43explicit agreement of, and full disclosure to, the individual developers
44involved. Developers cannot be interacted with/experimented on without
45consent; this, too, is standard research ethics.
46
47To help clarify: sending patches to developers *is* interacting
48with them, but they have already consented to receiving *good faith
49contributions*. Sending intentionally flawed/vulnerable patches or
50contributing misleading information to discussions is not consented
51to. Such communication can be damaging to the developer (e.g. draining
52time, effort, and morale) and damaging to the project by eroding
53the entire developer community's trust in the contributor (and the
54contributor's organization as a whole), undermining efforts to provide
55constructive feedback to contributors, and putting end users at risk of
56software flaws.
57
58Participation in the development of Linux itself by researchers, as
59with anyone, is welcomed and encouraged. Research into Linux code is
60a common practice, especially when it comes to developing or running
61analysis tools that produce actionable results.
62
63When engaging with the developer community, sending a patch has
64traditionally been the best way to make an impact. Linux already has
65plenty of known bugs -- what's much more helpful is having vetted fixes.
66Before 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
73Then send a patch (including a commit log with all the details listed
74below) and follow up on any feedback from other developers.
75
76When sending patches produced from research, the commit logs should
77contain at least the following details, so that developers have
78appropriate 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
96For 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
129If you are a first time contributor it is recommended that the patch
130itself be vetted by others privately before being posted to public lists.
131(This is required if you have been explicitly told your patches need
132more careful internal review.) These people are expected to have their
133"Reviewed-by" tag included in the resulting patch. Finding another
134developer familiar with Linux contribution, especially within your own
135organization, and having them help with reviews before sending them to
136the public mailing lists tends to significantly improve the quality of the
137resulting patches, and there by reduces the burden on other developers.
138
139If no one can be found to internally review patches and you need
140help finding such a person, or if you have any other questions
141related to this document and the developer community's expectations,
142please reach out to the private Technical Advisory Board mailing list:
143<tech-board@lists.linux-foundation.org>.
144