171 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. _researcher_guidelines:4 5Researcher Guidelines6+++++++++++++++++++++7 8The Linux kernel community welcomes transparent research on the Linux9kernel, the activities involved in producing it, and any other byproducts10of its development. Linux benefits greatly from this kind of research, and11most aspects of Linux are driven by research in one form or another.12 13The community greatly appreciates if researchers can share preliminary14findings before making their results public, especially if such research15involves security. Getting involved early helps both improve the quality16of research and ability for Linux to improve from it. In any case,17sharing open access copies of the published research with the community18is recommended.19 20This document seeks to clarify what the Linux kernel community considers21acceptable and non-acceptable practices when conducting such research. At22the very least, such research and related activities should follow23standard research ethics rules. For more background on research ethics24generally, ethics in technology, and research of developer communities25in 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 the32project is participating in good faith to make Linux better. Research on33any publicly-available artifact (including, but not limited to source34code) produced by the Linux kernel community is welcome, though research35on 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 public39repositories, 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 the43explicit agreement of, and full disclosure to, the individual developers44involved. Developers cannot be interacted with/experimented on without45consent; this, too, is standard research ethics.46 47Surveys48=======49 50Research often takes the form of surveys sent to maintainers or51contributors. As a general rule, though, the kernel community derives52little value from these surveys. The kernel development process works53because every developer benefits from their participation, even working54with others who have different goals. Responding to a survey, though, is a55one-way demand placed on busy developers with no corresponding benefit to56themselves or to the kernel community as a whole. For this reason, this57method of research is discouraged.58 59Kernel community members already receive far too much email and are likely60to perceive survey requests as just another demand on their time. Sending61such requests deprives the community of valuable contributor time and is62unlikely to yield a statistically useful response.63 64As an alternative, researchers should consider attending developer events,65hosting sessions where the research project and its benefits to the66participants can be explained, and interacting directly with the community67there. The information received will be far richer than that obtained from68an email survey, and the community will gain from the ability to learn from69your insights as well.70 71Patches72=======73 74To help clarify: sending patches to developers *is* interacting75with them, but they have already consented to receiving *good faith76contributions*. Sending intentionally flawed/vulnerable patches or77contributing misleading information to discussions is not consented78to. Such communication can be damaging to the developer (e.g. draining79time, effort, and morale) and damaging to the project by eroding80the entire developer community's trust in the contributor (and the81contributor's organization as a whole), undermining efforts to provide82constructive feedback to contributors, and putting end users at risk of83software flaws.84 85Participation in the development of Linux itself by researchers, as86with anyone, is welcomed and encouraged. Research into Linux code is87a common practice, especially when it comes to developing or running88analysis tools that produce actionable results.89 90When engaging with the developer community, sending a patch has91traditionally been the best way to make an impact. Linux already has92plenty of known bugs -- what's much more helpful is having vetted fixes.93Before contributing, carefully read the appropriate documentation:94 95* Documentation/process/development-process.rst96* Documentation/process/submitting-patches.rst97* Documentation/admin-guide/reporting-issues.rst98* Documentation/process/security-bugs.rst99 100Then send a patch (including a commit log with all the details listed101below) and follow up on any feedback from other developers.102 103When sending patches produced from research, the commit logs should104contain at least the following details, so that developers have105appropriate context for understanding the contribution. Answer:106 107* What is the specific problem that has been found?108* How could the problem be reached on a running system?109* What effect would encountering the problem have on the system?110* How was the problem found? Specifically include details about any111 testing, static or dynamic analysis programs, and any other tools or112 methods used to perform the work.113* Which version of Linux was the problem found on? Using the most recent114 release or a recent linux-next branch is strongly preferred (see115 Documentation/process/howto.rst).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 tested?118* What prior commit does this change fix? This should go in a "Fixes:"119 tag as the documentation describes.120* Who else has reviewed this patch? This should go in appropriate121 "Reviewed-by:" tags; see below.122 123For example::124 125 From: Author <author@email>126 Subject: [PATCH] drivers/foo_bar: Add missing kfree()127 128 The error path in foo_bar driver does not correctly free the allocated129 struct foo_bar_info. This can happen if the attached foo_bar device130 rejects the initialization packets sent during foo_bar_probe(). This131 would result in a 64 byte slab memory leak once per device attach,132 wasting memory resources over time.133 134 This flaw was found using an experimental static analysis tool we are135 developing, LeakMagic[1], which reported the following warning when136 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. No other references to141 this memory exist outside the probe function, so this is the only142 place it can be freed.143 144 x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC145 11.2 show no new warnings, and LeakMagic no longer warns about this146 code path. As we don't have a FooBar device to test with, no runtime147 testing was able to be performed.148 149 [1] https://url/to/leakmagic/details150 151 Reported-by: Researcher <researcher@email>152 Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")153 Signed-off-by: Author <author@email>154 Reviewed-by: Reviewer <reviewer@email>155 156If you are a first time contributor it is recommended that the patch157itself be vetted by others privately before being posted to public lists.158(This is required if you have been explicitly told your patches need159more careful internal review.) These people are expected to have their160"Reviewed-by" tag included in the resulting patch. Finding another161developer familiar with Linux contribution, especially within your own162organization, and having them help with reviews before sending them to163the public mailing lists tends to significantly improve the quality of the164resulting patches, and there by reduces the burden on other developers.165 166If no one can be found to internally review patches and you need167help finding such a person, or if you have any other questions168related to this document and the developer community's expectations,169please reach out to the private Technical Advisory Board mailing list:170<tech-board@groups.linuxfoundation.org>.171