On 10/1/20 1:50 AM, Thorsten Leemhuis wrote:
> Describe what users have to do if they can't reproduce a problem with
> mainline they want to see fixed in stable and longterm kernels. This is
> separated from the main flow, as integrating it there would make it
> harder to follow.
>
> Note users will only enter this section in two cases: (1) the issue was
> fixed in mainline (on purpose or accidentally) (2) it's a regression
accidentally); (2)
> that never was present in mainline (for example due to a broken
> backport).
>
> Help users to differentiate between the two, as they ideally are handled
> differently.
>
> Signed-off-by: Thorsten Leemhuis <li...@leemhuis.info>
> ---
> Documentation/admin-guide/reporting-bugs.rst | 191 +++++++++++++++++--
> 1 file changed, 179 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/admin-guide/reporting-bugs.rst
> b/Documentation/admin-guide/reporting-bugs.rst
> index b8bc6c4e2340..340fa44b352c 100644
> --- a/Documentation/admin-guide/reporting-bugs.rst
> +++ b/Documentation/admin-guide/reporting-bugs.rst
> @@ -1223,24 +1223,191 @@ with a bit of luck there might be someone in the
> team that knows a bit about
> programming and might be able to write a fix.
>
>
> +Details about reporting issues only occurring in older kernel version lines
> +---------------------------------------------------------------------------
> +
> +Find below details about the steps in the subsection for reporting issues
> that
> +only happen in 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
> +:ref:`within rules outlined in Documentation/process/stable-kernel-rules.rst
> +<stable_kernel_rules>`.
> +
> +Complex or risky changes for example do not qualify and thus only get
> applied to
> +mainline; sometimes 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 and that you have no other
> choice
> +then to live with the issue or switch to a newer version, unless you want to
> +patch the fix into your own kernels yourselfs.
yourself.
> +
> +
> +Make sure the particular version line is still supported
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> + *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
front page
> + 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 developer still support the version line you care
devlopers
> +for.
> +
> +Note: if kernel.org lists two 'stable' version lines, you likely want to
> focus
> +on the newer of the two, as support for the older is likely to be abandoned
> +soon and thus "end-of-life" (EOL). Version lines that reached that point
> still
> +get mentioned on the kernel.org-frontpage for a week or two, but then they
> are
kernel.org front page
> +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 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
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> + *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. That might lead you to the commit with the
> fix
> + or tell you if it's unsuitable for backporting. If backporting was not
> + considered at all, join the newest discussion, asking if its in the
> cards.*
it's
> +
> +In a lot of cases the issue you deal with, will have happened with mainline,
with will
> +but got fixed there. The commit that fixed it would need to get backported as
> +well to get the issue solved. That why you want to search for it or any
> +discussions abound it.
> +
> + * First try to find the fix on the Git repository that holds the Linux
> kernel
I would say in
but maybe it doesn't matter.
> + 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: <sta...@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
^^^ too many spaces.
> + 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
^^ drop one space.
> + 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.
> +
> +
> +Check if it's a regression specific to stable or longterm kernels
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> + *Check if you're dealing with a regression that was never present in
> + mainline by installing the first release of the version line you care
> about.
> + If the issue doesn't show up with it, you basically need to report the
> issue
> + with this version like you would report a problem with mainline (see
> above).
> + This ideally includes a bisection followed by a search for existing
> reports
> + on the net; with the help of the subject and the two relevant
> commit-ids. If
> + that doesn't turn up anything, write the report; CC or forward the
> report to
> + the stable maintainers, the stable mailing list, and those that authored
> the
> + change. Include the shortened commit-id if you found the change that
> causes
> + it.*
> +
> +Sometimes you won't find anything in the previous step: the issue you face
> might
> +have never occurred in mainline, as it its caused by some change that is
as it is caused
> +incomplete or not correctly applied. To check this, install the first release
> +from version line you care about, e.g. if you care about 5.4.x, install 5.4.
> +
> +If the issue doesn't show itself there, it's a regression specific to the
> +particular version line. In that case you need to report it like an issue
> +happening in mainline, like the last few steps in the main section above
in the main section in the
above
> +outline.
> +
> +One of them suggests doing a bisection, which you are strongly advised to do
> in
> +this case. After finding the culprit, search the net for existing reports
> again:
> +not only search for the exact subject and the commit-id (proper and
> shortened to
> +twelve characters) of the change, but also for the commit-id (proper and
> +shortened) mentioned as 'Upstream commit' in the commit message.
> +
> +Write the report, just keep a few specialties in mind: CC or forward the
> report
report; just
> +to the stable maintainers, the stable mailing list, which the `MAINTAINERS
> file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +mentions in the section "STABLE BRANCH". If you performed a successful
> +bisection, CC the author of the change and include its subject and the
> shortened
> +commit-id.
> +
> +Ask for advice
> +~~~~~~~~~~~~~~
> +
> + *One of the former steps should lead to a solution. If that doesn't work
> + out, ask the maintainers for the subsystem that seems to be causing the
> + issue for advice; CC the mailing list for the particular subsystem as
> well
> + as the stable mailing list.*
> +
> +If the previous three steps didn't get you closer to a solution there is only
> +one option left: ask for advice. Do that in a mail you sent to the
> maintainers
> +for the subsystem where the issue seems to have its roots; CC the mailing
> list
> +for the subsystem as well as the stable mailing list the `MAINTAINERS file
> +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/MAINTAINERS>`_
> +mention in the section "STABLE BRANCH".
> +
> +
--
~Randy
