Skip to content

L
linux
Switch branch/tag
  1. 03 Mar, 2024 3 commits
    • Thorsten Leemhuis's avatar
      docs: new text on bisecting which also covers bug validation · 78129672
      Thorsten Leemhuis authored 
      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: default avatarThorsten Leemhuis <linux@leemhuis.info>
[jc: Undo spurious removal of subsection header line]
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <02b084a06de4ad61ac4ecd92b9265d4df4d03d71.1709282441.git.linux@leemhuis.info>
      78129672
    • Lukas Bulwahn's avatar
      docs: drop the version constraints for sphinx and dependencies · b31274d5
      Lukas Bulwahn authored 
      As discussed (see Links), there is some inertia to move to the recent
Sphinx versions for the doc build environment.

As first step, drop the version constraints and the related comments. As
sphinx depends on jinja2, jinja2 is pulled in automatically. So drop that.
Then, the sphinx-pre-install script will fail though with:

  Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.

The script simply expects to parse a version constraint with Sphinx in the
requirements.txt. That version is used in the script for suggesting the
virtualenv directory name.

To suggest a virtualenv directory name, when there is no version given in
the requirements.txt, one could try to guess the version that would be
downloaded with 'pip install -r Documentation/sphinx/requirements.txt'.
However, there seems no simple way to get that version without actually
setting up the venv and running pip. So, instead, name the directory with
the fixed name 'sphinx_latest'.

Finally update the Sphinx build documentation to reflect this directory
name change.

Link: https://lore.kernel.org/linux-doc/874jf4m384.fsf@meer.lwn.net/
Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulwahn@gmail.com/Reviewed-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Tested-by: default avatarVegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: default avatarLukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>
      b31274d5
    • Akira Yokosawa's avatar
      docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4 · 0df46e09
      Akira Yokosawa authored 
      Now that Sphinx 2.4.4 or better is required, get rid of
\providecommand{}'s for compatibility with Sphinx 1.7.9.

While at it, reword the comment on \sphinxtableofcontentshook
for better description of why it needs to be emptied.
Signed-off-by: default avatarAkira Yokosawa <akiyks@gmail.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <ed1ec6f2-0050-46f6-807d-8679f26427e9@gmail.com>
      0df46e09
  3. 28 Feb, 2024 2 commits
  5. 21 Feb, 2024 15 commits
  7. 20 Feb, 2024 1 commit
  9. 14 Feb, 2024 7 commits
  11. 12 Feb, 2024 4 commits
  13. 08 Feb, 2024 2 commits
  15. 05 Feb, 2024 6 commits
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7