mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-09-28 13:22:57 +00:00
docs: reporting-issues.rst: duplicate sections for reviewing purposes
This duplicates two section to make the diff in the next patch a bit easier to gasp for humans. Straight copy, no content changes. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/ef85edc8466f035eb243dd6629429ad4fd0565d8.1616181657.git.linux@leemhuis.info Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
parent
4f08d7ab90
commit
9bc4430db5
1 changed files with 184 additions and 0 deletions
|
@ -328,6 +328,66 @@ those often get rejected or ignored, so consider yourself warned. But it's still
|
||||||
better than not reporting the issue at all: sometimes such reports directly or
|
better than not reporting the issue at all: sometimes such reports directly or
|
||||||
indirectly will help to get the issue fixed over time.
|
indirectly will help to get the issue fixed over time.
|
||||||
|
|
||||||
|
|
||||||
|
Search for existing reports
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
*Search the archives of the bug tracker or mailing list in question
|
||||||
|
thoroughly for reports that might match your issue. Also check if you find
|
||||||
|
something with your favorite internet search engine or in the Linux Kernel
|
||||||
|
Mailing List (LKML) archives. If you find anything, join the discussion
|
||||||
|
instead of sending a new report.*
|
||||||
|
|
||||||
|
Reporting an issue that someone else already brought forward is often a waste
|
||||||
|
of time for everyone involved, especially you as the reporter. So it's in your
|
||||||
|
own interest to thoroughly check if somebody reported the issue already. Thus
|
||||||
|
do not hurry with this step of the reporting process. Spending 30 to 60 minutes
|
||||||
|
or even more time can save you and others quite a lot of time and trouble.
|
||||||
|
|
||||||
|
The best place to search is the bug tracker or the mailing list where your
|
||||||
|
report needs to be filed. You'll find quite a few of those lists on
|
||||||
|
`lore.kernel.org <https://lore.kernel.org/>`_, but some are hosted in
|
||||||
|
different places. That for example is the case for the ath10k WiFi driver used
|
||||||
|
as example in the previous step. But you'll often find the archives for these
|
||||||
|
lists easily on the net. Searching for 'archive ath10k@lists.infradead.org' for
|
||||||
|
example will quickly lead you to the `Info page for the ath10k mailing list
|
||||||
|
<https://lists.infradead.org/mailman/listinfo/ath10k>`_, which at the top links
|
||||||
|
to its `list archives <https://lists.infradead.org/pipermail/ath10k/>`_.
|
||||||
|
|
||||||
|
Sadly this and quite a few other lists miss a way to search the archives. In
|
||||||
|
those cases use a regular internet search engine and add something like
|
||||||
|
'site:lists.infradead.org/pipermail/ath10k/' to your search terms, which limits
|
||||||
|
the results to the archives at that URL.
|
||||||
|
|
||||||
|
Additionally, search the internet and the `Linux Kernel Mailing List (LKML)
|
||||||
|
archives <https://lore.kernel.org/lkml/>`_, as maybe the real culprit might be
|
||||||
|
in some other subsystem. Searching in `bugzilla.kernel.org
|
||||||
|
<https://bugzilla.kernel.org/>`_ might also be a good idea, but if you find
|
||||||
|
anything there keep in mind: most subsystems expect reports in different
|
||||||
|
places, hence those you find there might have not even reached the people
|
||||||
|
responsible for the subsystem in question. Nevertheless, the data there might
|
||||||
|
provide valuable insights.
|
||||||
|
|
||||||
|
If you get flooded with results consider telling your search engine to limit
|
||||||
|
search timeframe to the past month or year. And wherever you search, make sure
|
||||||
|
to use good search terms; vary them a few times, too. While doing so try to
|
||||||
|
look at the issue from the perspective of someone else: that will help you to
|
||||||
|
come up with other words to use as search terms. Also make sure not to use too
|
||||||
|
many search terms at once. Remember to search with and without information like
|
||||||
|
the name of the kernel driver or the name of the affected hardware component.
|
||||||
|
But its exact brand name (say 'ASUS Red Devil Radeon RX 5700 XT Gaming OC')
|
||||||
|
often is not much helpful, as it is too specific. Instead try search terms like
|
||||||
|
the model line (Radeon 5700 or Radeon 5000) and the code name of the main chip
|
||||||
|
('Navi' or 'Navi10') with and without its manufacturer ('AMD').
|
||||||
|
|
||||||
|
In case you find an existing report about your issue, join the discussion, as
|
||||||
|
you might be able to provide valuable additional information. That can be
|
||||||
|
important even when a fix is prepared or in its final stages already, as
|
||||||
|
developers might look for people that can provide additional information or
|
||||||
|
test a proposed fix. Jump to the section 'Duties after the report went out' for
|
||||||
|
details on how to get properly involved.
|
||||||
|
|
||||||
|
|
||||||
Issue of high priority?
|
Issue of high priority?
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
|
@ -1523,6 +1583,130 @@ was already fixed in the latest release of version line you're interested in.
|
||||||
This kernel needs to be vanilla and shouldn't be tainted before the issue
|
This kernel needs to be vanilla and shouldn't be tainted before the issue
|
||||||
happens, as detailed outlined already above in the process of testing mainline.
|
happens, as detailed outlined already above in the process of testing mainline.
|
||||||
|
|
||||||
|
|
||||||
|
Check code history and search for existing discussions
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
*Search the Linux kernel version control system for the change that fixed
|
||||||
|
the issue in mainline, as its commit message might tell you if the fix is
|
||||||
|
scheduled for backporting already. If you don't find anything that way,
|
||||||
|
search the appropriate mailing lists for posts that discuss such an issue
|
||||||
|
or peer-review possible fixes; then check the discussions if the fix was
|
||||||
|
deemed unsuitable for backporting. If backporting was not considered at
|
||||||
|
all, join the newest discussion, asking if it's in the cards.*
|
||||||
|
|
||||||
|
In a lot of cases the issue you deal with will have happened with mainline, but
|
||||||
|
got fixed there. The commit that fixed it would need to get backported as well
|
||||||
|
to get the issue solved. That's why you want to search for it or any
|
||||||
|
discussions abound it.
|
||||||
|
|
||||||
|
* First try to find the fix in the Git repository that holds the Linux kernel
|
||||||
|
sources. You can do this with the web interfaces `on kernel.org
|
||||||
|
<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_
|
||||||
|
or its mirror `on GitHub <https://github.com/torvalds/linux>`_; if you have
|
||||||
|
a local clone you alternatively can search on the command line with ``git
|
||||||
|
log --grep=<pattern>``.
|
||||||
|
|
||||||
|
If you find the fix, look if the commit message near the end contains a
|
||||||
|
'stable tag' that looks like this:
|
||||||
|
|
||||||
|
Cc: <stable@vger.kernel.org> # 5.4+
|
||||||
|
|
||||||
|
If that's case the developer marked the fix safe for backporting to version
|
||||||
|
line 5.4 and later. Most of the time it's getting applied there within two
|
||||||
|
weeks, but sometimes it takes a bit longer.
|
||||||
|
|
||||||
|
* If the commit doesn't tell you anything or if you can't find the fix, look
|
||||||
|
again for discussions about the issue. Search the net with your favorite
|
||||||
|
internet search engine as well as the archives for the `Linux kernel
|
||||||
|
developers mailing list <https://lore.kernel.org/lkml/>`_. Also read the
|
||||||
|
section `Locate kernel area that causes the issue` above and follow the
|
||||||
|
instructions to find the subsystem in question: its bug tracker or mailing
|
||||||
|
list archive might have the answer you are looking for.
|
||||||
|
|
||||||
|
* If you see a proposed fix, search for it in the version control system as
|
||||||
|
outlined above, as the commit might tell you if a backport can be expected.
|
||||||
|
|
||||||
|
* Check the discussions for any indicators the fix might be too risky to get
|
||||||
|
backported to the version line you care about. If that's the case you have
|
||||||
|
to live with the issue or switch to the kernel version line where the fix
|
||||||
|
got applied.
|
||||||
|
|
||||||
|
* If the fix doesn't contain a stable tag and backporting was not discussed,
|
||||||
|
join the discussion: mention the version where you face the issue and that
|
||||||
|
you would like to see it fixed, if suitable.
|
||||||
|
|
||||||
|
Details about reporting issues only occurring in older kernel version lines
|
||||||
|
---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
This subsection provides details for steps you need to take if you could not
|
||||||
|
reproduce your issue with a mainline kernel, but want to see it fixed in older
|
||||||
|
version lines (aka stable and longterm kernels).
|
||||||
|
|
||||||
|
Some fixes are too complex
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
*Prepare yourself for the possibility that going through the next few steps
|
||||||
|
might not get the issue solved in older releases: the fix might be too big
|
||||||
|
or risky to get backported there.*
|
||||||
|
|
||||||
|
Even small and seemingly obvious code-changes sometimes introduce new and
|
||||||
|
totally unexpected problems. The maintainers of the stable and longterm kernels
|
||||||
|
are very aware of that and thus only apply changes to these kernels that are
|
||||||
|
within rules outlined in 'Documentation/process/stable-kernel-rules.rst'.
|
||||||
|
|
||||||
|
Complex or risky changes for example do not qualify and thus only get applied
|
||||||
|
to mainline. Other fixes are easy to get backported to the newest stable and
|
||||||
|
longterm kernels, but too risky to integrate into older ones. So be aware the
|
||||||
|
fix you are hoping for might be one of those that won't be backported to the
|
||||||
|
version line your care about. In that case you'll have no other choice then to
|
||||||
|
live with the issue or switch to a newer Linux version, unless you want to
|
||||||
|
patch the fix into your kernels yourself.
|
||||||
|
|
||||||
|
Make sure the particular version line still gets support
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
*Check if the kernel developers still maintain the Linux kernel version
|
||||||
|
line you care about: go to the front page of kernel.org and make sure it
|
||||||
|
mentions the latest release of the particular version line without an
|
||||||
|
'[EOL]' tag.*
|
||||||
|
|
||||||
|
Most kernel version lines only get supported for about three months, as
|
||||||
|
maintaining them longer is quite a lot of work. Hence, only one per year is
|
||||||
|
chosen and gets supported for at least two years (often six). That's why you
|
||||||
|
need to check if the kernel developers still support the version line you care
|
||||||
|
for.
|
||||||
|
|
||||||
|
Note, if kernel.org lists two 'stable' version lines on the front page, you
|
||||||
|
should consider switching to the newer one and forget about the older one:
|
||||||
|
support for it is likely to be abandoned soon. Then it will get a "end-of-life"
|
||||||
|
(EOL) stamp. Version lines that reached that point still get mentioned on the
|
||||||
|
kernel.org front page for a week or two, but are unsuitable for testing and
|
||||||
|
reporting.
|
||||||
|
|
||||||
|
Search stable mailing list
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
*Check the archives of the Linux stable mailing list for existing reports.*
|
||||||
|
|
||||||
|
Maybe the issue you face is already known and was fixed or is about to. Hence,
|
||||||
|
`search the archives of the Linux stable mailing list
|
||||||
|
<https://lore.kernel.org/stable/>`_ for reports about an issue like yours. If
|
||||||
|
you find any matches, consider joining the discussion, unless the fix is
|
||||||
|
already finished and scheduled to get applied soon.
|
||||||
|
|
||||||
|
Reproduce issue with the newest release
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
*Install the latest release from the particular version line as a vanilla
|
||||||
|
kernel. Ensure this kernel is not tainted and still shows the problem, as
|
||||||
|
the issue might have already been fixed there.*
|
||||||
|
|
||||||
|
Before investing any more time in this process you want to check if the issue
|
||||||
|
was already fixed in the latest release of version line you're interested in.
|
||||||
|
This kernel needs to be vanilla and shouldn't be tainted before the issue
|
||||||
|
happens, as detailed outlined already above in the process of testing mainline.
|
||||||
|
|
||||||
Check code history and search for existing discussions
|
Check code history and search for existing discussions
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue