1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _researcher_guidelines: 3 .. _researcher_guidelines:
4 4
5 Researcher Guidelines 5 Researcher Guidelines
6 +++++++++++++++++++++ 6 +++++++++++++++++++++
7 7
8 The Linux kernel community welcomes transparen 8 The Linux kernel community welcomes transparent research on the Linux
9 kernel, the activities involved in producing i 9 kernel, the activities involved in producing it, and any other byproducts
10 of its development. Linux benefits greatly fro 10 of its development. Linux benefits greatly from this kind of research, and
11 most aspects of Linux are driven by research i 11 most aspects of Linux are driven by research in one form or another.
12 12
13 The community greatly appreciates if researche 13 The community greatly appreciates if researchers can share preliminary
14 findings before making their results public, e 14 findings before making their results public, especially if such research
15 involves security. Getting involved early help 15 involves security. Getting involved early helps both improve the quality
16 of research and ability for Linux to improve f 16 of research and ability for Linux to improve from it. In any case,
17 sharing open access copies of the published re 17 sharing open access copies of the published research with the community
18 is recommended. 18 is recommended.
19 19
20 This document seeks to clarify what the Linux 20 This document seeks to clarify what the Linux kernel community considers
21 acceptable and non-acceptable practices when c 21 acceptable and non-acceptable practices when conducting such research. At
22 the very least, such research and related acti 22 the very least, such research and related activities should follow
23 standard research ethics rules. For more backg 23 standard research ethics rules. For more background on research ethics
24 generally, ethics in technology, and research 24 generally, ethics in technology, and research of developer communities
25 in particular, see: 25 in particular, see:
26 26
27 * `History of Research Ethics <https://www.unl 27 * `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
28 * `IEEE Ethics <https://www.ieee.org/about/eth 28 * `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_
29 * `Developer and Researcher Views on the Ethic 29 * `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_
30 30
31 The Linux kernel community expects that everyo 31 The Linux kernel community expects that everyone interacting with the
32 project is participating in good faith to make 32 project is participating in good faith to make Linux better. Research on
33 any publicly-available artifact (including, bu 33 any publicly-available artifact (including, but not limited to source
34 code) produced by the Linux kernel community i 34 code) produced by the Linux kernel community is welcome, though research
35 on developers must be distinctly opt-in. 35 on developers must be distinctly opt-in.
36 36
37 Passive research that is based entirely on pub 37 Passive research that is based entirely on publicly available sources,
38 including posts to public mailing lists and co 38 including posts to public mailing lists and commits to public
39 repositories, is clearly permissible. Though, 39 repositories, is clearly permissible. Though, as with any research,
40 standard ethics must still be followed. 40 standard ethics must still be followed.
41 41
42 Active research on developer behavior, however 42 Active research on developer behavior, however, must be done with the
43 explicit agreement of, and full disclosure to, 43 explicit agreement of, and full disclosure to, the individual developers
44 involved. Developers cannot be interacted with 44 involved. Developers cannot be interacted with/experimented on without
45 consent; this, too, is standard research ethic 45 consent; this, too, is standard research ethics.
46 46
47 Surveys 47 Surveys
48 ======= 48 =======
49 49
50 Research often takes the form of surveys sent 50 Research often takes the form of surveys sent to maintainers or
51 contributors. As a general rule, though, the 51 contributors. As a general rule, though, the kernel community derives
52 little value from these surveys. The kernel d 52 little value from these surveys. The kernel development process works
53 because every developer benefits from their pa 53 because every developer benefits from their participation, even working
54 with others who have different goals. Respond 54 with others who have different goals. Responding to a survey, though, is a
55 one-way demand placed on busy developers with 55 one-way demand placed on busy developers with no corresponding benefit to
56 themselves or to the kernel community as a who 56 themselves or to the kernel community as a whole. For this reason, this
57 method of research is discouraged. 57 method of research is discouraged.
58 58
59 Kernel community members already receive far t 59 Kernel community members already receive far too much email and are likely
60 to perceive survey requests as just another de 60 to perceive survey requests as just another demand on their time. Sending
61 such requests deprives the community of valuab 61 such requests deprives the community of valuable contributor time and is
62 unlikely to yield a statistically useful respo 62 unlikely to yield a statistically useful response.
63 63
64 As an alternative, researchers should consider 64 As an alternative, researchers should consider attending developer events,
65 hosting sessions where the research project an 65 hosting sessions where the research project and its benefits to the
66 participants can be explained, and interacting 66 participants can be explained, and interacting directly with the community
67 there. The information received will be far r 67 there. The information received will be far richer than that obtained from
68 an email survey, and the community will gain f 68 an email survey, and the community will gain from the ability to learn from
69 your insights as well. 69 your insights as well.
70 70
71 Patches 71 Patches
72 ======= 72 =======
73 73
74 To help clarify: sending patches to developers 74 To help clarify: sending patches to developers *is* interacting
75 with them, but they have already consented to 75 with them, but they have already consented to receiving *good faith
76 contributions*. Sending intentionally flawed/v 76 contributions*. Sending intentionally flawed/vulnerable patches or
77 contributing misleading information to discuss 77 contributing misleading information to discussions is not consented
78 to. Such communication can be damaging to the 78 to. Such communication can be damaging to the developer (e.g. draining
79 time, effort, and morale) and damaging to the 79 time, effort, and morale) and damaging to the project by eroding
80 the entire developer community's trust in the 80 the entire developer community's trust in the contributor (and the
81 contributor's organization as a whole), underm 81 contributor's organization as a whole), undermining efforts to provide
82 constructive feedback to contributors, and put 82 constructive feedback to contributors, and putting end users at risk of
83 software flaws. 83 software flaws.
84 84
85 Participation in the development of Linux itse 85 Participation in the development of Linux itself by researchers, as
86 with anyone, is welcomed and encouraged. Resea 86 with anyone, is welcomed and encouraged. Research into Linux code is
87 a common practice, especially when it comes to 87 a common practice, especially when it comes to developing or running
88 analysis tools that produce actionable results 88 analysis tools that produce actionable results.
89 89
90 When engaging with the developer community, se 90 When engaging with the developer community, sending a patch has
91 traditionally been the best way to make an imp 91 traditionally been the best way to make an impact. Linux already has
92 plenty of known bugs -- what's much more helpf 92 plenty of known bugs -- what's much more helpful is having vetted fixes.
93 Before contributing, carefully read the approp 93 Before contributing, carefully read the appropriate documentation:
94 94
95 * Documentation/process/development-process.rs 95 * Documentation/process/development-process.rst
96 * Documentation/process/submitting-patches.rst 96 * Documentation/process/submitting-patches.rst
97 * Documentation/admin-guide/reporting-issues.r 97 * Documentation/admin-guide/reporting-issues.rst
98 * Documentation/process/security-bugs.rst 98 * Documentation/process/security-bugs.rst
99 99
100 Then send a patch (including a commit log with 100 Then send a patch (including a commit log with all the details listed
101 below) and follow up on any feedback from othe 101 below) and follow up on any feedback from other developers.
102 102
103 When sending patches produced from research, t 103 When sending patches produced from research, the commit logs should
104 contain at least the following details, so tha 104 contain at least the following details, so that developers have
105 appropriate context for understanding the cont 105 appropriate context for understanding the contribution. Answer:
106 106
107 * What is the specific problem that has been f 107 * What is the specific problem that has been found?
108 * How could the problem be reached on a runnin 108 * How could the problem be reached on a running system?
109 * What effect would encountering the problem h 109 * What effect would encountering the problem have on the system?
110 * How was the problem found? Specifically incl 110 * How was the problem found? Specifically include details about any
111 testing, static or dynamic analysis programs 111 testing, static or dynamic analysis programs, and any other tools or
112 methods used to perform the work. 112 methods used to perform the work.
113 * Which version of Linux was the problem found 113 * Which version of Linux was the problem found on? Using the most recent
114 release or a recent linux-next branch is str 114 release or a recent linux-next branch is strongly preferred (see
115 Documentation/process/howto.rst). 115 Documentation/process/howto.rst).
116 * What was changed to fix the problem, and why 116 * What was changed to fix the problem, and why it is believed to be correct?
117 * How was the change build tested and run-time 117 * How was the change build tested and run-time tested?
118 * What prior commit does this change fix? This 118 * What prior commit does this change fix? This should go in a "Fixes:"
119 tag as the documentation describes. 119 tag as the documentation describes.
120 * Who else has reviewed this patch? This shoul 120 * Who else has reviewed this patch? This should go in appropriate
121 "Reviewed-by:" tags; see below. 121 "Reviewed-by:" tags; see below.
122 122
123 For example:: 123 For example::
124 124
125 From: Author <author@email> 125 From: Author <author@email>
126 Subject: [PATCH] drivers/foo_bar: Add missin 126 Subject: [PATCH] drivers/foo_bar: Add missing kfree()
127 127
128 The error path in foo_bar driver does not co 128 The error path in foo_bar driver does not correctly free the allocated
129 struct foo_bar_info. This can happen if the 129 struct foo_bar_info. This can happen if the attached foo_bar device
130 rejects the initialization packets sent duri 130 rejects the initialization packets sent during foo_bar_probe(). This
131 would result in a 64 byte slab memory leak o 131 would result in a 64 byte slab memory leak once per device attach,
132 wasting memory resources over time. 132 wasting memory resources over time.
133 133
134 This flaw was found using an experimental st 134 This flaw was found using an experimental static analysis tool we are
135 developing, LeakMagic[1], which reported the 135 developing, LeakMagic[1], which reported the following warning when
136 analyzing the v5.15 kernel release: 136 analyzing the v5.15 kernel release:
137 137
138 path/to/foo_bar.c:187: missing kfree() call 138 path/to/foo_bar.c:187: missing kfree() call?
139 139
140 Add the missing kfree() to the error path. N 140 Add the missing kfree() to the error path. No other references to
141 this memory exist outside the probe function 141 this memory exist outside the probe function, so this is the only
142 place it can be freed. 142 place it can be freed.
143 143
144 x86_64 and arm64 defconfig builds with CONFI 144 x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
145 11.2 show no new warnings, and LeakMagic no 145 11.2 show no new warnings, and LeakMagic no longer warns about this
146 code path. As we don't have a FooBar device 146 code path. As we don't have a FooBar device to test with, no runtime
147 testing was able to be performed. 147 testing was able to be performed.
148 148
149 [1] https://url/to/leakmagic/details 149 [1] https://url/to/leakmagic/details
150 150
151 Reported-by: Researcher <researcher@email> 151 Reported-by: Researcher <researcher@email>
152 Fixes: aaaabbbbccccdddd ("Introduce support 152 Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
153 Signed-off-by: Author <author@email> 153 Signed-off-by: Author <author@email>
154 Reviewed-by: Reviewer <reviewer@email> 154 Reviewed-by: Reviewer <reviewer@email>
155 155
156 If you are a first time contributor it is reco 156 If you are a first time contributor it is recommended that the patch
157 itself be vetted by others privately before be 157 itself be vetted by others privately before being posted to public lists.
158 (This is required if you have been explicitly 158 (This is required if you have been explicitly told your patches need
159 more careful internal review.) These people ar 159 more careful internal review.) These people are expected to have their
160 "Reviewed-by" tag included in the resulting pa 160 "Reviewed-by" tag included in the resulting patch. Finding another
161 developer familiar with Linux contribution, es 161 developer familiar with Linux contribution, especially within your own
162 organization, and having them help with review 162 organization, and having them help with reviews before sending them to
163 the public mailing lists tends to significantl 163 the public mailing lists tends to significantly improve the quality of the
164 resulting patches, and there by reduces the bu 164 resulting patches, and there by reduces the burden on other developers.
165 165
166 If no one can be found to internally review pa 166 If no one can be found to internally review patches and you need
167 help finding such a person, or if you have any 167 help finding such a person, or if you have any other questions
168 related to this document and the developer com 168 related to this document and the developer community's expectations,
169 please reach out to the private Technical Advi 169 please reach out to the private Technical Advisory Board mailing list:
170 <tech-board@groups.linuxfoundation.org>. 170 <tech-board@groups.linuxfoundation.org>.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.