Commit | Line | Data |
---|---|---|
f09f6f9b KC |
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 | |
44ac5aba | 71 | * Documentation/process/security-bugs.rst |
f09f6f9b KC |
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>. |