docs: reporting-issues: create a proper appendix explaining specialties

+44 -57

1 changed file

expand all

Documentation

admin-guide

+44 -57

Documentation/admin-guide/reporting-issues.rst

··· 1693 1693 for the subsystem as well as the stable mailing list (stable@vger.kernel.org). 1694 1694 1695 1695 1696 - Why some issues won't get any reaction or remain unfixed after being reported 1697 - ============================================================================= 1696 + Appendix: Why it is somewhat hard to report kernel bugs 1697 + ======================================================= 1698 1698 1699 - When reporting a problem to the Linux developers, be aware only 'issues of high 1700 - priority' (regressions, security issues, severe problems) are definitely going 1701 - to get resolved. The maintainers or if all else fails Linus Torvalds himself 1702 - will make sure of that. They and the other kernel developers will fix a lot of 1703 - other issues as well. But be aware that sometimes they can't or won't help; and 1704 - sometimes there isn't even anyone to send a report to. 1699 + The Linux kernel developers are well aware that reporting bugs to them is harder 1700 + than in other Free/Libre Open Source Projects. Many reasons for that lie in the 1701 + nature of kernels, Linux' development model, and how the world uses the kernel: 1705 1702 1706 - This is best explained with kernel developers that contribute to the Linux 1707 - kernel in their spare time. Quite a few of the drivers in the kernel were 1708 - written by such programmers, often because they simply wanted to make their 1709 - hardware usable on their favorite operating system. 1703 + * *Most kernels of Linux distributions are totally unsuitable for reporting bugs 1704 + upstream.* The reference section above already explained this in detail: 1705 + outdated codebases as well as modifications and add-ons lead to kernel bugs 1706 + that were fixed upstream a long time ago or never happened there in the first 1707 + place. Developers of other Open Source software face these problems as well, 1708 + but the situation is a lot worse when it comes to the kernel, as the changes 1709 + and their impact are much more severe -- which is why many kernel developers 1710 + expect reports with kernels built from fresh and nearly unmodified sources. 1710 1711 1711 - These programmers most of the time will happily fix problems other people 1712 - report. But nobody can force them to do, as they are contributing voluntarily. 1712 + * *Bugs often only occur in a special environment.* That is because Linux is 1713 + mostly drivers and can be used in a multitude of ways. Developers often do not 1714 + have a matching setup at hand -- and therefore frequently must rely on bug 1715 + reporters for isolating a problems's cause and testing proposed fixes. 1713 1716 1714 - Then there are situations where such developers really want to fix an issue, 1715 - but can't: sometimes they lack hardware programming documentation to do so. 1716 - This often happens when the publicly available docs are superficial or the 1717 - driver was written with the help of reverse engineering. 1717 + * *The kernel has hundreds of maintainers, but all-rounders are very rare.* That 1718 + again is and effect caused by the multitude of features and drivers, due to 1719 + which many kernel developers know little about lower or higher layers related 1720 + to their code and even less about other areas. 1718 1721 1719 - Sooner or later spare time developers will also stop caring for the driver. 1720 - Maybe their test hardware broke, got replaced by something more fancy, or is so 1721 - old that it's something you don't find much outside of computer museums 1722 - anymore. Sometimes developer stops caring for their code and Linux at all, as 1723 - something different in their life became way more important. In some cases 1724 - nobody is willing to take over the job as maintainer – and nobody can be forced 1725 - to, as contributing to the Linux kernel is done on a voluntary basis. Abandoned 1726 - drivers nevertheless remain in the kernel: they are still useful for people and 1727 - removing would be a regression. 1722 + * *It is hard finding where to report issues to, among others, due to the lack 1723 + of a central bug tracker.* This is something even some kernel developers 1724 + dislike, but that's the situation everyone has to deal with currently. 1728 1725 1729 - The situation is not that different with developers that are paid for their 1730 - work on the Linux kernel. Those contribute most changes these days. But their 1731 - employers sooner or later also stop caring for their code or make its 1732 - programmer focus on other things. Hardware vendors for example earn their money 1733 - mainly by selling new hardware; quite a few of them hence are not investing 1734 - much time and energy in maintaining a Linux kernel driver for something they 1735 - stopped selling years ago. Enterprise Linux distributors often care for a 1736 - longer time period, but in new versions often leave support for old and rare 1737 - hardware aside to limit the scope. Often spare time contributors take over once 1738 - a company orphans some code, but as mentioned above: sooner or later they will 1739 - leave the code behind, too. 1726 + * *Stable and longterm kernels are primarily maintained by a dedicated 'stable 1727 + team', which only handles regressions introduced within stable and longterm 1728 + series.* When someone reports a bug, say, using Linux 6.1.2, the team will, 1729 + therefore, always ask if mainline is affected: if the bug already happened 1730 + in 6.1 or occurs with latest mainline (say, 6.2-rc3), they in everybody's 1731 + interest shove it to the regular developers, as those know the code best. 1740 1732 1741 - Priorities are another reason why some issues are not fixed, as maintainers 1742 - quite often are forced to set those, as time to work on Linux is limited. 1743 - That's true for spare time or the time employers grant their developers to 1744 - spend on maintenance work on the upstream kernel. Sometimes maintainers also 1745 - get overwhelmed with reports, even if a driver is working nearly perfectly. To 1746 - not get completely stuck, the programmer thus might have no other choice than 1747 - to prioritize issue reports and reject some of them. 1733 + * *Linux developers are free to focus on latest mainline.* Some, thus, react 1734 + coldly to reports about bugs in, say, Linux 6.0 when 6.1 is already out; 1735 + even the latter might not be enough once 6.2-rc1 is out. Some will also not 1736 + be very welcoming to reports with 6.1.5 or 6.1.6, as the problem might be a 1737 + series-specific regression the stable team (see above) caused and must fix. 1748 1738 1749 - But don't worry too much about all of this, a lot of drivers have active 1750 - maintainers who are quite interested in fixing as many issues as possible. 1739 + * *Sometimes there is nobody to help.* Sometimes this is due to the lack of 1740 + hardware documentation -- for example, when a driver was built using reverse 1741 + engineering or was taken over by spare-time developers when the hardware 1742 + manufacturer left it behind. Other times there is nobody to even report bugs 1743 + to: when maintainers move on without a replacement, their code often remains 1744 + in the kernel as long as it's useful. 1751 1745 1752 - 1753 - Closing words 1754 - ============= 1755 - 1756 - Compared with other Free/Libre & Open Source Software it's hard to report 1757 - issues to the Linux kernel developers: the length and complexity of this 1758 - document and the implications between the lines illustrate that. But that's how 1759 - it is for now. The main author of this text hopes documenting the state of the 1760 - art will lay some groundwork to improve the situation over time. 1761 - 1746 + Some of these aspects could be improved to facilitate bug reporting -- many 1747 + Linux kernel developers are well aware of this and would be glad if a few 1748 + individuals or an entity would make this their mission. 1762 1749 1763 1750 .. 1764 1751 end-of-content

Configure Feed

Configure Feed