Documentation/admin-guide/reporting-regressions.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/reporting-regressions.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/reporting-regressions.rst
Extension
.rst
Size
22602 bytes
Lines
452
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
.. [see the bottom of this file for redistribution information]

Reporting regressions
+++++++++++++++++++++

"*We don't cause regressions*" is the first rule of Linux kernel development;
Linux founder and lead developer Linus Torvalds established it himself and
ensures it's obeyed.

This document describes what the rule means for users and how the Linux kernel's
development model ensures to address all reported regressions; aspects relevant
for kernel developers are left to Documentation/process/handling-regressions.rst.


The important bits (aka "TL;DR")
================================

#. It's a regression if something running fine with one Linux kernel works worse
   or not at all with a newer version. Note, the newer kernel has to be compiled
   using a similar configuration; the detailed explanations below describes this
   and other fine print in more detail.

#. Report your issue as outlined in Documentation/admin-guide/reporting-issues.rst,
   it already covers all aspects important for regressions and repeated
   below for convenience. Two of them are important: start your report's subject
   with "[REGRESSION]" and CC or forward it to `the regression mailing list
   <https://lore.kernel.org/regressions/>`_ (regressions@lists.linux.dev).

#. Optional, but recommended: when sending or forwarding your report, make the
   Linux kernel regression tracking bot "regzbot" track the issue by specifying
   when the regression started like this::

       #regzbot introduced: v5.13..v5.14-rc1


All the details on Linux kernel regressions relevant for users
==============================================================


The important basics
--------------------


What is a "regression" and what is the "no regressions" rule?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's a regression if some application or practical use case running fine with
one Linux kernel works worse or not at all with a newer version compiled using a
similar configuration. The "no regressions" rule forbids this to take place; if
it happens by accident, developers that caused it are expected to quickly fix
the issue.

It thus is a regression when a WiFi driver from Linux 5.13 works fine, but with
5.14 doesn't work at all, works significantly slower, or misbehaves somehow.
It's also a regression if a perfectly working application suddenly shows erratic
behavior with a newer kernel version; such issues can be caused by changes in
procfs, sysfs, or one of the many other interfaces Linux provides to userland
software. But keep in mind, as mentioned earlier: 5.14 in this example needs to
be built from a configuration similar to the one from 5.13. This can be achieved
using ``make olddefconfig``, as explained in more detail below.

Note the "practical use case" in the first sentence of this section: developers
despite the "no regressions" rule are free to change any aspect of the kernel
and even APIs or ABIs to userland, as long as no existing application or use
case breaks.

Also be aware the "no regressions" rule covers only interfaces the kernel
provides to the userland. It thus does not apply to kernel-internal interfaces
like the module API, which some externally developed drivers use to hook into

Annotation

Implementation Notes