요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
문제, 사용자 영향과 trade-off를 먼저 설명한다
submitting-patches.rst:45-164Commit message 첫 문단은 code를 어떻게 바꿨는지가 아니라 왜 읽을 가치가 있는 문제인지 설명한다. Crash, lockup, dmesg, 재현 조건, performance regression과 latency spike처럼 downstream maintainer가 영향받는 product tree를 판단할 정보도 포함한다.
Performance, memory, stack와 binary-size 개선을 주장하면 측정 수치를 제시한다. CPU를 줄이는 대신 memory를 늘리거나 특정 workload를 개선하면서 다른 workload를 악화시키는 non-obvious cost도 함께 밝힌다.
그 뒤 실제 변경과 그것이 문제를 해결하는 원리를 plain language로 설명한다. Resend할 때도 이전 mail이나 URL에 설명을 맡기지 말고 각 version을 self-contained하게 유지하며 imperative mood를 사용한다.
- Commit을 언급할 때 최소 12자리 hash와 정확한 one-line subject를 함께 쓴다.
- Mail discussion은 lore.kernel.org의 Message-ID link를 사용하고 실제로 열리는지 확인한다.
- 외부 Link가 있어도 핵심 결론과 근거는 commit message 안에 요약한다.
- Public bug를 완전히 고치면 Closes: URL을 사용한다. Private tracker와 invalid URL은 허용되지 않는다.
- 특정 commit이 bug를 도입했다면 한 줄의 Fixes: <12+ hash> ("subject") tag를 쓴다.
Patch 하나에는 logical change 하나만 둔다
submitting-patches.rst:168-198Bug fix와 performance 개선, API 추가와 그 API를 쓰는 driver처럼 독립적으로 판단할 수 있는 변경은 분리한다. 반대로 하나의 논리 변경이 여러 file을 건드리면 한 patch에 함께 둔다.
Series의 모든 중간 commit에서 kernel이 build되고 정상 동작해야 한다. git bisect는 series 중간 어느 지점에서도 멈출 수 있다. Dependency가 있으면 description에 명시하고 너무 큰 series는 약 15편씩 나눠 review와 integration을 기다린다.
Style check와 code 이동 분리
submitting-patches.rst:201-228scripts/checkpatch.pl의 ERROR, WARNING, CHECK를 확인하되 human judgment를 대신하게 하지는 않는다. 남겨 둔 violation은 이유를 설명할 수 있어야 한다.
Code를 다른 file로 옮기는 patch에서는 옮기는 code를 동시에 정리하지 않는다. Move와 semantic edit를 분리해야 reviewer와 history tracking 도구가 실제 차이를 정확히 볼 수 있다.
MAINTAINERS와 history로 recipient를 고른다
submitting-patches.rst:231-275MAINTAINERS와 file history를 확인하고 scripts/get_maintainer.pl에 patch path를 넘겨 subsystem maintainer와 list를 찾는다. linux-kernel은 기본 공개 list지만 관련 없는 사람과 list를 대량 Cc하지 않는다. 일반 patch를 Linus에게 직접 보내는 경우는 드물다.
- Exploitable security bug는 public list가 아니라 [email protected] 절차를 따른다.
- Released kernel의 severe bug fix는 sign-off 영역에 Cc: [email protected]를 넣고 stable rule을 확인한다.
- Userspace-kernel interface 변경은 linux-api와 man-pages maintainer에게 알리고 man page patch를 준비한다.
Patch는 inline plain text로 보낸다
submitting-patches.rst:278-308Reviewer가 code 일부를 그대로 quote할 수 있도록 git send-email로 mail body에 inline 전송한다. MIME attachment, compressed attachment와 web link만 보내는 방식은 patch review와 자동 적용을 방해한다.
Mailer가 patch를 손상한다면 먼저 email-clients.rst 설정을 고친다. Word wrapping, format=flowed, tab 변환과 charset 변환을 자신에게 보내는 test로 확인한다. MIME 재전송은 reviewer가 특별히 요청했을 때의 예외다.
Review에 답하고 새 version의 차이를 기록한다
submitting-patches.rst:310-382모든 review comment에 답한다. Code 변경으로 이어지지 않은 질문도 다음 reviewer가 같은 의문을 반복하지 않도록 source comment나 changelog 설명으로 반영할 수 있다. 새 version에서는 cover letter 또는 각 patch의 version changelog에 이전 version과의 차이를 적고 이전 reviewer를 Cc한다.
Reply는 필요한 인용문 바로 아래에 답하는 trimmed interleaved 형식을 쓴다. Top-posting과 관련 없는 긴 quotation은 discussion 흐름을 흐린다.
최소 1주일은 기다린 뒤 ping하고, 보통 2~3주 동안 답이 없으면 recipient를 다시 확인해 동일 patch를 RESEND로 보낼 수 있다. Code가 바뀐 새 version에는 RESEND를 붙이지 않고 v2, v3를 사용한다.
Developer's Certificate of Origin과 sign-off
submitting-patches.rst:385-454Subject에는 [PATCH]를 넣는다. Signed-off-by는 contributor가 자신이 만들 권리가 있는 code이거나 적절한 open-source license 아래 받은 code를 제출할 권리가 있고, contribution과 identity가 공개·영구 보존될 수 있음을 인증하는 DCO 1.1 표시다.
Signed-off-by: Real Name <[email protected]>
git commit -s
git revert -s <commit>Anonymous contribution은 받지 않는다. 첫 SoB는 primary author를 나타내고 뒤 SoB chain은 patch를 실제로 전달한 경로를 시간 순서대로 반영한다. 단순히 내부 승인자를 모두 나열하는 명단이 아니다.
Acked-by, Co-developed-by와 review tag
submitting-patches.rst:456-634| Tag | 의미 |
|---|---|
| Acked-by | 영향 code의 maintainer나 stakeholder가 방향과 적용을 받아들인다. Reviewed-by보다 약한 기술 검토일 수 있고 담당 범위에만 적용될 수 있다. |
| Co-developed-by | 공동 저자를 표시한다. 바로 다음 줄에 같은 사람의 Signed-off-by가 반드시 온다. |
| Reported-by | Bug를 발견·보고한 사람에게 credit을 준다. 보통 public report의 Closes 또는 부분 fix의 Link가 뒤따른다. |
| Tested-by | 표시된 사람이 특정 환경에서 patch를 성공적으로 test했다. |
| Reviewed-by | Mainline 포함 적합성을 기술적으로 검토했고 제기한 문제에 대한 답을 받아 심각한 잔여 문제가 없다고 판단했다. |
| Suggested-by | Patch idea를 제안한 사람에게 credit을 준다. |
| Fixes | Bug를 도입한 commit을 추적하고 stable 대상 version 판단을 돕는다. Stable Cc 요구를 대신하지는 않는다. |
Tested-by와 Reviewed-by는 새 version의 변경이 작아 검증이 여전히 유효할 때 유지한다. 크게 바뀌었다면 제거하고 version changelog에 이유를 적는다.
Cc, Reported-by, Suggested-by를 제외한 사람 tag는 명시적 허락이 필요하다. 세 예외도 해당 identity가 public lore 또는 commit history에 사용됐고 report·suggestion이 공개된 경우에만 묵시적 허락을 인정한다. Public Bugzilla의 비공개 email을 임의로 노출해서는 안 된다.
Canonical patch message 구조
submitting-patches.rst:638-820Subject: [PATCH v2 01/04] subsystem: concise summary
From: Patch Author <[email protected]> # sender와 author가 다를 때
<75-column commit message: 문제, 영향, 해결 원리>
Signed-off-by: Patch Author <[email protected]>
---
<v1 -> v2 변경 사항과 reviewer용 메모>
<diffstat>
<actual diff>Subject의 subsystem은 영향 영역을, summary는 file 이름이 아니라 무엇을 왜 바꾸는지를 70~75 character 안에 표현한다. Series는 1/4처럼 zero-padded order를 쓰고 RFC와 v2 같은 처리 tag를 [PATCH ...] 안에 둔다.
Explanation은 수개월·수년 뒤 discussion 없이 읽어도 patch 이유를 이해할 수 있어야 한다. Backtrace는 timestamp, register dump와 module list를 전부 붙이지 말고 실제 failure call chain만 남긴다.
--- 아래는 permanent commit log에 들어가지 않는 reviewer용 영역이다. Version별 변경, temporary note와 diffstat을 이곳에 둔다. Patch 적용 도구가 이 영역을 자동으로 제거한다.
Thread와 base-commit 정보
submitting-patches.rst:824-894관련 bug report에 In-Reply-To를 걸 수 있지만 multi-patch series의 새 version을 모두 이전 series thread 아래 연결하면 reference tree가 복잡해진다. 이전 version은 cover letter의 lore link로 연결하는 편이 낫다.
git checkout -t -b my-topical-branch master
# commits...
git format-patch --base=auto --cover-letter -o outgoing/ masterCover letter의 base-commit trailer는 reviewer와 CI가 정확한 tree에서 git am하도록 한다. Base는 외부에서 접근 가능한 official mainline 또는 maintainer tree commit이어야 하며 개인 내부 repository hash는 의미가 없다.
b4로 반복 작업 자동화
submitting-patches.rst:896-902b4는 dependency 추적, checkpatch, patch formatting과 mail 전송 같은 기술 작업을 자동화할 수 있다. 자동화가 problem statement, test 근거와 review 판단을 대신하지는 않지만 message thread와 attestation을 일관되게 관리하는 데 유용하다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. _submittingpatches:
Submitting patches: the essential guide to getting your code into the kernel
============================================================================
For a person or company who wishes to submit a change to the Linux
kernel, the process can sometimes be daunting if you're not familiar
with "the system." This text is a collection of suggestions which
can greatly increase the chances of your change being accepted.
This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process
works, see Documentation/process/development-process.rst. Also, read
Documentation/process/submit-checklist.rst
for a list of items to check before submitting code.
For device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.rst.
This documentation assumes that you're using ``git`` to prepare your patches.
If you're unfamiliar with ``git``, you would be well-advised to learn how to
use it, it will make your life as a kernel developer and in general much
easier.
Some subsystems and maintainer trees have additional information about
their workflow and expectations, see
:ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`.
Obtain a current source tree
----------------------------
If you do not have a repository with the current kernel source handy, use
``git`` to obtain one. You'll want to start with the mainline repository,
which can be grabbed with::
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Note, however, that you may not want to develop against the mainline tree
directly. Most subsystem maintainers run their own trees and want to see
patches prepared against those trees. See the **T:** entry for the subsystem
in the MAINTAINERS file to find that tree, or simply ask the maintainer if
the tree is not listed there.
.. _describe_changes:
Describe your changes
---------------------
Describe your problem. Whether your patch is a one-line bug fix or
5000 lines of a new feature, there must be an underlying problem that
motivated you to do this work. Convince the reviewer that there is a
problem worth fixing and that it makes sense for them to read past the
first paragraph.
Describe user-visible impact. Straight up crashes and lockups are
pretty convincing, but not all bugs are that blatant. Even if the
problem was spotted during code review, describe the impact you think
it can have on users. Keep in mind that the majority of Linux
installations run kernels from secondary stable trees or
vendor/product-specific trees that cherry-pick only specific patches
from upstream, so include anything that could help route your change
downstream: provoking circumstances, excerpts from dmesg, crash
descriptions, performance regressions, latency spikes, lockups, etc.
Quantify optimizations and trade-offs. If you claim improvements in
performance, memory consumption, stack footprint, or binary size,
include numbers that back them up. But also describe non-obvious
costs. Optimizations usually aren't free but trade-offs between CPU,
memory, and readability; or, when it comes to heuristics, between
different workloads. Describe the expected downsides of your
optimization so that the reviewer can weigh costs against benefits.
Once the problem is established, describe what you are actually doing
about it in technical detail. It's important to describe the change
in plain English for the reviewer to verify that the code is behaving
as you intend it to.
The maintainer will thank you if you write your patch description in a
form which can be easily pulled into Linux's source code management
system, ``git``, as a "commit log". See :ref:`the_canonical_patch_format`.
Solve only one problem per patch. If your description starts to get
long, that's a sign that you probably need to split up your patch.
See :ref:`split_changes`.
When you submit or resubmit a patch or patch series, include the
complete patch description and justification for it. Don't just
say that this is version N of the patch (series). Don't expect the
subsystem maintainer to refer back to earlier patch versions or referenced
URLs to find the patch description and put that into the patch.
I.e., the patch (series) and its description should be self-contained.
This benefits both the maintainers and reviewers. Some reviewers
probably didn't even receive earlier versions of the patch.
Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
to do frotz", as if you are giving orders to the codebase to change
its behaviour.
If you want to refer to a specific commit, don't just refer to the
SHA-1 ID of the commit. Please also include the oneline summary of
the commit, to make it easier for reviewers to know what it is about.
Example::
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.
You should also be sure to use at least the first twelve characters of the
SHA-1 ID. The kernel repository holds a *lot* of objects, making
collisions with shorter IDs a real possibility. Bear in mind that, even if
there is no collision with your six-character ID now, that condition may
change five years from now.
If related discussions or any other background information behind the change
can be found on the web, add 'Link:' tags pointing to it. If the patch is a
result of some earlier mailing list discussions or something documented on the
web, point to it.
When linking to mailing list archives, preferably use the lore.kernel.org
message archiver service. To create the link URL, use the contents of the
``Message-ID`` header of the message without the surrounding angle brackets.
For example::
Link: https://lore.kernel.org/[email protected]
Please check the link to make sure that it is actually working and points
to the relevant message.
However, try to make your explanation understandable without external
resources. In addition to giving a URL to a mailing list archive or bug,
summarize the relevant points of the discussion that led to the
patch as submitted.
In case your patch fixes a bug, use the 'Closes:' tag with a URL referencing
the report in the mailing list archives or a public bug tracker. For example::
Closes: https://example.com/issues/1234
Some bug trackers have the ability to close issues automatically when a
commit with such a tag is applied. Some bots monitoring mailing lists can
also track such tags and take certain actions. Private bug trackers and
invalid URLs are forbidden.
If your patch fixes a bug in a specific commit, e.g. you found an issue using
``git bisect``, please use the 'Fixes:' tag with at least the first 12
characters of the SHA-1 ID, and the one line summary. Do not split the tag
across multiple lines, tags are exempt from the "wrap at 75 columns" rule in
order to simplify parsing scripts. For example::
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
The following ``git config`` settings can be used to add a pretty format for
outputting the above style in the ``git log`` or ``git show`` commands::
[core]
abbrev = 12
[pretty]
fixes = Fixes: %h (\"%s\")
An example call::
$ git log -1 --pretty=fixes 54a4f0239f2e
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
.. _split_changes:
Separate your changes
---------------------
Separate each **logical change** into a separate patch.
For example, if your changes include both bug fixes and performance
enhancements for a single driver, separate those changes into two
or more patches. If your changes include an API update, and a new
driver which uses that new API, separate those into two patches.
On the other hand, if you make a single change to numerous files,
group those changes into a single patch. Thus a single logical change
is contained within a single patch.
The point to remember is that each patch should make an easily understood
change that can be verified by reviewers. Each patch should be justifiable
on its own merits.
If one patch depends on another patch in order for a change to be
complete, that is OK. Simply note **"this patch depends on patch X"**
in your patch description.
When dividing your change into a series of patches, take special care to
ensure that the kernel builds and runs properly after each patch in the
series. Developers using ``git bisect`` to track down a problem can end up
splitting your patch series at any point; they will not thank you if you
introduce bugs in the middle.
If you cannot condense your patch set into a smaller set of patches,
then only post say 15 or so at a time and wait for review and integration.
Style-check your changes
------------------------
Check your patch for basic style violations, details of which can be
found in Documentation/process/coding-style.rst.
Failure to do so simply wastes
the reviewers time and will get your patch rejected, probably
without even being read.
One significant exception is when moving code from one file to
another -- in this case you should not modify the moved code at all in
the same patch which moves it. This clearly delineates the act of
moving the code and your changes. This greatly aids review of the
actual differences and allows tools to better track the history of
the code itself.
Check your patches with the patch style checker prior to submission
(scripts/checkpatch.pl). Note, though, that the style checker should be
viewed as a guide, not as a replacement for human judgment. If your code
looks better with a violation then its probably best left alone.
The checker reports at three levels:
- ERROR: things that are very likely to be wrong
- WARNING: things requiring careful review
- CHECK: things requiring thought
You should be able to justify all violations that remain in your
patch.
Select the recipients for your patch
------------------------------------
You should always copy the appropriate subsystem maintainer(s) and list(s) on
any patch to code that they maintain; look through the MAINTAINERS file and the
source code revision history to see who those maintainers are. The script
scripts/get_maintainer.pl can be very useful at this step (pass paths to your
patches as arguments to scripts/get_maintainer.pl). If you cannot find a
maintainer for the subsystem you are working on, Andrew Morton
([email protected]) serves as a maintainer of last resort.
[email protected] should be used by default for all patches, but the
volume on that list has caused a number of developers to tune it out. Please
do not spam unrelated lists and unrelated people, though.
Many kernel-related lists are hosted at kernel.org; you can find a list
of them at https://subspace.kernel.org. There are kernel-related lists
hosted elsewhere as well, though.
Linus Torvalds is the final arbiter of all changes accepted into the
Linux kernel. His e-mail address is <[email protected]>.
He gets a lot of e-mail, and, at this point, very few patches go through
Linus directly, so typically you should do your best to -avoid-
sending him e-mail.
If you have a patch that fixes an exploitable security bug, send that patch
to [email protected]. For severe bugs, a short embargo may be considered
to allow distributors to get the patch out to users; in such cases,
obviously, the patch should not be sent to any public lists. See also
Documentation/process/security-bugs.rst.
Patches that fix a severe bug in a released kernel should be directed
toward the stable maintainers by putting a line like this::
Cc: [email protected]
into the sign-off area of your patch (note, NOT an email recipient). You
should also read Documentation/process/stable-kernel-rules.rst
in addition to this document.
If changes affect userland-kernel interfaces, please send the MAN-PAGES
maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
least a notification of the change, so that some information makes its way
into the manual pages. User-space API changes should also be copied to
No MIME, no links, no compression, no attachments. Just plain text
-------------------------------------------------------------------
Linus and other kernel developers need to be able to read and comment
on the changes you are submitting. It is important for a kernel
developer to be able to "quote" your changes, using standard e-mail
tools, so that they may comment on specific portions of your code.
For this reason, all patches should be submitted by e-mail "inline". The
easiest way to do this is with ``git send-email``, which is strongly
recommended. An interactive tutorial for ``git send-email`` is available at
https://git-send-email.io.
If you choose not to use ``git send-email``:
.. warning::
Be wary of your editor's word-wrap corrupting your patch,
if you choose to cut-n-paste your patch.
Do not attach the patch as a MIME attachment, compressed or not.
Many popular e-mail applications will not always transmit a MIME
attachment as plain text, making it impossible to comment on your
code. A MIME attachment also takes Linus a bit more time to process,
decreasing the likelihood of your MIME-attached change being accepted.
Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME.
See Documentation/process/email-clients.rst for hints about configuring
your e-mail client so that it sends your patches untouched.
Respond to review comments
--------------------------
Your patch will almost certainly get comments from reviewers on ways in
which the patch can be improved, in the form of a reply to your email. You must
respond to those comments; ignoring reviewers is a good way to get ignored in
return. You can simply reply to their emails to answer their comments. Review
comments or questions that do not lead to a code change should almost certainly
bring about a comment or changelog entry so that the next reviewer better
understands what is going on.
Be sure to tell the reviewers what changes you are making and to thank them
for their time. Code review is a tiring and time-consuming process, and
reviewers sometimes get grumpy. Even in that case, though, respond
politely and address the problems they have pointed out. When sending a next
version, add a ``patch changelog`` to the cover letter or to individual patches
explaining difference against previous submission (see
:ref:`the_canonical_patch_format`).
Notify people that commented on your patch about new versions by adding them to
the patches CC list.
See Documentation/process/email-clients.rst for recommendations on email
clients and mailing list etiquette.
.. _interleaved_replies:
Use trimmed interleaved replies in email discussions
----------------------------------------------------
Top-posting is strongly discouraged in Linux kernel development
discussions. Interleaved (or "inline") replies make conversations much
easier to follow. For more details see:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
As is frequently quoted on the mailing list::
A: http://en.wikipedia.org/wiki/Top_post
Q: Where do I find info about this thing called top-posting?
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?
Similarly, please trim all unneeded quotations that aren't relevant
to your reply. This makes responses easier to find, and saves time and
space. For more details see: http://daringfireball.net/2007/07/on_top ::
A: No.
Q: Should I include quotations after my reply?
.. _resend_reminders:
Don't get discouraged - or impatient
------------------------------------
After you have submitted your change, be patient and wait. Reviewers are
busy people and may not get to your patch right away.
Once upon a time, patches used to disappear into the void without comment,
but the development process works more smoothly than that now. You should
receive comments within a few weeks (typically 2-3); if that does not
happen, make sure that you have sent your patches to the right place.
Wait for a minimum of one week before resubmitting or pinging reviewers
- possibly longer during busy times like merge windows.
It's also ok to resend the patch or the patch series after a couple of
weeks with the word "RESEND" added to the subject line::
[PATCH Vx RESEND] sub/sys: Condensed patch summary
Don't add "RESEND" when you are submitting a modified version of your
patch or patch series - "RESEND" only applies to resubmission of a
patch or patch series which have not been modified in any way from the
previous submission.
Include PATCH in the subject
-----------------------------
Due to high e-mail traffic to Linus, and to linux-kernel, it is common
convention to prefix your subject line with [PATCH]. This lets Linus
and other kernel developers more easily distinguish patches from other
e-mail discussions.
``git send-email`` will do this for you automatically.
Sign your work - the Developer's Certificate of Origin
------------------------------------------------------
To improve tracking of who did what, especially with patches that can
percolate to their final resting place in the kernel through several
layers of maintainers, we've introduced a "sign-off" procedure on
patches that are being emailed around.
The sign-off is a simple line at the end of the explanation for the
patch, which certifies that you wrote it or otherwise have the right to
pass it on as an open-source patch. The rules are pretty simple: if you
can certify the below:
Developer's Certificate of Origin 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line saying::
Signed-off-by: Random J Developer <[email protected]>
using a known identity (sorry, no anonymous contributions.)
This will be done for you automatically if you use ``git commit -s``.
Reverts should also include "Signed-off-by". ``git revert -s`` does that
for you.
Some people also put extra tags at the end. They'll just be ignored for
now, but you can do this to mark internal company procedures or just
point out some special detail about the sign-off.
Any further SoBs (Signed-off-by:'s) following the author's SoB are from
people handling and transporting the patch, but were not involved in its
development. SoB chains should reflect the **real** route a patch took
as it was propagated to the maintainers and ultimately to Linus, with
the first SoB entry signalling primary authorship of a single author.
When to use Acked-by:, Cc:, and Co-developed-by:
------------------------------------------------
The Signed-off-by: tag indicates that the signer was involved in the
development of the patch, or that he/she was in the patch's delivery path.
If a person was not directly involved in the preparation or handling of a
patch but wishes to signify and record their approval of it then they can
ask to have an Acked-by: line added to the patch's changelog.
Acked-by: is meant to be used by those responsible for or involved with the
affected code in one way or another. Most commonly, the maintainer when that
maintainer neither contributed to nor forwarded the patch.
Acked-by: may also be used by other stakeholders, such as people with domain
knowledge (e.g. the original author of the code being modified), userspace-side
reviewers for a kernel uAPI patch or key users of a feature. Optionally, in
these cases, it can be useful to add a "# Suffix" to clarify its meaning::
Acked-by: The Stakeholder <[email protected]> # As primary user
Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
has at least reviewed the patch and has indicated acceptance. Hence patch
mergers will sometimes manually convert an acker's "yep, looks good to me"
into an Acked-by: (but note that it is usually better to ask for an
explicit ack).
Acked-by: is also less formal than Reviewed-by:. For instance, maintainers may
use it to signify that they are OK with a patch landing, but they may not have
reviewed it as thoroughly as if a Reviewed-by: was provided. Similarly, a key
user may not have carried out a technical review of the patch, yet they may be
satisfied with the general approach, the feature or the user-facing interface.
Acked-by: does not necessarily indicate acknowledgement of the entire patch.
For example, if a patch affects multiple subsystems and has an Acked-by: from
one subsystem maintainer then this usually indicates acknowledgement of just
the part which affects that maintainer's code. Judgement should be used here.
When in doubt people should refer to the original discussion in the mailing
list archives. A "# Suffix" may also be used in this case to clarify.
If a person has had the opportunity to comment on a patch, but has not
provided such comments, you may optionally add a ``Cc:`` tag to the patch.
This tag documents that potentially interested parties have been included in
the discussion. Note, this is one of only three tags you might be able to use
without explicit permission of the person named (see 'Tagging people requires
permission' below for details).
Co-developed-by: states that the patch was co-created by multiple developers;
it is used to give attribution to co-authors (in addition to the author
attributed by the From: tag) when several people work on a single patch. Since
Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
followed by a Signed-off-by: of the associated co-author. Standard sign-off
procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
chronological history of the patch insofar as possible, regardless of whether
the author is attributed via From: or Co-developed-by:. Notably, the last
Signed-off-by: must always be that of the developer submitting the patch.
Note, the From: tag is optional when the From: author is also the person (and
email) listed in the From: line of the email header.
Example of a patch submitted by the From: author::
<changelog>
Co-developed-by: First Co-Author <[email protected]>
Signed-off-by: First Co-Author <[email protected]>
Co-developed-by: Second Co-Author <[email protected]>
Signed-off-by: Second Co-Author <[email protected]>
Signed-off-by: From Author <[email protected]>
Example of a patch submitted by a Co-developed-by: author::
From: From Author <[email protected]>
<changelog>
Co-developed-by: Random Co-Author <[email protected]>
Signed-off-by: Random Co-Author <[email protected]>
Signed-off-by: From Author <[email protected]>
Co-developed-by: Submitting Co-Author <[email protected]>
Signed-off-by: Submitting Co-Author <[email protected]>
Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
----------------------------------------------------------------------
The Reported-by tag gives credit to people who find bugs and report them and it
hopefully inspires them to help us again in the future. The tag is intended for
bugs; please do not use it to credit feature requests. The tag should be
followed by a Closes: tag pointing to the report, unless the report is not
available on the web. The Link: tag can be used instead of Closes: if the patch
fixes a part of the issue(s) being reported. Note, the Reported-by tag is one
of only three tags you might be able to use without explicit permission of the
person named (see 'Tagging people requires permission' below for details).
A Tested-by: tag indicates that the patch has been successfully tested (in
some environment) by the person named. This tag informs maintainers that
some testing has been performed, provides a means to locate testers for
future patches, and ensures credit for the testers.
Reviewed-by:, instead, indicates that the patch has been reviewed and found
acceptable according to the Reviewer's Statement:
Reviewer's statement of oversight
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By offering my Reviewed-by: tag, I state that:
(a) I have carried out a technical review of this patch to
evaluate its appropriateness and readiness for inclusion into
the mainline kernel.
(b) Any problems, concerns, or questions relating to the patch
have been communicated back to the submitter. I am satisfied
with the submitter's response to my comments.
(c) While there may be things that could be improved with this
submission, I believe that it is, at this time, (1) a
worthwhile modification to the kernel, and (2) free of known
issues which would argue against its inclusion.
(d) While I have reviewed the patch and believe it to be sound, I
do not (unless explicitly stated elsewhere) make any
warranties or guarantees that it will achieve its stated
purpose or function properly in any given situation.
A Reviewed-by tag is a statement of opinion that the patch is an
appropriate modification of the kernel without any remaining serious
technical issues. Any interested reviewer (who has done the work) can
offer a Reviewed-by tag for a patch. This tag serves to give credit to
reviewers and to inform maintainers of the degree of review which has been
done on the patch. Reviewed-by: tags, when supplied by reviewers known to
understand the subject area and to perform thorough reviews, will normally
increase the likelihood of your patch getting into the kernel.
Both Tested-by and Reviewed-by tags, once received on mailing list from tester
or reviewer, should be added by author to the applicable patches when sending
next versions. However if the patch has changed substantially in following
version, these tags might not be applicable anymore and thus should be removed.
Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned
in the patch changelog (after the '---' separator).
A Suggested-by: tag indicates that the patch idea is suggested by the person
named and ensures credit to the person for the idea: if we diligently credit
our idea reporters, they will, hopefully, be inspired to help us again in the
future. Note, this is one of only three tags you might be able to use without
explicit permission of the person named (see 'Tagging people requires
permission' below for details).
A Fixes: tag indicates that the patch fixes a bug in a previous commit. It
is used to make it easy to determine where an issue originated, which can help
review a bug fix. This tag also assists the stable kernel team in determining
which stable kernel versions should receive your fix. This is the preferred
method for indicating a bug fixed by the patch. See :ref:`describe_changes`
for more details.
Note: Attaching a Fixes: tag does not subvert the stable kernel rules
process nor the requirement to Cc: [email protected] on all stable
patch candidates. For more information, please read
Documentation/process/stable-kernel-rules.rst.
Finally, while providing tags is welcome and typically very appreciated, please
note that signers (i.e. submitters and maintainers) may use their discretion in
applying offered tags.
.. _tagging_people:
Tagging people requires permission
----------------------------------
Be careful in the addition of the aforementioned tags to your patches, as all
except for Cc:, Reported-by:, and Suggested-by: need explicit permission of the
person named. For those three implicit permission is sufficient if the person
contributed to the Linux kernel using that name and email address according
to the lore archives or the commit history -- and in case of Reported-by:
and Suggested-by: did the reporting or suggestion in public. Note,
bugzilla.kernel.org is a public place in this sense, but email addresses
used there are private; so do not expose them in tags, unless the person
used them in earlier contributions.
.. _the_canonical_patch_format:
The canonical patch format
--------------------------
This section describes how the patch itself should be formatted. Note
that, if you have your patches stored in a ``git`` repository, proper patch
formatting can be had with ``git format-patch``. The tools cannot create
the necessary text, though, so read the instructions below anyway.
Subject Line
^^^^^^^^^^^^
The canonical patch subject line is::
Subject: [PATCH 001/123] subsystem: summary phrase
The canonical patch message body contains the following:
- A ``from`` line specifying the patch author, followed by an empty
line (only needed if the person sending the patch is not the author).
- The body of the explanation, line wrapped at 75 columns, which will
be copied to the permanent changelog to describe this patch.
- An empty line.
- The ``Signed-off-by:`` lines, described above, which will
also go in the changelog.
- A marker line containing simply ``---``.
- Any additional comments not suitable for the changelog.
- The actual patch (``diff`` output).
The Subject line format makes it very easy to sort the emails
alphabetically by subject line - pretty much any email reader will
support that - since because the sequence number is zero-padded,
the numerical and alphabetic sort is the same.
The ``subsystem`` in the email's Subject should identify which
area or subsystem of the kernel is being patched.
The ``summary phrase`` in the email's Subject should concisely
describe the patch which that email contains. The ``summary
phrase`` should not be a filename. Do not use the same ``summary
phrase`` for every patch in a whole patch series (where a ``patch
series`` is an ordered sequence of multiple, related patches).
Bear in mind that the ``summary phrase`` of your email becomes a
globally-unique identifier for that patch. It propagates all the way
into the ``git`` changelog. The ``summary phrase`` may later be used in
developer discussions which refer to the patch. People will want to
google for the ``summary phrase`` to read discussion regarding that
patch. It will also be the only thing that people may quickly see
when, two or three months later, they are going through perhaps
thousands of patches using tools such as ``gitk`` or ``git log
--oneline``.
For these reasons, the ``summary`` must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary. It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.
The ``summary phrase`` may be prefixed by tags enclosed in square
brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
not considered part of the summary phrase, but describe how the patch
should be treated. Common tags might include a version descriptor if
the multiple versions of the patch have been sent out in response to
comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
comments.
If there are four patches in a patch series the individual patches may
be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers
understand the order in which the patches should be applied and that
they have reviewed or applied all of the patches in the patch series.
Here are some good example Subjects::
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCH v2 01/27] x86: fix eflags tracking
Subject: [PATCH v2] sub/sys: Condensed patch summary
Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
From Line
^^^^^^^^^
The ``from`` line must be the very first line in the message body,
and has the form:
From: Patch Author <[email protected]>
The ``from`` line specifies who will be credited as the author of the
patch in the permanent changelog. If the ``from`` line is missing,
then the ``From:`` line from the email header will be used to determine
the patch author in the changelog.
The author may indicate their affiliation or the sponsor of the work
by adding the name of an organization to the ``from`` and ``SoB`` lines,
e.g.:
From: Patch Author (Company) <[email protected]>
Explanation Body
^^^^^^^^^^^^^^^^
The explanation body will be committed to the permanent source
changelog, so should make sense to a competent reader who has long since
forgotten the immediate details of the discussion that might have led to
this patch. Including symptoms of the failure which the patch addresses
(kernel log messages, oops messages, etc.) are especially useful for
people who might be searching the commit logs looking for the applicable
patch. The text should be written in such detail so that when read
weeks, months or even years later, it can give the reader the needed
details to grasp the reasoning for **why** the patch was created.
If a patch fixes a compile failure, it may not be necessary to include
_all_ of the compile failures; just enough that it is likely that
someone searching for the patch can find it. As in the ``summary
phrase``, it is important to be both succinct as well as descriptive.
.. _backtraces:
Backtraces in commit messages
"""""""""""""""""""""""""""""
Backtraces help document the call chain leading to a problem. However,
not all backtraces are helpful. For example, early boot call chains are
unique and obvious. Copying the full dmesg output verbatim, however,
adds distracting information like timestamps, module lists, register and
stack dumps.
Therefore, the most useful backtraces should distill the relevant
information from the dump, which makes it easier to focus on the real
issue. Here is an example of a well-trimmed backtrace::
unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
Call Trace:
mba_wrmsr
update_domains
rdtgroup_mkdir
Commentary
^^^^^^^^^^
The ``---`` marker line serves the essential purpose of marking for
patch handling tools where the changelog message ends.
One good use for the additional comments after the ``---`` marker is
for a ``diffstat``, to show what files have changed, and the number of
inserted and deleted lines per file. A ``diffstat`` is especially useful
on bigger patches. If you are going to include a ``diffstat`` after the
``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that
filenames are listed from the top of the kernel source tree and don't
use too much horizontal space (easily fit in 80 columns, maybe with some
indentation). (``git`` generates appropriate diffstats by default.)
Other comments relevant only to the moment or the maintainer, not
suitable for the permanent changelog, should also go here. A good
example of such comments might be ``patch changelogs`` which describe
what has changed between the v1 and v2 version of the patch.
Please put this information **after** the ``---`` line which separates
the changelog from the rest of the patch. The version information is
not part of the changelog which gets committed to the git tree. It is
additional information for the reviewers. If it's placed above the
commit tags, it needs manual interaction to remove it. If it is below
the separator line, it gets automatically stripped off when applying the
patch::
<commit message>
...
Signed-off-by: Author <author@mail>
---
V2 -> V3: Removed redundant helper function
V1 -> V2: Cleaned up coding style and addressed review comments
path/to/file | 5+++--
...
See more details on the proper patch format in the following
references.
.. _explicit_in_reply_to:
Explicit In-Reply-To headers
----------------------------
It can be helpful to manually add In-Reply-To: headers to a patch
(e.g., when using ``git send-email``) to associate the patch with
previous relevant discussion, e.g. to link a bug fix to the email with
the bug report. However, for a multi-patch series, it is generally
best to avoid using In-Reply-To: to link to older versions of the
series. This way multiple versions of the patch don't become an
unmanageable forest of references in email clients. If a link is
helpful, you can use the https://lore.kernel.org/ redirector (e.g., in
the cover email text) to link to an earlier version of the patch series.
Providing base tree information
-------------------------------
When other developers receive your patches and start the review process,
it is absolutely necessary for them to know what is the base
commit/branch your work applies on, considering the sheer amount of
maintainer trees present nowadays. Note again the **T:** entry in the
MAINTAINERS file explained above.
This is even more important for automated CI processes that attempt to
run a series of tests in order to establish the quality of your
submission before the maintainer starts the review.
If you are using ``git format-patch`` to generate your patches, you can
automatically include the base tree information in your submission by
using the ``--base`` flag. The easiest and most convenient way to use
this option is with topical branches::
$ git checkout -t -b my-topical-branch master
Branch 'my-topical-branch' set up to track local branch 'master'.
Switched to a new branch 'my-topical-branch'
[perform your edits and commits]
$ git format-patch --base=auto --cover-letter -o outgoing/ master
outgoing/0000-cover-letter.patch
outgoing/0001-First-Commit.patch
outgoing/...
When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
notice that it will have the ``base-commit:`` trailer at the very
bottom, which provides the reviewer and the CI tools enough information
to properly perform ``git am`` without worrying about conflicts::
$ git checkout -b patch-review [base-commit-id]
Switched to a new branch 'patch-review'
$ git am patches.mbox
Applying: First Commit
Applying: ...
Please see ``man git-format-patch`` for more information about this
option.
.. note::
The ``--base`` feature was introduced in git version 2.9.0.
If you are not using git to format your patches, you can still include
the same ``base-commit`` trailer to indicate the commit hash of the tree
on which your work is based. You should add it either in the cover
letter or in the first patch of the series and it should be placed
either below the ``---`` line or at the very bottom of all other
content, right before your email signature.
Make sure that base commit is in an official maintainer/mainline tree
and not in some internal, accessible only to you tree - otherwise it
would be worthless.
Tooling
-------
Many of the technical aspects of this process can be automated using
b4, documented at <https://b4.docs.kernel.org/en/latest/>. This can
help with things like tracking dependencies, running checkpatch and
with formatting and sending mails.
References
----------
Andrew Morton, "The perfect patch" (tpp).
<https://www.ozlabs.org/~akpm/stuff/tpp.txt>
Jeff Garzik, "Linux kernel patch submission format".
<https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer.html>
<http://www.kroah.com/log/linux/maintainer-02.html>
<http://www.kroah.com/log/linux/maintainer-03.html>
<http://www.kroah.com/log/linux/maintainer-04.html>
<http://www.kroah.com/log/linux/maintainer-05.html>
<http://www.kroah.com/log/linux/maintainer-06.html>
Kernel Documentation/process/coding-style.rst
Linus Torvalds's mail on the canonical patch format:
<https://lore.kernel.org/r/[email protected]>
Andi Kleen, "On submitting kernel patches"
Some strategies to get difficult or controversial changes in.
http://halobates.de/on-submitting-patches.pdf
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
현재 source tree와 subsystem workflow 확인
1-42Linux kernel change를 제출하려는 개인이나 회사는 익숙하지 않은 process를 어렵게 느낄 수 있다. 이 문서는 change가 받아들여질 가능성을 크게 높이는 지침을 간결하게 모은다.
Kernel development process의 자세한 설명은 Documentation/process/development-process.rst, 제출 전 checklist는 Documentation/process/submit-checklist.rst를 본다. Device tree binding patch는 Documentation/devicetree/bindings/submitting-patches.rst를 읽는다. Subsystem·maintainer tree별 추가 workflow는 Documentation/process/maintainer-handbooks.rst에 있다.
이 문서는 git으로 patch를 만든다고 가정한다. Git을 모르면 먼저 익히는 것이 kernel development와 일반 작업을 훨씬 쉽게 만든다.
Current source repository가 없다면 mainline repository를 clone한다.
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git다만 mainline을 직접 base로 쓰지 않을 수 있다. Subsystem maintainer 대부분은 자체 tree를 운영하고 그 tree 기준 patch를 원한다. MAINTAINERS의 해당 subsystem T: entry에서 tree를 찾고 없으면 maintainer에게 묻는다.
Problem, impact, trade-off와 solution 설명
43-165한 line bug fix든 5,000 line 새 feature든 작업을 시작하게 한 underlying problem이 있어야 한다. Reviewer에게 고칠 가치가 있는 문제이며 첫 paragraph 뒤도 읽을 이유가 있음을 설득한다.
User-visible impact를 설명한다. Crash와 lockup만 impact가 아니다. Code review에서 발견한 문제라도 사용자에게 어떤 영향을 줄지 적는다. Linux 설치 대부분은 upstream에서 일부 patch만 cherry-pick하는 secondary stable tree나 vendor/product tree를 사용하므로 downstream routing에 도움이 되는 정보를 포함한다.
- 문제가 발생하는 조건
- dmesg 발췌와 crash description
- Performance regression과 latency spike
- Lockup 등 사용자 관측 증상
Performance, memory consumption, stack footprint, binary size 개선을 주장하면 수치로 입증한다. CPU, memory, readability 사이 trade-off나 heuristic이 workload별로 보이는 차이처럼 잘 드러나지 않는 cost도 설명한다. Reviewer가 benefit과 cost를 비교할 수 있어야 한다.
Problem을 세운 뒤 실제로 무엇을 바꾸는지 technical detail을 plain English로 설명한다. Reviewer가 code가 의도대로 동작하는지 검증할 수 있어야 한다. Git commit log로 바로 가져갈 수 있는 형식이면 maintainer에게 도움이 된다.
Patch 하나는 problem 하나만 해결한다. Description이 길어지기 시작하면 patch를 나눌 신호다. 제출·재제출할 때마다 complete description과 justification을 포함한다. 단지 version N이라고 쓰거나 maintainer가 이전 version과 외부 URL에서 설명을 찾아 조합할 것이라 기대하지 않는다. Patch series와 description은 self-contained여야 하며 이전 version을 받지 못한 reviewer에게도 필요하다.
Change description은 “[This patch] makes xyzzy do frotz”나 “[I] changed...” 대신 “make xyzzy do frotz”처럼 codebase에 behavior change를 지시하는 imperative mood로 쓴다.
특정 commit을 가리킬 때 SHA-1만 쓰지 말고 one-line summary도 넣는다. SHA-1은 최소 첫 12 character를 사용한다. Kernel repository object가 매우 많아 짧은 ID는 현재 충돌하지 않아도 몇 년 뒤 충돌할 수 있다.
Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.관련 discussion이나 background가 web에 있으면 Link: tag를 추가한다. Mailing list archive는 lore.kernel.org를 선호하며 Message-ID에서 angle bracket을 뺀 값을 URL에 넣는다. Link가 실제 relevant message로 동작하는지 확인한다.
Link: https://lore.kernel.org/[email protected]External resource 없이도 설명을 이해할 수 있게 한다. URL만 제시하지 말고 제출된 patch로 이어진 discussion 핵심을 요약한다.
Bug fix는 public mailing list archive나 bug tracker report를 Closes: URL로 가리킨다. 일부 tracker는 commit 적용 시 issue를 자동 close하고 mailing list bot도 추적한다. Private tracker와 invalid URL은 금지된다.
Closes: https://example.com/issues/1234특정 commit의 bug를 고치면 Fixes:에 12자 이상 SHA-1과 one-line summary를 넣고 여러 line으로 나누지 않는다. Tag는 parsing script를 위해 75-column wrap rule의 예외다.
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")다음 git config는 git log·show에서 같은 Fixes 형식을 만든다.
[core]
abbrev = 12
[pretty]
fixes = Fixes: %h (\"%s\")
$ git log -1 --pretty=fixes 54a4f0239f2eLogical change 분리와 style check
166-228각 logical change를 별도 patch로 나눈다. 한 driver의 bug fix와 performance enhancement는 둘 이상 patch로 나누고, API update와 그 API를 쓰는 new driver도 분리한다.
반대로 하나의 logical change가 많은 file을 수정한다면 한 patch에 묶는다. 각 patch는 reviewer가 쉽게 이해하고 검증할 수 있어야 하며 자체 merit로 정당화돼야 한다.
Change 완성에 다른 patch가 필요해도 괜찮다. Description에 “this patch depends on patch X”라고 명시한다.
Series의 각 patch 뒤에 kernel이 정상 build·run되는지 특히 주의한다. git bisect는 series 어느 지점에서든 잘라 test할 수 있으므로 중간 commit이 bug를 만들면 안 된다.
Patch set을 더 줄일 수 없다면 한 번에 약 15개만 게시하고 review와 integration을 기다린다.
Documentation/process/coding-style.rst에 따라 기본 style violation을 검사한다. 하지 않으면 reviewer 시간을 낭비하고 읽히지도 않은 채 거부될 수 있다.
예외는 code를 file 사이에 옮기는 patch다. Move patch에서 moved code 자체를 함께 고치지 않는다. 이동과 수정이 명확히 분리되어 actual difference review와 history tracking이 쉬워진다.
제출 전 scripts/checkpatch.pl을 실행한다. 다만 checker는 human judgment를 대신하지 않는 guide다. Violation이 있어도 code가 더 읽기 좋다면 그대로 둘 수 있지만 남은 모든 violation을 설명할 수 있어야 한다.
| Level | 의미 |
|---|---|
| ERROR | 잘못됐을 가능성이 매우 높은 항목 |
| WARNING | 주의 깊은 review가 필요한 항목 |
| CHECK | 생각해 볼 필요가 있는 항목 |
Patch recipient 선택
231-276Maintained code patch에는 적절한 subsystem maintainer와 list를 항상 CC한다. MAINTAINERS와 source revision history를 확인하고 scripts/get_maintainer.pl에 patch path를 argument로 넘겨 활용한다. Maintainer를 찾지 못하면 Andrew Morton([email protected])이 last resort maintainer다.
모든 patch에는 기본적으로 [email protected]를 사용하지만 volume이 커서 일부 developer는 보지 않는다. 관련 없는 list와 사람에게 spam을 보내지 않는다. Kernel.org hosting list는 subspace.kernel.org에서 찾을 수 있고 외부 hosting list도 있다.
Linus Torvalds는 최종 arbiter이며 address는 [email protected]다. Mail이 매우 많고 현재 patch가 Linus에게 직접 가는 경우는 거의 없으므로 보통 직접 보내지 않도록 최선을 다한다.
Exploitable security bug fix는 [email protected]로 보낸다. Severe bug는 distributor가 user에게 patch를 전달할 시간을 주기 위해 짧은 embargo를 둘 수 있으므로 이 경우 public list에 보내지 않는다. Documentation/process/security-bugs.rst를 참고한다.
Released kernel의 severe bug fix는 sign-off area에 Cc: [email protected]를 넣는다. 이는 email recipient가 아니다. Documentation/process/stable-kernel-rules.rst도 읽는다.
Userland-kernel interface change는 MAINTAINERS의 MAN-PAGES maintainer에게 man-page patch 또는 최소한 notification을 보내고 [email protected]도 CC한다.
Plain-text email, review response와 resend
278-395Patch는 inline plain text로 보낸다
Developer가 standard email tool로 change 일부를 quote해 comment할 수 있어야 한다. 모든 patch를 email 본문 inline으로 보내며 git send-email을 강하게 권장한다.
Cut-and-paste한다면 editor word-wrap이 patch를 훼손하지 않게 한다. Compressed 여부와 상관없이 MIME attachment로 붙이지 않는다. Mail application이 plain text 그대로 전송하지 않아 line comment가 불가능해질 수 있고 처리 시간도 늘어 acceptance 가능성이 낮아진다. Mailer가 patch를 망가뜨리면 누군가 MIME resend를 요청하는 예외는 있다.
Review comment에 답한다
거의 반드시 improvement comment를 받는다. 반드시 답해야 하며 reviewer를 무시하면 자신도 무시당한다. Code change로 이어지지 않은 question과 comment도 다음 reviewer가 이해하도록 code comment나 changelog entry로 남길 가능성이 높다.
어떤 change를 할지 reviewer에게 알리고 시간에 감사한다. Review는 피곤하고 오래 걸려 reviewer가 불친절해질 때도 있지만 정중히 답하고 지적한 문제를 해결한다.
다음 version에는 cover letter나 개별 patch에 이전 submission과의 차이를 설명하는 patch changelog를 넣는다. Comment한 사람을 새 version CC list에 추가해 알린다.
Trimmed interleaved reply
Kernel discussion에서는 top-posting을 강하게 피한다. 필요한 quote 바로 아래에 inline reply를 달고 답과 무관한 quote를 모두 자른다.
A: http://en.wikipedia.org/wiki/Top_post
Q: Where do I find info about this thing called top-posting?
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?
A: No.
Q: Should I include quotations after my reply?기다림과 RESEND
제출 뒤에는 기다린다. 보통 2~3주 안에 comment를 받는다. 없다면 올바른 곳에 보냈는지 확인한다. Resubmit 또는 ping 전 최소 1주를 기다리고 merge window 같은 busy period에는 더 기다린다.
몇 주 뒤 변경 없이 다시 보내면 subject에 RESEND를 추가한다. 수정한 version에는 RESEND를 쓰지 않는다.
[PATCH Vx RESEND] sub/sys: Condensed patch summaryMail traffic에서 patch를 구분하도록 subject에 [PATCH]를 붙인다. git send-email이 자동으로 처리한다.
Developer's Certificate of Origin 1.1
396-455여러 maintainer layer를 거치는 patch에서 누가 무엇을 했는지 추적하도록 sign-off 절차를 사용한다. Patch 설명 끝의 단순한 line으로 자신이 작성했거나 open-source patch로 전달할 권리가 있음을 인증한다.
기여자가 인증하는 내용
(a) Contribution 전부 또는 일부를 자신이 만들었고 file에 표시된 open source license로 제출할 권리가 있다.
(b) 아는 한 contribution이 적절한 open source license가 적용된 prior work에 기반하며, 그 license에 따라 자신이 전부 또는 일부 만든 modification과 함께 file에 표시된 같은 license로 제출할 권리가 있다. 다른 license로 제출할 허가가 있으면 그 license를 사용할 수 있다.
(c) (a), (b), 또는 (c)를 인증한 다른 사람이 contribution을 직접 제공했고 자신은 수정하지 않았다.
(d) Project와 contribution이 public이고 자신이 제출한 모든 personal information과 sign-off를 포함한 contribution record가 무기한 유지되며 project 또는 관련 open source license에 따라 재배포될 수 있음을 이해하고 동의한다.
위 조건을 인증할 수 있으면 known identity로 Signed-off-by를 추가한다. Anonymous contribution은 허용되지 않는다.
Signed-off-by: Random J Developer <[email protected]>git commit -s가 자동으로 추가하고 revert는 git revert -s를 사용한다. 추가 internal company tag를 끝에 둘 수 있으며 현재는 무시되지만 내부 절차나 sign-off의 특별한 detail을 표시할 수 있다.
Author SoB 뒤의 SoB는 개발에는 참여하지 않고 patch를 처리·운반한 사람의 것이다. Chain은 maintainer와 최종적으로 Linus까지 patch가 실제 이동한 경로를 반영하며 첫 SoB는 single author의 primary authorship을 나타낸다.
Acked-by, Cc와 Co-developed-by
456-537Signed-off-by는 signer가 patch 개발 또는 delivery path에 참여했음을 뜻한다.
Patch preparation이나 handling에 직접 참여하지 않았지만 approval을 기록하고 싶다면 Acked-by를 요청할 수 있다. 주로 영향받는 code의 책임자나 관계자가 사용한다. Maintainer가 patch를 만들거나 전달하지 않았지만 landing에 동의할 때 흔하다.
Original code author 같은 domain expert, kernel uAPI patch의 userspace reviewer, feature 주요 사용자도 쓸 수 있다. 의미를 분명히 하려면 # Suffix를 붙일 수 있다.
Acked-by: The Stakeholder <[email protected]> # As primary userAcked-by는 Signed-off-by보다 덜 formal하며 최소한 patch를 보고 acceptance를 표시했다는 기록이다. “looks good” 답을 merger가 Acked-by로 바꾸기도 하지만 explicit ack를 요청하는 편이 좋다.
Reviewed-by보다도 덜 formal하다. Maintainer가 landing에는 동의하지만 thorough technical review는 하지 않았거나 주요 사용자가 general approach와 interface에는 만족하지만 technical review는 하지 않았을 수 있다.
여러 subsystem patch에서 한 maintainer Acked-by는 보통 그 maintainer 영역만 인정한다. Original discussion과 # Suffix를 보고 판단한다.
Comment 기회가 있었지만 comment하지 않은 사람에게는 optional Cc: tag를 붙여 interested party가 discussion에 포함됐음을 기록할 수 있다. Explicit permission 없이 사용할 수 있을 가능성이 있는 tag 세 개 중 하나다.
Co-developed-by는 여러 developer가 patch를 공동 작성했음을 기록한다. Git From: author 외 co-author에게 attribution한다. Authorship이므로 각 Co-developed-by 바로 뒤에 같은 co-author의 Signed-off-by가 반드시 와야 한다.
SOB ordering은 From:과 Co-developed-by 중 어느 방식으로 author를 표시하든 가능한 한 patch의 chronological history를 반영한다. 마지막 Signed-off-by는 항상 실제 submitter다. Email header From과 author name·email이 같으면 body From: tag는 optional이다.
<changelog>
Co-developed-by: First Co-Author <[email protected]>
Signed-off-by: First Co-Author <[email protected]>
Co-developed-by: Second Co-Author <[email protected]>
Signed-off-by: Second Co-Author <[email protected]>
Signed-off-by: From Author <[email protected]>
From: From Author <[email protected]>
<changelog>
Co-developed-by: Random Co-Author <[email protected]>
Signed-off-by: Random Co-Author <[email protected]>
Signed-off-by: From Author <[email protected]>
Co-developed-by: Submitting Co-Author <[email protected]>
Signed-off-by: Submitting Co-Author <[email protected]>Reported, Tested, Reviewed, Suggested와 Fixes tag
539-620Reported-by는 bug를 찾아 report한 사람에게 credit을 주고 향후에도 돕도록 장려한다. Feature request credit에는 쓰지 않는다. Web report가 없다면 예외지만 보통 바로 뒤에 report를 가리키는 Closes:가 와야 한다. Report된 issue 일부만 고치면 Link:를 쓸 수 있다. Explicit permission 없이 쓸 수 있을 가능성이 있는 tag 중 하나다.
Tested-by는 표시된 사람이 어떤 environment에서 patch를 성공적으로 test했음을 뜻한다. Maintainer에게 test 사실을 알리고 future patch tester를 찾을 수 있게 하며 tester에게 credit을 준다.
Reviewer's statement of oversight
Reviewed-by를 제공하는 reviewer는 다음을 진술한다.
- Mainline kernel inclusion의 적절성과 readiness를 평가하기 위해 technical review를 수행했다.
- Patch 관련 problem, concern, question을 submitter에게 전달했고 comment에 대한 response에 만족한다.
- 더 개선할 점은 있을 수 있지만 현재 가치 있는 kernel modification이며 inclusion을 반대하게 할 known issue가 없다고 믿는다.
- Patch가 sound하다고 믿지만 별도 명시가 없는 한 목적 달성이나 모든 상황의 정상 동작을 보증하지 않는다.
Reviewed-by는 심각한 technical issue가 남지 않은 적절한 kernel modification이라는 opinion이다. 실제 review를 수행한 누구나 제공할 수 있다. Reviewer credit과 review 정도를 maintainer에게 알린다. Subject 이해와 thorough review로 알려진 사람의 tag는 merge 가능성을 높인다.
Mailing list에서 받은 Tested-by와 Reviewed-by는 다음 version의 해당 patch에 추가한다. Patch가 크게 바뀌어 더는 적용되지 않으면 제거하고 보통 --- 아래 patch changelog에서 제거 사실을 말한다.
Suggested-by는 patch idea를 제안한 사람에게 credit을 준다. 이 역시 explicit permission 없이 쓸 수 있을 가능성이 있는 세 tag 중 하나다.
Fixes:는 이전 commit의 bug를 고친다는 뜻으로 issue origin 파악과 bug fix review를 돕고 stable team이 적용할 version을 정하는 데도 쓰인다. Fixes:가 stable rule을 우회하지 않으며 stable 후보에는 별도 Cc: [email protected]가 여전히 필요하다.
Tag 제공은 환영받지만 signer, submitter, maintainer는 offered tag 적용 여부를 재량으로 결정할 수 있다.
사람 이름을 tag에 넣기 위한 permission
621-635Cc:, Reported-by:, Suggested-by:를 제외한 앞의 모든 tag는 이름이 들어가는 사람의 explicit permission이 필요하다.
이 세 tag는 lore archive나 commit history에서 그 name과 email로 Linux kernel에 기여했고, Reported-by와 Suggested-by의 경우 public하게 report 또는 suggestion했다면 implicit permission으로 쓸 수 있다.
bugzilla.kernel.org는 이 의미에서 public place지만 그곳에 사용된 email address는 private이다. 이전 contribution에서 공개적으로 사용한 address가 아니라면 tag에 노출하지 않는다.
Canonical patch format과 subject
636-740Git repository에 patch가 있다면 git format-patch가 올바른 formatting을 만든다. Tool은 필요한 설명 text를 만들 수 없으므로 지침을 직접 따라야 한다.
Subject: [PATCH 001/123] subsystem: summary phraseCanonical message body 순서는 sender와 author가 다를 때만 필요한 author From: line, empty line, 75 column로 wrap한 permanent changelog explanation, empty line, Signed-off-by line, --- marker, permanent changelog에 부적합한 comment, 실제 diff다.
Apply tool은 --- 위를 permanent commit message로 가져가고 아래의 version note와 diffstat를 review-only 정보로 제거한다.
Zero-padded sequence number 덕분에 subject alphabetic sort와 numeric sort가 같아 mail reader에서 쉽게 정렬된다.
Subject의 subsystem은 kernel의 대상 area를 식별한다. Summary phrase는 해당 mail patch를 간결히 설명하고 filename이어서는 안 된다. Series 전체 patch에 같은 summary를 반복하지 않는다.
Summary는 patch의 globally unique identifier가 되어 git changelog와 developer discussion에 남고 검색어로 쓰인다. 몇 달 뒤 수천 patch를 gitk나 git log --oneline으로 볼 때 빠르게 보이는 유일한 정보일 수 있다.
Summary는 70~75 character 이내에서 무엇을 바꾸고 왜 필요한지를 모두 나타낸다. 간결하면서 descriptive해야 한다.
[PATCH <tag>...] 형식의 bracket tag는 summary 일부가 아니며 patch 취급 방법을 표시한다. V1, v2, v3는 revision, RFC는 comment request다. Four-patch series는 1/4~4/4로 numbering해 application order와 누락 여부를 알려 준다.
Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
Subject: [PATCH v2 01/27] x86: fix eflags tracking
Subject: [PATCH v2] sub/sys: Condensed patch summary
Subject: [PATCH v2 M/N] sub/sys: Condensed patch summaryBody의 from line은 첫 line이어야 하며 permanent changelog의 author를 정한다. 없으면 email header From:을 사용한다. Organization 이름을 from과 SoB에 넣어 affiliation 또는 sponsor를 표시할 수 있다.
From: Patch Author <[email protected]>
From: Patch Author (Company) <[email protected]>Explanation, backtrace와 --- 아래 commentary
741-821Explanation body는 permanent source changelog에 commit된다. Discussion detail을 오래전에 잊은 competent reader도 이해해야 한다. Kernel log, oops 등 failure symptom은 나중 commit log에서 applicable patch를 찾는 사람에게 특히 유용하다. 몇 주, 몇 달, 몇 년 뒤에도 patch를 만든 이유를 파악할 detail을 남긴다.
Compile failure fix에서 모든 error를 붙일 필요는 없다. Search로 patch를 찾을 만큼만 남기고 간결하면서 descriptive하게 쓴다.
Backtrace는 problem까지의 call chain을 기록하지만 모두 유용하지는 않다. Early boot call chain처럼 unique하고 obvious한 경우가 있고 full dmesg에는 timestamp, module list, register·stack dump가 섞여 집중을 방해한다. Relevant information만 추린다.
unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
Call Trace:
mba_wrmsr
update_domains
rdtgroup_mkdir--- marker는 patch handling tool에 changelog 종료 위치를 알린다. 아래에는 changed file과 insert/delete line 수를 보여 주는 diffstat를 둘 수 있고 큰 patch에서 특히 유용하다. 직접 diffstat를 만들면 -p 1 -w 70으로 source tree root 기준 filename과 좁은 width를 사용한다. Git은 기본적으로 적절히 만든다.
현재 review에만 필요하고 permanent changelog에 부적합한 comment도 --- 아래 둔다. V1과 V2 차이를 설명하는 patch changelog가 대표적이다. 위에 두면 apply 전 수동 제거가 필요하지만 separator 아래면 자동 제거된다.
<commit message>
...
Signed-off-by: Author <author@mail>
---
V2 -> V3: Removed redundant helper function
V1 -> V2: Cleaned up coding style and addressed review comments
path/to/file | 5+++--
...In-Reply-To와 base tree 정보
822-895Explicit In-Reply-To
Bug fix를 bug report mail과 연결하는 등 이전 relevant discussion과 patch를 연결하려면 In-Reply-To header를 수동 추가할 수 있다.
Multi-patch series는 old version과 In-Reply-To로 연결하지 않는 편이 좋다. 여러 revision이 mail client에서 관리 불가능한 reference forest가 될 수 있다. 필요하면 cover letter에서 lore.kernel.org redirector로 이전 series를 link한다.
Base commit 명시
Maintainer tree가 매우 많으므로 reviewer는 patch가 적용되는 base commit·branch를 반드시 알아야 한다. MAINTAINERS의 T: entry를 확인한다. Review 전에 test하는 automated CI에는 더 중요하다.
git format-patch의 --base option으로 base tree 정보를 자동 포함할 수 있다. Topical branch에서 사용하는 방법은 다음과 같다.
$ git checkout -t -b my-topical-branch master
Branch 'my-topical-branch' set up to track local branch 'master'.
Switched to a new branch 'my-topical-branch'
[perform your edits and commits]
$ git format-patch --base=auto --cover-letter -o outgoing/ master
outgoing/0000-cover-letter.patch
outgoing/0001-First-Commit.patch
outgoing/...Cover letter 아래 base-commit: trailer가 생겨 reviewer와 CI가 conflict 걱정 없이 git am할 정보를 제공한다.
$ git checkout -b patch-review [base-commit-id]
Switched to a new branch 'patch-review'
$ git am patches.mbox
Applying: First Commit
Applying: ...--base는 Git 2.9.0에 도입됐다. Git으로 format하지 않아도 base tree commit hash를 같은 base-commit trailer로 cover letter 또는 series 첫 patch에 넣을 수 있다. --- 아래 또는 email signature 직전 모든 content의 맨 아래에 둔다.
Base commit은 official maintainer/mainline tree에 있어야 하며 자신만 접근 가능한 internal tree commit이면 쓸모가 없다.
Tooling과 참고 자료
896-934B4는 dependency tracking, checkpatch 실행, mail formatting과 sending 등 process의 많은 technical aspect를 자동화한다.
- B4 documentation
https://b4.docs.kernel.org/en/latest/ - Andrew Morton, The perfect patch
https://www.ozlabs.org/~akpm/stuff/tpp.txt - Linux kernel patch submission format
https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html - How to piss off a kernel subsystem maintainer, 1
http://www.kroah.com/log/linux/maintainer.html - How to piss off a kernel subsystem maintainer, 2
http://www.kroah.com/log/linux/maintainer-02.html - How to piss off a kernel subsystem maintainer, 3
http://www.kroah.com/log/linux/maintainer-03.html - How to piss off a kernel subsystem maintainer, 4
http://www.kroah.com/log/linux/maintainer-04.html - How to piss off a kernel subsystem maintainer, 5
http://www.kroah.com/log/linux/maintainer-05.html - How to piss off a kernel subsystem maintainer, 6
http://www.kroah.com/log/linux/maintainer-06.html - Linus on canonical patch format
https://lore.kernel.org/r/[email protected] - Andi Kleen, On submitting kernel patches
http://halobates.de/on-submitting-patches.pdf
Documentation/process/coding-style.rst도 참고한다. 마지막 Andi Kleen 자료는 어렵거나 논쟁적인 change를 받아들여지게 하는 전략을 다룬다.
맞는 maintainer tree를 기준으로 시작한다
submitting-patches.rst:3-41Mainline repository는 torvalds/linux에서 얻지만 실제 개발 base가 항상 mainline HEAD인 것은 아니다. Subsystem maintainer가 별도 tree를 운영한다면 MAINTAINERS의 T: entry를 확인하고 그 tree의 적절한 branch 위에서 patch를 준비한다. 명시되지 않았다면 maintainer에게 묻는다.
이 문서는 Git으로 patch를 준비한다고 가정한다. Devicetree binding과 maintainer별 workflow에는 추가 지침이 있으므로 해당 handbook과 binding submission 문서를 함께 읽는다.