Documentation/process/researcher-guidelines.rst

   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
  71 * Documentation/process/security-bugs.rst
  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>.