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