요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
세 가지 제출 방식
stable-kernel-rules.rst:34-64Security patch를 -stable 공개 review만으로 처리해서는 안 된다. security-bugs.rst의 비공개 보고와 disclosure 절차를 먼저 따른다.
| 방식 | 사용 시점 | 핵심 동작 |
|---|---|---|
| Option 1 | Mainline 제출 전 | Commit의 sign-off 영역에 stable Cc tag를 넣어 mainline merge 뒤 자동 선별되게 한다. |
| Option 2 | 이미 mainline에 merge됨 | Stable team에 commit ID, 적용 이유와 대상 version을 mail로 요청한다. |
| Option 3 | 이전 API에 맞춘 별도 backport가 필요함 | Upstream commit을 명시하고 조정한 patch를 stable team에 직접 보낸다. |
Option 1이 가장 쉽고 일반적이므로 강하게 권장된다. Option 2는 처음 제출할 때 backport를 고려하지 못한 변경에, Option 3은 API 차이 때문에 mainline patch를 그대로 cherry-pick할 수 없는 경우에 사용한다.
특정 stable series만 지정할 때는 그보다 새로운 지원 중 series 모두에 같은 fix가 적용 가능하거나 이미 들어가 있는지 확인한다. 예를 들어 5.10.y만 고치고 5.15.y를 빠뜨리면 사용자가 upgrade할 때 bug가 되살아나는 역방향 regression이 생긴다.
Option 1: mainline patch에 stable tag 넣기
stable-kernel-rules.rst:65-137Cc: [email protected]일반 bug fix는 위 tag를 sign-off 영역에 넣는다. Patch가 mainline에 merge되면 author나 subsystem maintainer가 별도 요청하지 않아도 stable team이 대상 tree에 적용한다.
Cc: [email protected]아직 공개되지 않은 취약점을 고칠 때는 이 주소를 사용한다. 이 주소로 보낸 mail은 어디에도 배달되지 않으므로 git send-email 과정에서 fix가 공개 mailing list로 잘못 노출될 위험을 줄인다.
Inline shell comment로 선행 commit, 적용 시작 version, 지연 시점과 알려진 조정 사항을 stable team에 전달할 수 있다. 선행 commit 목록은 적힌 순서대로 cherry-pick한 뒤 현재 commit을 적용하라는 의미다. 같은 patch series 안에서 이미 stable 표시한 앞 patch는 뒤 patch의 prerequisite로 다시 나열하지 않아도 된다.
Cc: <[email protected]> # 6.6.x
Cc: <[email protected]> # after -rc3
Cc: <[email protected]> # see patch description, needs adjustments for <= 6.3Fixes tag만으로 stable team이 대상 version을 계산할 수 있다면 version comment는 불필요하다. AUTOSEL과 Fixes tag 기반 자동 도구가 특정 변경을 고르지 않게 해야 한다면 반드시 이유를 붙여 [email protected] tag를 사용한다.
Option 2와 Option 3
stable-kernel-rules.rst:138-166Option 2에서는 mainline에 merge된 patch의 subject와 commit ID, stable에 필요한 이유, 적용할 kernel version을 [email protected]로 보낸다.
Option 3에서는 위 acceptance rule을 만족하는 backport patch 자체를 stable team에 보낸다. Changelog의 commit 설명 위에 upstream identity를 독립된 줄로 넣어 어느 mainline 변경과 동등한지 추적 가능하게 해야 한다.
commit <sha1> upstream.
[ Upstream commit <sha1> ]Old series의 API에 맞추느라 original upstream patch와 달라졌다면 바뀐 부분과 이유를 patch description에 명확히 기록한다. 단순히 'backport conflict 해결'이라고 쓰는 것으로는 동작 동등성을 review하기 어렵다.
제출 뒤 queue와 응답
stable-kernel-rules.rst:169-178Stable team이 patch를 queue에 받아들이면 ACK, 거절하면 NAK가 온다. Team 일정에 따라 며칠이 걸릴 수 있다. Accepted patch는 stable queue에 들어가 다른 개발자와 해당 subsystem maintainer의 review를 받는다.
48시간 review와 release candidate
stable-kernel-rules.rst:180-204- Review cycle이 시작되면 patch를 review committee, 영향 영역 maintainer와 linux-kernel mailing list에 보낸다.
- Review committee는 48시간 안에 ACK 또는 NAK한다.
- Committee 또는 mailing list에서 미처 발견하지 못한 문제가 제기되면 patch는 queue에서 빠진다.
- ACK된 patch는 stable release candidate의 일부로 다시 게시되어 개발자와 tester가 실행 검증한다.
- 보통 -rc는 한 번이지만 문제가 있으면 patch를 수정·제외·추가하고 더 많은 -rc를 낸다.
- Tester는 test 환경과 결과를 적은 Tested-by mail을 보내 release commit에 기록할 수 있다.
- 검토가 끝나면 queue에서 test를 통과한 patch를 포함한 새 stable release가 나온다.
- Kernel security team의 security patch는 일반 review cycle을 거치지 않고 stable tree로 직접 전달될 수 있다.
Stable 관련 repository
stable-kernel-rules.rst:207-235| Repository | 용도 |
|---|---|
| stable-queue.git | 완료된 version과 작업 중 version의 patch queue |
| linux.git | Version별 branch에 저장된 최종 tag stable release |
| linux-stable-rc.git | 각 stable version의 release-candidate snapshot |
linux-stable-rc는 stable-queue의 특정 시점 snapshot이며 자주 rebase된다. CI 같은 test 용도로만 사용하고 영구 branch나 개발 기반으로 삼지 않는다.
Review committee는 이 업무에 자원한 여러 kernel 개발자와, 문서의 표현을 빌리면 자원하지 않았지만 참여하게 된 일부 개발자로 구성된다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. _stable_kernel_rules:
Everything you ever wanted to know about Linux -stable releases
===============================================================
Rules on what kind of patches are accepted, and which ones are not, into the
"-stable" tree:
- It or an equivalent fix must already exist in Linux mainline (upstream).
- It must be obviously correct and tested.
- It cannot be bigger than 100 lines, with context.
- It must follow the
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
rules.
- It must either fix a real bug that bothers people or just add a device ID.
To elaborate on the former:
- It fixes a problem like an oops, a hang, data corruption, a real security
issue, a hardware quirk, a build error (but not for things marked
CONFIG_BROKEN), or some "oh, that's not good" issue.
- Serious issues as reported by a user of a distribution kernel may also
be considered if they fix a notable performance or interactivity issue.
As these fixes are not as obvious and have a higher risk of a subtle
regression they should only be submitted by a distribution kernel
maintainer and include an addendum linking to a bugzilla entry if it
exists and additional information on the user-visible impact.
- No "This could be a problem..." type of things like a "theoretical race
condition", unless an explanation of how the bug can be exploited is also
provided.
- No "trivial" fixes without benefit for users (spelling changes, whitespace
cleanups, etc).
Procedure for submitting patches to the -stable tree
----------------------------------------------------
.. note::
Security patches should not be handled (solely) by the -stable review
process but should follow the procedures in
:ref:`Documentation/process/security-bugs.rst <securitybugs>`.
There are three options to submit a change to -stable trees:
1. Add a 'stable tag' to the description of a patch you then submit for
mainline inclusion.
2. Ask the stable team to pick up a patch already mainlined.
3. Submit a patch to the stable team that is equivalent to a change already
mainlined.
The sections below describe each of the options in more detail.
:ref:`option_1` is **strongly** preferred, it is the easiest and most common.
:ref:`option_2` is mainly meant for changes where backporting was not considered
at the time of submission. :ref:`option_3` is an alternative to the two earlier
options for cases where a mainlined patch needs adjustments to apply in older
series (for example due to API changes).
When using option 2 or 3 you can ask for your change to be included in specific
stable series. When doing so, ensure the fix or an equivalent is applicable,
submitted, or already present in all newer stable trees still supported. This is
meant to prevent regressions that users might later encounter on updating, if
e.g. a fix merged for 5.19-rc1 would be backported to 5.10.y, but not to 5.15.y.
.. _option_1:
Option 1
********
To have a patch you submit for mainline inclusion later automatically picked up
for stable trees, add this tag in the sign-off area::
Cc: [email protected]
Use ``Cc: [email protected]`` instead when fixing unpublished vulnerabilities:
it reduces the chance of accidentally exposing the fix to the public by way of
'git send-email', as mails sent to that address are not delivered anywhere.
Once the patch is mainlined it will be applied to the stable tree without
anything else needing to be done by the author or subsystem maintainer.
To send additional instructions to the stable team, use a shell-style inline
comment to pass arbitrary or predefined notes:
* Specify any additional patch prerequisites for cherry picking::
Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <[email protected]> # 3.3.x
Signed-off-by: Ingo Molnar <[email protected]>
The tag sequence has the meaning of::
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
git cherry-pick <this commit>
Note that for a patch series, you do not have to list as prerequisites the
patches present in the series itself. For example, if you have the following
patch series::
patch1
patch2
where patch2 depends on patch1, you do not have to list patch1 as
prerequisite of patch2 if you have already marked patch1 for stable
inclusion.
* Point out kernel version prerequisites::
Cc: <[email protected]> # 3.3.x
The tag has the meaning of::
git cherry-pick <this commit>
For each "-stable" tree starting with the specified version.
Note, such tagging is unnecessary if the stable team can derive the
appropriate versions from Fixes: tags.
* Delay pick up of patches::
Cc: <[email protected]> # after -rc3
* Point out known problems::
Cc: <[email protected]> # see patch description, needs adjustments for <= 6.3
There furthermore is a variant of the stable tag you can use to make the stable
team's backporting tools (e.g AUTOSEL or scripts that look for commits
containing a 'Fixes:' tag) ignore a change::
Cc: <[email protected]> # reason goes here, and must be present
.. _option_2:
Option 2
********
If the patch already has been merged to mainline, send an email to
[email protected] containing the subject of the patch, the commit ID,
why you think it should be applied, and what kernel versions you wish it to
be applied to.
.. _option_3:
Option 3
********
Send the patch, after verifying that it follows the above rules, to
[email protected] and mention the kernel versions you wish it to be applied
to. When doing so, you must note the upstream commit ID in the changelog of your
submission with a separate line above the commit text, like this::
commit <sha1> upstream.
Or alternatively::
[ Upstream commit <sha1> ]
If the submitted patch deviates from the original upstream patch (for example
because it had to be adjusted for the older API), this must be very clearly
documented and justified in the patch description.
Following the submission
------------------------
The sender will receive an ACK when the patch has been accepted into the
queue, or a NAK if the patch is rejected. This response might take a few
days, according to the schedules of the stable team members.
If accepted, the patch will be added to the -stable queue, for review by other
developers and by the relevant subsystem maintainer.
Review cycle
------------
- When the -stable maintainers decide for a review cycle, the patches will be
sent to the review committee, and the maintainer of the affected area of
the patch (unless the submitter is the maintainer of the area) and CC: to
the linux-kernel mailing list.
- The review committee has 48 hours in which to ACK or NAK the patch.
- If the patch is rejected by a member of the committee, or linux-kernel
members object to the patch, bringing up issues that the maintainers and
members did not realize, the patch will be dropped from the queue.
- The ACKed patches will be posted again as part of release candidate (-rc)
to be tested by developers and testers.
- Usually only one -rc release is made, however if there are any outstanding
issues, some patches may be modified or dropped or additional patches may
be queued. Additional -rc releases are then released and tested until no
issues are found.
- Responding to the -rc releases can be done on the mailing list by sending
a "Tested-by:" email with any testing information desired. The "Tested-by:"
tags will be collected and added to the release commit.
- At the end of the review cycle, the new -stable release will be released
containing all the queued and tested patches.
- Security patches will be accepted into the -stable tree directly from the
security kernel team, and not go through the normal review cycle.
Contact the kernel security team for more details on this procedure.
Trees
-----
- The queues of patches, for both completed versions and in progress
versions can be found at:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
- The finalized and tagged releases of all stable kernels can be found
in separate branches per version at:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
- The release candidate of all stable kernel versions can be found at:
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
.. warning::
The -stable-rc tree is a snapshot in time of the stable-queue tree and
will change frequently, hence will be rebased often. It should only be
used for testing purposes (e.g. to be consumed by CI systems).
Review committee
----------------
- This is made up of a number of kernel developers who have volunteered for
this task, and a few that haven't.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
-stable tree가 받는 patch
1-31- 동일하거나 동등한 fix가 Linux mainline upstream에 이미 있어야 한다.
- 명백히 올바르고 test된 변경이어야 한다.
- Context를 포함해 100 line보다 크면 안 된다.
- Documentation/process/submitting-patches.rst의 제출 규칙을 따라야 한다.
- 실제 user가 겪는 bug를 고치거나 device ID만 추가하는 변경이어야 한다.
- Oops, hang, data corruption, 실제 security issue, hardware quirk, CONFIG_BROKEN 이외의 build error처럼 명백히 좋지 않은 문제를 고친다.
- Distribution kernel user가 보고한 뚜렷한 performance 또는 interactivity 문제도 고려할 수 있지만 subtle regression 위험이 높으므로 distribution kernel maintainer가 제출하고 bugzilla link와 user-visible impact를 덧붙여야 한다.
- 악용 또는 실제 발생 경로 설명이 없는 theoretical race처럼 '문제가 될 수 있다'는 추측만으로는 받지 않는다.
- Spelling과 whitespace cleanup처럼 user에게 이익이 없는 trivial fix는 받지 않는다.
-stable 제출의 세 방식
34-63Security patch는 -stable review만으로 처리하지 않고 Documentation/process/security-bugs.rst의 보안 절차를 따라야 한다.
- Option 1: mainline 제출 patch description에 stable tag를 추가한다. 가장 쉽고 흔하며 강하게 권장된다.
- Option 2: 이미 mainline에 merge된 patch를 stable team이 가져가도록 요청한다. 원 제출 때 backport를 고려하지 못한 경우에 주로 쓴다.
- Option 3: mainline change와 동등하지만 옛 series API에 맞게 조정한 patch를 stable team에 직접 보낸다.
Option 2 또는 3으로 특정 stable series만 지정할 때는 그 fix 또는 동등한 변경이 지원 중인 모든 더 최신 stable tree에도 적용 가능하거나 제출되었거나 이미 들어 있는지 확인한다. 예를 들어 5.10.y에 backport했지만 5.15.y에 빠져 user가 upgrade하면서 regression을 다시 만나는 상황을 막기 위해서다.
Option 1: mainline patch의 stable tag
65-80Cc: [email protected]
# unpublished vulnerability
Cc: [email protected]Mainline patch의 sign-off 영역에 Cc: [email protected]를 넣으면 mainline merge 뒤 stable tree가 자동으로 가져간다. 미공개 취약점 fix는 git send-email을 통해 공개될 위험을 줄이도록 실제 전달되지 않는 [email protected] 주소를 사용한다.
Cherry-pick prerequisite와 version 조건
82-122Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <[email protected]> # 3.3.x
Signed-off-by: Ingo Molnar <[email protected]>Shell-style inline comment로 stable team에 prerequisite 순서를 전달할 수 있다. 예시는 a1f84a3, 1b9508f, fd21073을 차례로 cherry-pick한 뒤 current commit을 적용하라는 뜻이다.
같은 patch series 안에서 stable 표시된 앞 patch에 뒤 patch가 의존한다면 prerequisite로 다시 나열할 필요가 없다.
Cc: <[email protected]> # 3.3.xVersion만 적으면 그 version부터 시작하는 각 stable tree에 current commit을 적용한다. Fixes: tag에서 version을 추론할 수 있으면 이 표기는 필요 없다.
지연, known issue, AUTOSEL 제외
124-137Cc: <[email protected]> # after -rc3
Cc: <[email protected]> # see patch description, needs adjustments for <= 6.3
Cc: <[email protected]> # reason goes here, and must be presentInline note로 -rc3 이후까지 pick을 미루거나 6.3 이하에 조정이 필요하다는 known issue를 알릴 수 있다. AUTOSEL이나 Fixes: scanner 같은 자동 backport tool이 change를 무시해야 한다면 stable+noautosel 주소를 쓰고 반드시 이유를 적는다.
Option 2: 이미 mainline인 patch 요청
138-146이미 mainline에 merge된 patch라면 [email protected]에 patch subject, commit ID, stable에 적용해야 하는 이유, 원하는 kernel version을 적어 email을 보낸다.
Option 3: 조정한 backport 제출
148-166앞의 규칙을 충족하는지 확인한 patch를 [email protected]에 보내고 적용할 kernel version을 명시한다. Changelog의 commit text 위에 upstream commit ID를 별도 line으로 기록한다.
commit <sha1> upstream.
# or
[ Upstream commit <sha1> ]옛 API에 맞추기 위해 original upstream patch와 달라졌다면 차이를 patch description에 매우 명확하게 기록하고 정당화한다.
제출 이후 ACK와 queue
169-177Patch가 queue에 accept되면 ACK, reject되면 NAK를 받는다. Stable team 일정에 따라 며칠 걸릴 수 있다. Accept된 patch는 다른 developer와 관련 subsystem maintainer가 review하는 stable queue에 들어간다.
48시간 review cycle과 release candidate
180-204- Stable maintainer가 review cycle을 시작하면 patch를 review committee, 영향받는 영역 maintainer, linux-kernel mailing list에 보낸다. Submitter가 해당 maintainer면 별도 maintainer 전달은 생략한다.
- Review committee는 48시간 안에 ACK 또는 NAK한다.
- Committee member가 reject하거나 linux-kernel 구성원이 새 문제를 제기하면 patch를 queue에서 제거한다.
- ACK된 patch는 -rc release로 다시 게시해 developer와 tester가 시험한다.
- 보통 -rc 하나지만 문제가 남으면 patch를 수정·제거하거나 추가 patch를 넣고 문제가 없어질 때까지 새 -rc를 시험한다.
- Test 결과는 mailing list에 Tested-by: email로 보낼 수 있고 tag는 release commit에 모인다.
- Cycle 끝에 queue의 test된 patch 전체를 포함한 새 stable release를 배포한다.
- Security kernel team이 보낸 security patch는 일반 review cycle을 거치지 않고 stable tree에 직접 accept된다.
Stable queue와 release repository
207-227- 완료 및 진행 중 patch queue
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git - Version별 finalized tagged stable release
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git - Stable release candidate
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
linux-stable-rc tree는 stable-queue의 특정 시점 snapshot이며 자주 바뀌고 rebase된다. CI를 포함한 시험 목적으로만 사용한다.
Review committee
230-234Review committee는 이 작업에 자원한 여러 kernel developer와 자원하지 않았지만 참여하게 된 일부 developer로 구성된다.
Stable tree가 받는 patch
stable-kernel-rules.rst:3-31Stable tree는 새 기능을 개발하는 곳이 아니라 이미 mainline에서 검증된 실제 bug fix를 지원 중인 이전 kernel series에 옮기는 곳이다. 따라서 같은 fix 또는 동등한 fix가 먼저 upstream mainline에 존재해야 한다.
Distribution kernel 사용자가 보고한 심각한 performance 또는 interactivity regression도 고려할 수 있다. 다만 이런 변경은 정답이 덜 명백하고 미세한 regression 위험이 높으므로 distribution kernel maintainer가 제출해야 하며, bug tracker와 사용자에게 보이는 영향을 추가로 설명해야 한다.