요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
linux-next and references
bug-bisect.rst:111-143next/stable과 next/master endpoint, 추가 bisect 자료를 정리합니다.
Maintenance and license
bug-bisect.rst:144-165Maintainer contact, contribution sign-off와 GPL/CC-BY 재배포 조건을 기록합니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
.. [see the bottom of this file for redistribution information]
======================
Bisecting a regression
======================
This document describes how to use a ``git bisect`` to find the source code
change that broke something -- for example when some functionality stopped
working after upgrading from Linux 6.0 to 6.1.
The text focuses on the gist of the process. If you are new to bisecting the
kernel, better follow Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
instead: it depicts everything from start to finish while covering multiple
aspects even kernel developers occasionally forget. This includes detecting
situations early where a bisection would be a waste of time, as nobody would
care about the result -- for example, because the problem happens after the
kernel marked itself as 'tainted', occurs in an abandoned version, was already
fixed, or is caused by a .config change you or your Linux distributor performed.
Finding the change causing a kernel issue using a bisection
===========================================================
*Note: the following process assumes you prepared everything for a bisection.
This includes having a Git clone with the appropriate sources, installing the
software required to build and install kernels, as well as a .config file stored
in a safe place (the following example assumes '~/prepared_kernel_.config') to
use as pristine base at each bisection step; ideally, you have also worked out
a fully reliable and straight-forward way to reproduce the regression, too.*
* Preparation: start the bisection and tell Git about the points in the history
you consider to be working and broken, which Git calls 'good' and 'bad'::
git bisect start
git bisect good v6.0
git bisect bad v6.1
Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.
1. Copy your prepared .config into the build directory and adjust it to the
needs of the codebase Git checked out for testing::
cp ~/prepared_kernel_.config .config
make olddefconfig
2. Now build, install, and boot a kernel. This might fail for unrelated reasons,
for example, when a compile error happens at the current stage of the
bisection a later change resolves. In such cases run ``git bisect skip`` and
go back to step 1.
3. Check if the functionality that regressed works in the kernel you just built.
If it works, execute::
git bisect good
If it is broken, run::
git bisect bad
Note, getting this wrong just once will send the rest of the bisection
totally off course. To prevent having to start anew later you thus want to
ensure what you tell Git is correct; it is thus often wise to spend a few
minutes more on testing in case your reproducer is unreliable.
After issuing one of these two commands, Git will usually check out another
bisection point and print something like 'Bisecting: 675 revisions left to
test after this (roughly 10 steps)'. In that case go back to step 1.
If Git instead prints something like 'cafecaca0c0dacafecaca0c0dacafecaca0c0da
is the first bad commit', then you have finished the bisection. In that case
move to the next point below. Note, right after displaying that line Git will
show some details about the culprit including its patch description; this can
easily fill your terminal, so you might need to scroll up to see the message
mentioning the culprit's commit-id.
In case you missed Git's output, you can always run ``git bisect log`` to
print the status: it will show how many steps remain or mention the result of
the bisection.
* Recommended complementary task: put the bisection log and the current .config
file aside for the bug report; furthermore tell Git to reset the sources to
the state before the bisection::
git bisect log > ~/bisection-log
cp .config ~/bisection-config-culprit
git bisect reset
* Recommended optional task: try reverting the culprit on top of the latest
codebase and check if that fixes your bug; if that is the case, it validates
the bisection and enables developers to resolve the regression through a
revert.
To try this, update your clone and check out latest mainline. Then tell Git
to revert the change by specifying its commit-id::
git revert --no-edit cafec0cacaca0
Git might reject this, for example when the bisection landed on a merge
commit. In that case, abandon the attempt. Do the same, if Git fails to revert
the culprit on its own because later changes depend on it -- at least unless
you bisected a stable or longterm kernel series, in which case you want to
check out its latest codebase and try a revert there.
If a revert succeeds, build and test another kernel to check if reverting
resolved your regression.
With that the process is complete. Now report the regression as described by
Documentation/admin-guide/reporting-issues.rst.
Bisecting linux-next
--------------------
If you face a problem only happening in linux-next, bisect between the
linux-next branches 'stable' and 'master'. The following commands will start
the process for a linux-next tree you added as a remote called 'next'::
git bisect start
git bisect good next/stable
git bisect bad next/master
The 'stable' branch refers to the state of linux-mainline that the current
linux-next release (found in the 'master' branch) is based on -- the former
thus should be free of any problems that show up in -next, but not in Linus'
tree.
This will bisect across a wide range of changes, some of which you might have
used in earlier linux-next releases without problems. Sadly there is no simple
way to avoid checking them: bisecting from one linux-next release to a later
one (say between 'next-20241020' and 'next-20241021') is impossible, as they
share no common history.
Additional reading material
---------------------------
* The `man page for 'git bisect' <https://git-scm.com/docs/git-bisect>`_ and
`fighting regressions with 'git bisect' <https://git-scm.com/docs/git-bisect-lk2009.html>`_
in the Git documentation.
* `Working with git bisect <https://nathanchance.dev/posts/working-with-git-bisect/>`_
from kernel developer Nathan Chancellor.
* `Using Git bisect to figure out when brokenness was introduced <http://webchick.net/node/99>`_.
* `Fully automated bisecting with 'git bisect run' <https://lwn.net/Articles/317154>`_.
..
end-of-content
..
This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
you spot a typo or small mistake, feel free to let him know directly and
he'll fix it. You are free to do the same in a mostly informal way if you
want to contribute changes to the text -- but for copyright reasons please CC
linux-doc@vger.kernel.org and 'sign-off' your contribution as
Documentation/process/submitting-patches.rst explains in the section 'Sign
your work - the Developer's Certificate of Origin'.
..
This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
of the file. If you want to distribute this text under CC-BY-4.0 only,
please use 'The Linux kernel development community' for author attribution
and link this as source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rst
..
Note: Only the content of this RST file as found in the Linux kernel sources
is available under CC-BY-4.0, as versions of this text that were processed
(for example by the kernel's build system) might contain content taken from
files which use a more restrictive license.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Regression bisect 목적과 준비
1-39이 문서는 GPL-2.0+ 또는 CC-BY-4.0으로 제공되며 `git bisect`로 Linux 6.0에서 6.1로 올린 뒤 기능이 멈춘 경우처럼 문제를 만든 source-code change를 찾는 방법을 설명합니다.
여기서는 핵심 절차에 집중합니다. Kernel bisect가 처음이면 `Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst`를 따라 start-to-finish 지침을 보는 편이 낫습니다. 그 문서는 tainted kernel, 버려진 version, 이미 수정된 문제, user 또는 distribution의 `.config` 변경처럼 결과를 활용할 사람이 없어 bisect가 낭비가 되는 상황을 일찍 찾는 방법도 다룹니다.
Bisect 전에 적절한 source Git clone, kernel build·install software, 매 step의 pristine base로 쓸 안전하게 보관한 `.config`(예제는 `~/prepared_kernel_.config`), 신뢰할 수 있고 단순한 regression reproducer를 준비합니다.
Git history에서 정상 지점을 `good`, 고장 지점을 `bad`로 알려 bisect를 시작합니다. Tag 대신 commit ID도 사용할 수 있습니다.
* Preparation: start the bisection and tell Git about the points in the history
you consider to be working and broken, which Git calls 'good' and 'bad'::
git bisect start
git bisect good v6.0
git bisect bad v6.1
Instead of Git tags like 'v6.0' and 'v6.1' you can specify commit-ids, too.결과가 의미 있는지 확인한 뒤 reproducible good/bad endpoints를 고릅니다.
Build·test·good/bad/skip 반복
40-80각 step에서 준비한 `.config`를 build directory에 복사하고 Git이 checkout한 codebase에 맞게 `make olddefconfig`로 조정합니다.
1. Copy your prepared .config into the build directory and adjust it to the
needs of the codebase Git checked out for testing::
cp ~/prepared_kernel_.config .config
make olddefconfigKernel을 build·install·boot합니다. 현재 revision의 compile error가 나중 change에서 해결되는 등 regression과 무관한 이유로 실패하면 `git bisect skip`을 실행하고 step 1로 돌아갑니다.
새 kernel에서 regression 기능을 검사합니다. 정상 작동하면 `git bisect good`, 고장이면 `git bisect bad`를 실행합니다.
3. Check if the functionality that regressed works in the kernel you just built.
If it works, execute::
git bisect good
If it is broken, run::
git bisect bad
판정을 한 번만 잘못해도 나머지 bisect가 완전히 틀어집니다. Reproducer가 불안정하면 처음부터 다시 시작하지 않도록 몇 분 더 테스트해 Git에 주는 답이 정확한지 확인합니다.
명령 뒤 Git이 `675 revisions left ... roughly 10 steps`처럼 다음 point를 checkout하면 step 1로 돌아갑니다. `... is the first bad commit`을 출력하면 완료입니다. 이어지는 patch description이 terminal을 채울 수 있으므로 culprit commit ID message를 보려면 위로 scroll해야 할 수 있습니다.
출력을 놓쳤다면 언제든 `git bisect log`로 남은 step 또는 결과를 확인할 수 있습니다.
Build 결과와 regression test 결과에 따라 다음 revision을 선택합니다.
Log 보존·reset·revert 검증·report
81-110권장 보완 작업으로 bug report에 쓸 bisect log와 현재 `.config`를 따로 저장하고 source를 bisect 전 상태로 reset합니다.
* Recommended complementary task: put the bisection log and the current .config
file aside for the bug report; furthermore tell Git to reset the sources to
the state before the bisection::
git bisect log > ~/bisection-log
cp .config ~/bisection-config-culprit
git bisect resetOptional 권장 작업은 최신 codebase 위에서 culprit를 revert하고 bug가 사라지는지 확인하는 것입니다. 성공하면 bisect를 검증하고 developer가 revert로 regression을 해결할 수 있게 합니다. Clone을 update하고 최신 mainline을 checkout한 뒤 culprit commit ID를 지정합니다.
* Recommended optional task: try reverting the culprit on top of the latest
codebase and check if that fixes your bug; if that is the case, it validates
the bisection and enables developers to resolve the regression through a
revert.
To try this, update your clone and check out latest mainline. Then tell Git
to revert the change by specifying its commit-id::
git revert --no-edit cafec0cacaca0
Bisect 결과가 merge commit이거나 뒤 change가 culprit에 의존해 Git이 자동 revert하지 못하면 시도를 포기합니다. 단 stable 또는 longterm series를 bisect했다면 해당 series의 최신 codebase에서 revert를 시도합니다. Revert가 성공하면 kernel을 다시 build·test해 regression 해결 여부를 확인합니다.
절차가 끝나면 `Documentation/admin-guide/reporting-issues.rst`에 따라 regression을 보고합니다.
Bisect 산출물을 보존하고 가능한 경우 revert로 인과를 재검증합니다.
linux-next bisect
111-132문제가 linux-next에서만 발생하면 linux-next의 `stable`과 `master` branch 사이를 bisect합니다. Remote 이름이 `next`인 tree에서는 다음 명령을 사용합니다.
If you face a problem only happening in linux-next, bisect between the
linux-next branches 'stable' and 'master'. The following commands will start
the process for a linux-next tree you added as a remote called 'next'::
git bisect start
git bisect good next/stable
git bisect bad next/master`stable`은 현재 `master` linux-next release가 기반으로 삼은 linux-mainline 상태입니다. 따라서 `stable`에는 -next에서만 나타나고 Linus tree에는 없는 문제가 없어야 합니다.
이 방식은 넓은 change 범위를 bisect하므로 과거 linux-next release에서 문제없이 사용한 change도 다시 검사할 수 있습니다. `next-20241020`과 `next-20241021`처럼 두 linux-next release 사이에는 공통 history가 없으므로 그 둘을 직접 bisect하는 간단한 방법은 없습니다.
Current linux-next가 기반으로 한 mainline과 -next head를 비교합니다.
추가 자료
133-143추가 자료로 Git의 `git bisect` man page, `fighting regressions with git bisect`, kernel developer Nathan Chancellor의 `Working with git bisect`, `Using Git bisect to figure out when brokenness was introduced`, LWN의 `Fully automated bisecting with git bisect run`을 제시합니다.
원문이 제시한 URL과 주제입니다.
문서 유지관리와 재배포 조건
144-165이 문서는 Thorsten Leemhuis `<linux@leemhuis.info>`가 유지합니다. Typo나 작은 오류는 직접 알려도 되며, 비공식적으로 text change를 기여할 수도 있습니다. 다만 copyright를 위해 `linux-doc@vger.kernel.org`를 CC하고 `Documentation/process/submitting-patches.rst`의 Developer's Certificate of Origin 절차에 따라 sign-off해야 합니다.
원문은 file 상단에 명시한 대로 GPL-2.0+ 또는 CC-BY-4.0으로 제공됩니다. CC-BY-4.0만으로 배포하려면 author attribution을 `The Linux kernel development community`로 하고 원문 source URL을 link해야 합니다.
This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
of the file. If you want to distribute this text under CC-BY-4.0 only,
please use 'The Linux kernel development community' for author attribution
and link this as source:
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/bug-bisect.rstCC-BY-4.0은 Linux kernel source에 있는 이 RST file 내용에만 적용됩니다. Kernel build system 등으로 처리된 version은 더 제한적인 license의 다른 file 내용을 포함할 수 있습니다.
선택한 license와 attribution·범위 조건입니다.
Main bisection
bug-bisect.rst:1-110Known-good/bad 사이를 build·test하고 log·config를 보존해 culprit를 검증합니다.