mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-12-29 17:25:38 +00:00
Linux kernel stable tree
7812967276
Add a second document on bisecting regressions explaining the whole process from beginning to end -- while also describing how to validate if a problem is still present in mainline. This "two in one" approach is possible, as checking whenever a bug is in mainline is one of the first steps before performing a bisection anyway and thus needs to be described. Due to this approach the text also works quite nicely in conjunction with Documentation/admin-guide/reporting-issues.rst, as it covers all typical cases where users will need to build a kernel in exactly the same order. The text targets users that normally run kernels from their Linux distributor who might never have compiled their own kernel. This aim is why the first kernel built while following this guide is generated from the latest mainline codebase. This will rule out that the regression (a) was fixed already and (b) is caused by config change a vendor distributor performed; checking mainline will furthermore (c) determine if the issue is something that needs to be reported to the regular developers or the stable team (this is needed even when readers bisect within a stable series). Only then are readers instructed to build their own variant of the 'good' kernel to validate the trimmed .config file created during early in the guide, as performing a bisection with a broken one would be a waste of time. There is a small downside of this order: readers might have to go back to testing mainline, if it turns out there is a problem with their .config. But that should be rare -- and if the regression was already fixed readers might not get to this point anyway. Hence in the end this order should mean that readers built less kernels overall. This sequence allows the text to easily cover the "check if a bug is present in the upstream kernel" case while only making things a tiny bit more complicated. The text tries to prevent readers from running into many mistakes users are known to frequently make. The steps required for this might look superfluous for people that are already familiar with bisections -- but anyone with that knowledge should be able to adapt the instructions to their use-case or will not need this text at all. Style and structure of the text match the one Documentation/admin-guide/quickly-build-trimmed-linux.rst uses. Quite a few paragraphs are even copied from there and not changed at all or only slightly. This will complicate maintenance, as some future changes to one of these documents will have to be replicated in the other. But this is the lesser evil: solutions like "sending readers from one document over to the other" or "extracting the common parts into a separate document" might work in other cases, but would be too confusing here given the topic and the target audience. Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info> [jc: Undo spurious removal of subsection header line] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <02b084a06de4ad61ac4ecd92b9265d4df4d03d71.1709282441.git.linux@leemhuis.info> |
||
|---|---|---|
| arch | ||
| block | ||
| certs | ||
| crypto | ||
| Documentation | ||
| drivers | ||
| fs | ||
| include | ||
| init | ||
| io_uring | ||
| ipc | ||
| kernel | ||
| lib | ||
| LICENSES | ||
| mm | ||
| net | ||
| rust | ||
| samples | ||
| scripts | ||
| security | ||
| sound | ||
| tools | ||
| usr | ||
| virt | ||
| .clang-format | ||
| .cocciconfig | ||
| .editorconfig | ||
| .get_maintainer.ignore | ||
| .gitattributes | ||
| .gitignore | ||
| .mailmap | ||
| .rustfmt.toml | ||
| COPYING | ||
| CREDITS | ||
| Kbuild | ||
| Kconfig | ||
| MAINTAINERS | ||
| Makefile | ||
| README | ||
Linux kernel
============
There are several guides for kernel developers and users. These guides can
be rendered in a number of formats, like HTML and PDF. Please read
Documentation/admin-guide/README.rst first.
In order to build the documentation, use ``make htmldocs`` or
``make pdfdocs``. The formatted documentation can also be read online at:
https://www.kernel.org/doc/html/latest/
There are various text files in the Documentation/ subdirectory,
several of them using the ReStructured Text markup notation.
Please read the Documentation/process/changes.rst file, as it contains the
requirements for building and running the kernel, and information about
the problems which may result by upgrading your kernel.