mirror of
https://github.com/torvalds/linux.git
synced 2024-12-13 14:43:03 +00:00
ad93f083bd
It is common for university researchers to want to poll the community with online surveys, but that approach distracts developers while yielding little in the way of useful data. Encourage alternatives instead. Co-developed-by: Dan Williams <dan.j.williams@intel.com> Signed-off-by: Dan Williams <dan.j.williams@intel.com> Reviewed-by: Christian Brauner <brauner@kernel.org> Reviewed-by: Kees Cook <keescook@chromium.org> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/87il9v7u55.fsf@meer.lwn.net
171 lines
8.1 KiB
ReStructuredText
171 lines
8.1 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
.. _researcher_guidelines:
|
|
|
|
Researcher Guidelines
|
|
+++++++++++++++++++++
|
|
|
|
The Linux kernel community welcomes transparent research on the Linux
|
|
kernel, the activities involved in producing it, and any other byproducts
|
|
of its development. Linux benefits greatly from this kind of research, and
|
|
most aspects of Linux are driven by research in one form or another.
|
|
|
|
The community greatly appreciates if researchers can share preliminary
|
|
findings before making their results public, especially if such research
|
|
involves security. Getting involved early helps both improve the quality
|
|
of research and ability for Linux to improve from it. In any case,
|
|
sharing open access copies of the published research with the community
|
|
is recommended.
|
|
|
|
This document seeks to clarify what the Linux kernel community considers
|
|
acceptable and non-acceptable practices when conducting such research. At
|
|
the very least, such research and related activities should follow
|
|
standard research ethics rules. For more background on research ethics
|
|
generally, ethics in technology, and research of developer communities
|
|
in particular, see:
|
|
|
|
* `History of Research Ethics <https://www.unlv.edu/research/ORI-HSR/history-ethics>`_
|
|
* `IEEE Ethics <https://www.ieee.org/about/ethics/index.html>`_
|
|
* `Developer and Researcher Views on the Ethics of Experiments on Open-Source Projects <https://arxiv.org/pdf/2112.13217.pdf>`_
|
|
|
|
The Linux kernel community expects that everyone interacting with the
|
|
project is participating in good faith to make Linux better. Research on
|
|
any publicly-available artifact (including, but not limited to source
|
|
code) produced by the Linux kernel community is welcome, though research
|
|
on developers must be distinctly opt-in.
|
|
|
|
Passive research that is based entirely on publicly available sources,
|
|
including posts to public mailing lists and commits to public
|
|
repositories, is clearly permissible. Though, as with any research,
|
|
standard ethics must still be followed.
|
|
|
|
Active research on developer behavior, however, must be done with the
|
|
explicit agreement of, and full disclosure to, the individual developers
|
|
involved. Developers cannot be interacted with/experimented on without
|
|
consent; this, too, is standard research ethics.
|
|
|
|
Surveys
|
|
=======
|
|
|
|
Research often takes the form of surveys sent to maintainers or
|
|
contributors. As a general rule, though, the kernel community derives
|
|
little value from these surveys. The kernel development process works
|
|
because every developer benefits from their participation, even working
|
|
with others who have different goals. Responding to a survey, though, is a
|
|
one-way demand placed on busy developers with no corresponding benefit to
|
|
themselves or to the kernel community as a whole. For this reason, this
|
|
method of research is discouraged.
|
|
|
|
Kernel community members already receive far too much email and are likely
|
|
to perceive survey requests as just another demand on their time. Sending
|
|
such requests deprives the community of valuable contributor time and is
|
|
unlikely to yield a statistically useful response.
|
|
|
|
As an alternative, researchers should consider attending developer events,
|
|
hosting sessions where the research project and its benefits to the
|
|
participants can be explained, and interacting directly with the community
|
|
there. The information received will be far richer than that obtained from
|
|
an email survey, and the community will gain from the ability to learn from
|
|
your insights as well.
|
|
|
|
Patches
|
|
=======
|
|
|
|
To help clarify: sending patches to developers *is* interacting
|
|
with them, but they have already consented to receiving *good faith
|
|
contributions*. Sending intentionally flawed/vulnerable patches or
|
|
contributing misleading information to discussions is not consented
|
|
to. Such communication can be damaging to the developer (e.g. draining
|
|
time, effort, and morale) and damaging to the project by eroding
|
|
the entire developer community's trust in the contributor (and the
|
|
contributor's organization as a whole), undermining efforts to provide
|
|
constructive feedback to contributors, and putting end users at risk of
|
|
software flaws.
|
|
|
|
Participation in the development of Linux itself by researchers, as
|
|
with anyone, is welcomed and encouraged. Research into Linux code is
|
|
a common practice, especially when it comes to developing or running
|
|
analysis tools that produce actionable results.
|
|
|
|
When engaging with the developer community, sending a patch has
|
|
traditionally been the best way to make an impact. Linux already has
|
|
plenty of known bugs -- what's much more helpful is having vetted fixes.
|
|
Before contributing, carefully read the appropriate documentation:
|
|
|
|
* Documentation/process/development-process.rst
|
|
* Documentation/process/submitting-patches.rst
|
|
* Documentation/admin-guide/reporting-issues.rst
|
|
* Documentation/process/security-bugs.rst
|
|
|
|
Then send a patch (including a commit log with all the details listed
|
|
below) and follow up on any feedback from other developers.
|
|
|
|
When sending patches produced from research, the commit logs should
|
|
contain at least the following details, so that developers have
|
|
appropriate context for understanding the contribution. Answer:
|
|
|
|
* What is the specific problem that has been found?
|
|
* How could the problem be reached on a running system?
|
|
* What effect would encountering the problem have on the system?
|
|
* How was the problem found? Specifically include details about any
|
|
testing, static or dynamic analysis programs, and any other tools or
|
|
methods used to perform the work.
|
|
* Which version of Linux was the problem found on? Using the most recent
|
|
release or a recent linux-next branch is strongly preferred (see
|
|
Documentation/process/howto.rst).
|
|
* What was changed to fix the problem, and why it is believed to be correct?
|
|
* How was the change build tested and run-time tested?
|
|
* What prior commit does this change fix? This should go in a "Fixes:"
|
|
tag as the documentation describes.
|
|
* Who else has reviewed this patch? This should go in appropriate
|
|
"Reviewed-by:" tags; see below.
|
|
|
|
For example::
|
|
|
|
From: Author <author@email>
|
|
Subject: [PATCH] drivers/foo_bar: Add missing kfree()
|
|
|
|
The error path in foo_bar driver does not correctly free the allocated
|
|
struct foo_bar_info. This can happen if the attached foo_bar device
|
|
rejects the initialization packets sent during foo_bar_probe(). This
|
|
would result in a 64 byte slab memory leak once per device attach,
|
|
wasting memory resources over time.
|
|
|
|
This flaw was found using an experimental static analysis tool we are
|
|
developing, LeakMagic[1], which reported the following warning when
|
|
analyzing the v5.15 kernel release:
|
|
|
|
path/to/foo_bar.c:187: missing kfree() call?
|
|
|
|
Add the missing kfree() to the error path. No other references to
|
|
this memory exist outside the probe function, so this is the only
|
|
place it can be freed.
|
|
|
|
x86_64 and arm64 defconfig builds with CONFIG_FOO_BAR=y using GCC
|
|
11.2 show no new warnings, and LeakMagic no longer warns about this
|
|
code path. As we don't have a FooBar device to test with, no runtime
|
|
testing was able to be performed.
|
|
|
|
[1] https://url/to/leakmagic/details
|
|
|
|
Reported-by: Researcher <researcher@email>
|
|
Fixes: aaaabbbbccccdddd ("Introduce support for FooBar")
|
|
Signed-off-by: Author <author@email>
|
|
Reviewed-by: Reviewer <reviewer@email>
|
|
|
|
If you are a first time contributor it is recommended that the patch
|
|
itself be vetted by others privately before being posted to public lists.
|
|
(This is required if you have been explicitly told your patches need
|
|
more careful internal review.) These people are expected to have their
|
|
"Reviewed-by" tag included in the resulting patch. Finding another
|
|
developer familiar with Linux contribution, especially within your own
|
|
organization, and having them help with reviews before sending them to
|
|
the public mailing lists tends to significantly improve the quality of the
|
|
resulting patches, and there by reduces the burden on other developers.
|
|
|
|
If no one can be found to internally review patches and you need
|
|
help finding such a person, or if you have any other questions
|
|
related to this document and the developer community's expectations,
|
|
please reach out to the private Technical Advisory Board mailing list:
|
|
<tech-board@lists.linux-foundation.org>.
|