Skip to content

L
linux
Switch branch/tag
  1. 03 Mar, 2024 4 commits
    • Lukas Bulwahn's avatar
      docs: submit-checklist: structure by category · 5969fbf3
      Lukas Bulwahn authored 
      While going through the submit checklist, the list order seemed rather
random, probably just by historical coincidences of always adding yet the
next point someone thought of at the end of the list.

Structure and order them by the category of such activity,
reviewing, documenting, checking with tools, building and testing.

As the diff of the reordering is large:
Review code now includes previous points 1, 5 and 22.
Review Kconfig includes previous 6, 7 and 8.
Documenting includes previous 11, 15, 16, 17, 18 and 23.
Checking with tools includes previous 5, 9 and 10.
Building includes previous 2, 3, 20 and 24.
Testing includes previous 12, 13, 14, 19 and 21.

Previous point 4 (compile for ppc64) was merged into point 3 (build for
many architectures), as it was just a further note to cross-compiling.

Previous point 5 was split into one in review and one in checking
to have every previous point in the right category.
Point 11 was shortened, as building documentation is mentioned already
in Build your code, 1d.

A note that was presented visually much too aggressive in the HTML view was
turned into a simple "Note that..." sentence in the enumeration.

The recommendation to test with the -mm patchset (previous 21, now
testing, point 5) was updated to the current state of affairs to test with
a recent tag of linux-next.

Note that the previous first point still remains the first list even after
reordering. Randy confirmed that it was important to Stephen Rothwell to
keep 'include what you use' to be the first in the list.

While at it, replace the reference to the obsolete CONFIG_DEBUG_SLAB with
CONFIG_SLUB_DEBUG.
Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarLukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <20240229030743.9125-2-lukas.bulwahn@gmail.com>
      5969fbf3
    • 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 5 commits
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7