원문 : http://wiki.kldp.org/wiki.php/SubmittingPatches
How to Get Your Change Into the Linux Kernel
리눅스 커널에 여러분의 패치(역자주:원본에는 change를 사용하였으나 문맥상 patch로 번역함)를 반영하는 법
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. or
Care And Operation Of Your Linus Torvalds 리눅스 커널에 여러분의 패치(역자주:원본에는 change를 사용하였으나 문맥상 patch로 번역함)를 반영하는 법
혹은
여러분의 Linux Torvalds를 치료하고 수술하는 법 리눅스 커널에 패치를 적용하고 싶은 개인이나 회사의 경우, "시스템"에 익숙하지 않다면 그 절차에 다소 풀이 죽을 수도 있다. 이 문서는 여러분의 패치들이 많이 반영될 수 있도록 하기 위한 제안들을 담고 있다.
Read Documentation/SubmitChecklist for a list of items to check before submitting code. If you are submitting a driver, also read Documentation/SubmittingDrivers.
코드를 제출하기 전, 체크해볼 목록들을 위해 Documentation/SubmitChecklist를 읽어라. 여러분이 드라이버를 제출하고 있다면 Documentation/SubmittingDrivers 또한 읽어야 한다.
SECTION 1 - CREATING AND SENDING YOUR CHANGE
섹션 1 - 패치를 만들어 보내기
1) "diff -up"
1) "diff -up"
Use "diff -up" or "diff -uprN" to create patches.
패치를 만들기 위해 "diff -up" 나 "diff -uprN"을 사용하라.
All changes to the Linux kernel occur in the form of patches, as generated by diff(1). When creating your patch, make sure to create it in "unified diff" format, as supplied by the '-u' argument to diff(1). Also, please use the '-p' argument which shows which C function each change is in - that makes the resultant diff a lot easier to read. Patches should be based in the root kernel source directory, not in any lower subdirectory.
리눅스 커널의 모든 변경사항들은 diff(1)에 의해 만을어지기 때문에 패치의 형태로 나타내어진다. 패치를 만들때는 '-u' 옵션을 사용하여 "unified diff" 양식으로 만들어라. 또한 '-p' 옵션을 사용하여 변경된 영역의 C 함수이름을 나타내어라. 이렇게 하는 것은 읽기 쉬운 패치를 만들어 낼 것이다. 패치는 커널 소스의 하위 디렉토리가 아닌 루트 디렉토리를 기준으로 만들어져야 한다.
To create a patch for a single file, it is often sufficient to do:
하나의 파일만을 위한 패치를 만들려면 흔히 다음과 같이 한다.
SRCTREE= linux-2.6 MYFILE= drivers/net/mydriver.c
cd $SRCTREE cp $MYFILE $MYFILE.orig vi $MYFILE # make your change cd .. diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
SRCTREE= linux-2.6 MYFILE= drivers/net/mydriver.c
cd $SRCTREE cp $MYFILE $MYFILE.orig vi $MYFILE # make your change cd .. diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a diff against your own source tree. For example: cd $SRCTREE cp $MYFILE $MYFILE.orig vi $MYFILE # make your change cd .. diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
SRCTREE= linux-2.6 MYFILE= drivers/net/mydriver.c
cd $SRCTREE cp $MYFILE $MYFILE.orig vi $MYFILE # make your change cd .. diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
복수개의 파일들을 위한 패치를 만들기 위해서는 "vanilla(역자주: 전혀 손대지 않은 원래의 압축 파일 형태의 커널 소스)"를 압출해지하거나 커널 소스 트리를 변경하지 말아야 한다. 그리고 여러분의 소스 트리와 diff를 하여 만들어낸다. 예를 들면 다음과 같다.
MYSRC= /devel/linux-2.6
tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
"dontdiff" is a list of files which are generated by the kernel during the build process, and should be ignored in any diff(1)-generated patch. The "dontdiff" file is included in the kernel tree in 2.6.12 and later. For earlier kernel versions, you can get it from <http://www.xenotime.net/linux/doc/dontdiff>. tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
linux-2.6.12-vanilla $MYSRC > /tmp/patch
MYSRC= /devel/linux-2.6 tar xvfz linux-2.6.12.tar.gz mv linux-2.6.12 linux-2.6.12-vanilla diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
linux-2.6.12-vanilla $MYSRC > /tmp/patch
"dontdiff"는 build 과정 중에 커널이 만들어내는 파일들의 리스트이며 그 파일들은 diff(1)가 만들어내는 패치에서 무시된다. "dontdiff" 파일은 2.6.12 이상의 커널 트리에 포함되어 있다. 그보다 앞버젼들의 커널의 경우, 여러분은 다음에서 dontdiff파일을 얻을 수 있다. <http://www.xenotime.net/linux/doc/dontdiff>.
Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- generated it with diff(1), to ensure accuracy.
여러분의 패치가 제출하려는 패치에 해당되지 않는 기타 다른 파일들을 포함하지 않도록 하라. diff(1)를 통해 패치를 만들어 낸 이후에도 정확하게 하게 하기 위해 여러분의 패치를 검토하라.
If your changes produce a lot of deltas, you may want to look into splitting them into individual patches which modify things in logical stages. This will facilitate easier reviewing by other kernel developers, very important if you want your patch accepted. There are a number of scripts which can aid in this:
여러분의 변경이 많은 델타(역자주:부수적인 것)를 만들어낸다면 논리적인 단계로 구분하여 각각의 패치들로 나누고 싶을 것이다. 그렇게하는 것은 다른 커널 개발자들의 검토를 더 쉽게하며 이는 여러분의 패치가 반영되길 바란다면 매우 중요한 것이다. 그런 노력을 도울수 있는 많은 스크립트들이 있다.
Andrew Morton's patch scripts: http://www.zip.com.au/~akpm/linux/patches/ Instead of these scripts, quilt is the recommended patch management tool (see above). 이 스크립트들 대신 quilt가 추천되는 패치관리 툴이다.(위를 보라)
Andrew Morton's patch scripts: http://www.zip.com.au/~akpm/linux/patches/
2) Describe your changes.
2) 패치에 대한 설명
Describe the technical detail of the change(s) your patch includes.
여러분의 패치가 포함하고 있는 수정사항들에 대하여 기술적으로 자세하게 설명하라.
Be as specific as possible. The WORST descriptions possible include things like "update driver X", "bug fix for driver X", or "this patch includes updates for subsystem X. Please apply."
가능한한 명확하게 하라. 좋지 않은 설명들은 다음과 같은 것들을 포함할 것이다. "드라이버 X의 업데이트", "드라이버 X의 버그 수정", "이 패치는 subsystem X에 대한 업데이트를 포함한다. 반영해달라"
If your description starts to get long, that's a sign that you probably need to split up your patch. See #3, next.
여러분의 설명이 길게 시작한다면 아마도 여러분은 패치를 더 나누어야 할 필요가 있다는 신호일 것이다. 다음, 3번을 참조하라.
3) Separate your changes.
3) 패치 나누기
Separate _logical changes_ into a single patch file.
논리적인 단위마다 하나의 패치파일로 나누어라
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.
예를들어 여러분의 수정이 하나의 드라이버에 대한 버그 수정과 성능 향상 둘 다를 포함하고 있다면 그 수정들을 2개 이상의 패치들로 나누어라. 여러분의 수정이 API 업데이트와 새로운 API를 사용하는 새로운 드라이버로 이루어졌다면 2개의 패치로 나누어라.
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.
다른한편, 여러분이 하나의 수정을 많은 파일들로 만들었다면 그러한 수정들을 하나의 패치파일로 묶어라. 그렇게해서 하나의 논리적 단위의 수정은 하나의 패치내에 담아질 수 있게 된다.
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.
한 패치가 완전해지기위하여 다른 패치에 의존적일 경우도 문제 없다. 간단하게 여러분의 패치설명에 다름과 같이 작성하라. "이 패치는 패치 X에 의존적이다."
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.
여러분이 패치를 더 작은 패치들의 묶음으로 간추릴 수 없다면 일단 포스트하라. 그리고 15분 정도 검토와 통합을 기다려라.
4) Style check your changes.
4) 수정들에 대한 스타일 체크
Check your patch for basic style violations, details of which can be found in Documentation/CodingStyle. Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read.
여러분의 패치가 Documentation/CodingStyle 파일에 있는 기본적인 스타일을 위반하고 있는지 체크하라. 스타일을 지키지 않게 되면 검토해주는 사람들이 시간을 낭비하게 될 것이고 여러분의 패치는 아마도 읽혀지기는 커녕 받아들여지지도 않을 것이다.
At a minimum you should check your patches with the patch style checker prior to submission (scripts/checkpatch.pl). You should be able to justify all violations that remain in your patch.
여러분은 최소한 패치를 제출하기 전에 스타일 체커(scripts/checkpatch.pl)를 가지고 여러분의 패치들을 채크해봐야 한다. 여러분은 패치에 남아있는 모든 위반사항들을 정당화할 수 있어야 한다.
5) Select e-mail destination.
5) 이메일 수신 선택
Look through the MAINTAINERS file and the source code, and determine if your change applies to a specific subsystem of the kernel, with an assigned maintainer. If so, e-mail that person.
MAINTAINERS 파일과 소스코드를 ㅤㅎㅜㅀ어보고 여러분의 수정이 커널의 어떤 subsystem에 국한된 것인지, 특정 메인테이너와 관련된 부분인지를 살펴라. 그리고나서 그 사람에게 메일을 보내라.
If no maintainer is listed, or the maintainer does not respond, send your patch to the primary Linux kernel developer's mailing list, linux-kernel@vger.kernel.org. Most kernel developers monitor this e-mail list, and can comment on your changes.
어떤 메인테이너도 명시되지 않았거나 메인테이너가 응답하지 않는다면 여러분의 패치를 가장 주요한 리눅스 커널의 메일링 리스트인 linux-kernel@vger.kernel.org 로 보내라. 대부분의 커널 개발자들은 이 메일링 리스트를 보고 있으므로 여러분의 수정에 대한 의견을 게진할 것이다.
Do not send more than 15 patches at once to the vger mailing lists!!!
한번에 15개 이상의 패치를 vger 메일링 리스트로 보내지 마라!!!
Linus Torvalds is the final arbiter of all changes accepted into the Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. He gets a lot of e-mail, so typically you should do your best to -avoid- sending him e-mail.
Linux Torvalds는 리눅스 커널에 받아들여질 모든 수정들의 마지막 중재인이다. 그의 이메일 주소는 <torvalds@linux-foundation.org>이다. 그는 많은 메일을 받기 때문에 여러분은 그에게 메일을 보내는 것을 최대한 피해야 한다.
Patches which are bug fixes, are "obvious" changes, or similarly require little discussion should be sent or CC'd to Linus. Patches which require discussion or do not have a clear advantage should usually be sent first to linux-kernel. Only after the patch is discussed should the patch then be submitted to Linus.
버그를 수정하는 패치와 같은 "명백한" 수정 패치들 또는 그와 비슷하게 거의 토론을 필요로 하지 않는 수정들은 Linux를 참조로(CC)로 해서 보내야 한다. 토론을 필요로 하거나 분명한 이점이 없는 패치들은 대개 linux-kernel로 먼저 보내져야 한다. 패치를 충분히 토론한 후에 Linux에게 보내야 한다.
6) Select your CC (e-mail carbon copy) list.
6) 참조목록의 선택
Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
특별한 이유가 없다면 항상 linux-kernel@vger.kernel.org를 참조로 넣어라.
Other kernel developers besides Linus need to be aware of your change, so that they may comment on it and offer code review and suggestions. linux-kernel is the primary Linux kernel developer mailing list. Other mailing lists are available for specific subsystems, such as USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the MAINTAINERS file for a mailing list that relates specifically to your change.
Linus 주위의 다른 커널 개발자들도 여러분이 수정하는 것에 관해 알 필요가 있다. 그렇게되면 다른 커널 개발자들은 여러분의 패치에 대하여 자신들의 의견을 게진할 것이며 코드를 검토하고 새로운 제안을 할것이다. linux-kernel은 주요한 리눅스 커널 개발 메일링 리스트이다. USB, framebuffer 장치들, VFS, SCSI subsystem과 같이 다른 특정 하위시스템에 관련된 메일링 리스트도 있다. 여러분의 패치와 관련있는 메일링 리스트를 찾기위해 MAINTAINERS 파일을 봐라.
Majordomo lists of VGER.KERNEL.ORG at:
VGER.KERNEL.ORG의 Majordomo 리스트들
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.
수정이 userland-kernel 인터페이스에 영향을 준다면 MAN-PAGES 메인테이너에게 man-pages 패치를 보내주거나 적어도 수정이 있다는 사실을 알려 메뉴얼 페이지에 반영되게 되게하라.
Even if the maintainer did not respond in step #4, make sure to ALWAYS copy the maintainer when you change their code.
메인테이너가 응답하지 않았어도 수정을 할때는 메인테이너를 항상 참조로 넣어라.
For small patches you may want to CC the Trivial Patch Monkey trivial@kernel.org managed by Adrian Bunk; which collects "trivial" patches. Trivial patches must qualify for one of the following rules:
소소한 패치의 경우 Adrian Bunk에 의해 관리되는 trivial@kernel.org 주소를 가지고 있는 rivial Patcch Monkey를 참조(CC)로 넣어라. 그곳은 "사소한"패치들을 모은다. 사소한 패치라 함은 다음의 조건들을 만족해야 한다.
Spelling fixes in documentation 문서에 잘못된 스펠링 교정
Spelling fixes which could break grep(1) grep(1)을 하기 어렵게 만드는 스펠링 교정
Warning fixes (cluttering with useless warnings is bad) Warning 교정(쓸모없는 warning으로 어지럽혀 지는 것은 나쁘다)
Compilation fixes (only if they are actually correct) 컴파일 교정(교정한 것이 실제로 옳을 경우에 한해)
Runtime fixes (only if they actually fix things) 실행시의 문제점 교정(실제로 문제를 교정한 경우에 한해)
Removing use of deprecated functions/macros (eg. check_region) 앞으로 없어질게 될 함수나 매크로의 사용을 제거(예. check_region)
Contact detail and documentation fixes 문의처나 문서의 교정
Non-portable code replaced by portable code (even in arch-specific, 이식성이 좋지 않은 코드를 이식성이 좋은 코드로 수정(arch에서만 사용한다 할지라도)
TODO : since people copy, as long as it's trivial)
Any fix by the author/maintainer of the file (ie. patch monkey in re-transmission mode) 파일의 저자나 메인테이너에 의한 수정(TODO)
URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> Spelling fixes which could break grep(1) grep(1)을 하기 어렵게 만드는 스펠링 교정
Warning fixes (cluttering with useless warnings is bad) Warning 교정(쓸모없는 warning으로 어지럽혀 지는 것은 나쁘다)
Compilation fixes (only if they are actually correct) 컴파일 교정(교정한 것이 실제로 옳을 경우에 한해)
Runtime fixes (only if they actually fix things) 실행시의 문제점 교정(실제로 문제를 교정한 경우에 한해)
Removing use of deprecated functions/macros (eg. check_region) 앞으로 없어질게 될 함수나 매크로의 사용을 제거(예. check_region)
Contact detail and documentation fixes 문의처나 문서의 교정
Non-portable code replaced by portable code (even in arch-specific, 이식성이 좋지 않은 코드를 이식성이 좋은 코드로 수정(arch에서만 사용한다 할지라도)
TODO : since people copy, as long as it's trivial)
Any fix by the author/maintainer of the file (ie. patch monkey in re-transmission mode) 파일의 저자나 메인테이너에 의한 수정(TODO)
7) No MIME, no links, no compression, no attachments. Just plain text.
7) MIME, 링크, 압축, 첨부를 사용하지 말고 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.
Linux와 다른 커널 개발자들은 여러분이 제출한 패치들을 읽고 코멘트해야 한다. 커널 개발자들은 기본적인 이메일 툴을 사용하여 여러분의 수정에 quote(역자주: 패치의 중간중간 인용부호를 넣어 자신의 생각을 작성함)를 하여 여러분의 코드 일부분에 코멘트를 할 수 있어야 한다.
For this reason, all patches should be submitting e-mail "inline". WARNING: Be wary of your editor's word-wrap corrupting your patch, if you choose to cut-n-paste your patch.
그런 이유로 모든 패치들은 이메일의 내용에 직접 포함되는 형태로 제출되야만 한다. 주의: 여러분이 여러분의 패치를 cut-n-paste하기로 했다면 여러분이 사용하는 편집기의 word-wrap 기능이 패치를 망가뜨리지 않을지 주의해야 한다.
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.
패치를 압축유무와는 상관없이 MIME 형태로는 첨부하지 말라. 널리 사용되는 많은 이메일 응용프로그램들이 항상 MIME 첨부파일을 순수한 text로 보내지 않을 것이며 그로 인하여 다른 사람들은 여러분의 코드에 코멘트할 수 없게 될 것이다. 또한 MIME 첨부는 Linus가 패치를 처리하는 시간을 더 들이도록 하고 패치가 받아들여질 확률은 더 줄어들게 만든다.
Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME.
예외: 여러분의 mailer가 패치들을 엉망으로 만든다면 누군가는 여러분에게 MIME을 사용하여 다시 보내달라고 요청할 수도 있다.
WARNING: Some mailers like Mozilla send your messages with
---- message header
Content-Type: text/plain; charset=us-ascii; format=flowed
---- message header
The problem is that "format=flowed" makes some of the mailers on receiving side to replace TABs with spaces and do similar changes. Thus the patches from you can look corrupted.
문제는 "format=flowed"이다. 이것은 받는 측의 mailer중의 일부가 TAB을 space로 바꾸도록 만들며 유사한 다른 문제들을 발생킨다. 그래서 여러분의 패치가 깨져 보일 것이다.
To fix this just make your mozilla defaults/pref/mailnews.js file to look like: pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= pref("mailnews.display.disable_format_flowed_support", true);
이 문제를 수정하기 위해서 여러분의 모질라 defaults/pref/mailnews.js 파일을 다음과 같이 수정하라. pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= pref("mailnews.display.disable_format_flowed_support", true);
8) E-mail size.
8) E-mail 크기
When sending patches to Linus, always follow step #7.
Linus에게 패치를 보낼 때는 항상 섹션 7번에서 명시한 대로 하라.
Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 40 kB in size, it is preferred that you store your patch on an Internet-accessible server, and provide instead a URL (link) pointing to your patch.
큰 패치는 메일링 리스트와 일부 메인테이너들에게는 적절하지 않다. 여러분의 패치가 압축하지 않은 상태로 크기가 40 kB를 넘게된다면 패치를 인터넷으로 접근 가능한 서버에 저장하고 패치를 가리키는 URL(link) 로 대치하는 것이 더 좋은 방법이다.
9) Name your kernel version.
9) 여러분이 사용하는 커널 버젼의 명기
It is important to note, either in the subject line or in the patch description, the kernel version to which this patch applies.
패치의 제목줄 또는 패치의 설명에 패치가 적용되는 커널 버젼을 명시하는 것은 중요하다.
If the patch does not apply cleanly to the latest kernel version, Linus will not apply it.
패치가 최신 커널 버젼에 올바르게 적용되지 않는다면 Linus는 그 패치를 적용하지 않을 것이다.
10) Don't get discouraged. Re-submit.
10) 좌절하지 말고 다시 보내라.
After you have submitted your change, be patient and wait. If Linus likes your change and applies it, it will appear in the next version of the kernel that he releases.
패치를 제출한 후에 인내심을 가지고 기다려라. Linus가 여러분의 패치가 맘에 들고 패치를 적용한다면 배포되는 다음 버젼의 커널에서 여러분의 패치를 보게 될 것이다.
However, if your change doesn't appear in the next version of the kernel, there could be any number of reasons. It's YOUR job to narrow down those reasons, correct what was wrong, and submit your updated change.
그러나, 여러분의 패치가 다음 커널 버젼에 나타나지 않으면 아마 많은 이유가 있을 것이다. 그 이유를 찾아 잘못된 것을 수정하고 업데이트하여 다시 보내는 것은 여러분이 해야 할 일이다.
It is quite common for Linus to "drop" your patch without comment. That's the nature of the system. If he drops your patch, it could be due to
Linus가 아무 언급없이 여러분의 패치를 "버리는 것"은 늘상 있는 일이다. 그것은 자연스러운 것이다. Linus가 여러분의 패치를 버린다면 아마 다음 문제들 때문일 것이다.
* Your patch did not apply cleanly to the latest kernel version. * Your patch was not sufficiently discussed on linux-kernel. * A style issue (see section 2). * An e-mail formatting issue (re-read this section). * A technical problem with your change. * He gets tons of e-mail, and yours got lost in the shuffle. * You are being annoying.
* 여러분의 패치는 최신 커널 버젼에 깨끗이 적용되지 않았다. * 여러분의 패치는 linux-kernel에서 충분히 토론되지 않았다. * 스타일 문제(2절 참조) * 이메일 양식 문제(이번 절을 다시 읽어라) * 여러분의 패치의 기술적인 문제 * Linus는 수천통의 메일을 받았고 뒤섞여서 결국 여러분의 것을 잃어버렸다. * 여러분은 Linus를 귀찮게 하고 있다.
When in doubt, solicit comments on linux-kernel mailing list.
의심되면 linux-kernel 메일링 리스트에 확인 메일을 보내봐라.
11) Include PATCH in the subject
11) 제목에 PATCHf라는 문구를 포함하라
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.
Linus와 linux-kernel에는 많은 메일 트래픽이 있기 때문에 여러분의 제목앞에 PATCH라고 명시하는 것이 일반적인 관례다. 이렇게 함으로써 Linus와 다른 커널 개발자들은 패치 메일을 다른 메일들과 구별하기 수월해진다.
12) Sign your work
12) 여러분의 작업에 대한 싸인
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.
누가 무엇을 했는지를 파악하기 위해서(특히, 각각의 메인테이너들이 관리하는 여러 레이어들을 거치며 최종본을 만들어가는 경우) 이메일에 "sigh-off"를 하는 절차를 도입했다.
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 a open-source patch. The rules are pretty simple: if you can certify the below:
sign-off는 패치에 대한 설명 끝에 간단히 한 라인으로 들어가며 여러분이 그 패치를 작성했다는 것이나 또는 그 패치를 open-sourch 패치로써 제출할 권리를 가지고 있다는 것을 입증하는 것이다. 규칙은 상당히 간단하다. 여러분이 아래와 같은 것들을 입증할 수 있다면 TODO
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
(d) I understand and agree that this project and the contribution
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.
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 <random@developer.example.org>
using your real name (sorry, no pseudonyms or anonymous contributions.) (유감이지만 가명이나 익명은 안된다) 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.
일부 사람들은 패치의 끝에 다른 꼬릿말(tag)를 두기도 한다. 그런 것들이 지금은 무시될 것이지만 꼬릿말을 통하여 회사 내부 절차를 표시하거나 sign-off에 관한 몇몇 세부사항을 나타내기 위해 사용할 수 있다.
13) When to use Acked-by:
TODO: 여기서부터
13) Acked-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.
Signed-off-by: 이 태그는 싸인을 한 사람이 패치의 개발에 관계되었거나 그 사람이 패치를 전달하는 과정에 관계되어 있었다는 것을 나타낸다.
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 arrange to have an Acked-by: line added to the patch's changelog.
어느 한 사람이 패치의 준비나 처리과정에 직접적으로 관여하지 않았지만 패치에 대한 승인을 기록하거나 나타내길 원한다면 Acked-by를 사용하여 그렇게 할 수 있다. Acked-by는 패치의 changelog에 덧붙여지는 라인이다.
Acked-by: is often used by the maintainer of the affected code when that maintainer neither contributed to nor forwarded the patch.
Acked-by는 일반적으로 메인테이너가 패치를 만드는 데 공헌하지 않았거나 패치를 전달하는 것이 아닐 때 관련된 코드의 메인테이너에의해 사용된다.
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:.
Acked-by는 Signed-off-by과 같이 어떤 공식적인 것은 아니다. 그것은 ack를 하는 사람이 적어도 그 패치를 검토하였으며 승인을 했다는 것을 나타내는 것이다. 그러므로 패치를 병합하는 사람은(merger) 때론 직접 승인한 사람의 "음, 좋아 보이는 걸" 과 같은 문구를 Acked-by로 변환할 것이다.
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. Acked-by가 절대적으로 모든 패치를 승인했다는 것을 의미하는 것은 아니다. 예를 들어 하나의 패치가 여러개의 subsystem에 영향을 주고 한 subsystem의 메인테이너로부터만 Acked-by를 받았다면 이것은 단지 그 메인테이너의 코드에 영향을 주는 부분만을 승인받았다는 것을 의미하는 것이다. 판단은 여기서 해야한다. 의심스러우면 메일링 리스트 아카이브에 토론되었던 원본을 참조해야 한다.
14) The canonical patch format 14) 표준 패치 포맷
The canonical patch subject line is: 표준 패치 제목은 다음과 같다.
The canonical patch message body contains the following: 표준 패치 내용은 다음과 같다.
- A "from" line specifying the patch author.
- "from"은 패치 저자를 명시하는 라인이다. - An empty line.
- 한 줄의 빈 라인. - The body of the explanation, which will be copied to the
- 이 패치를 설명하는 changelog에 영원히 기록될 내용 permanent changelog to describe this patch.
- The "Signed-off-by:" lines, described above, which will
- 위에서 설명했던 "Signed-off-by"라인들, 이 라인들도 changelog에
also go in the changelog.
기록됨
- A marker line containing simply "---".
- 간단히 "---"를 포함하는 표시 라인
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. =======================================================================??? 여까지 제목 라인 포맷은 이메일을 제목 라인에 의해 알파벳순으로 정렬하기 쉽게 만든다. 많은 이메일 리더들이 그러한 것을 지원할 것이다. ㅁㄴ이러ㅏ이넘리머니 링ㄴ멀 - Any additional comments not suitable for the changelog.
- changelog에 알맞지 않은 부가적인 코멘트 - The actual patch (diff output).
- 실제 패치(diff의 산출물) The "subsystem" in the email's Subject should identify which area or subsystem of the kernel is being patched. 이메일의 제목에 "subsystem"은 커널의 어떤 영역이나 subsystem이 패치되고 있는지를 구분해야 한다.
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).
이메일의 제목에 "summary phrase"는 이메일이 담고 있는 패치를 간결하게 설명해야 한다. "summary phrase"는 파일이름이 되서는 안된다. 전체 패치 시리즈에 모든 패치마다 같은 "summary phrase"를 사용하지 마라. (ㅁㄴ이라ㅓ미 러ㅣ망너리만ㄹ)
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.
여러분의 이메일에 "summary phrase"가 그 패치를 구분하는 세계에서 유일한 식별자게 된다는 것을 유념해라. "summary phrase"는 나중에 그 패치를 참조하는 개발자들간의 토론에서 사용될 수도 있다. 사람드른 그 패치와 관련된 토론 내용들을 읽기 위하여 "summary phrase"를 구글링 하길 원할 것이다.
A couple of example Subjects: 두개의 제목 예제:
Subject: patch 2/5 ext2: improve scalability of bitmap searching Subject: PATCHv2 001/207 x86: fix eflags tracking
The "from" line must be the very first line in the message body, and has the form: "from"라인은 반드시 내용의 첫 라인에 위치해야 하며 다음과 같은 형태를 가져야 한다.
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. "from"라인은 영원히 남게 될 changelog에 패치의 저자로써 누가 자랑스럽게 올라갈 것인지를 명시하는 것이다. "from"라인이 없다면 이메일 헤더의 "From" 라인이 changelog에 패치의 저자로서 기록될 것이다.
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.
내용은 영원한 source의 changelog에 남게 될 것이다. 그래서 이 패치를 ㅁㅇㄴㄹ;ㅣ망;니라 ㅁㄴ이;라;ㅁㄴ
The "---" marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. "---" 표시 라인은 changelog 내용이 끝났다는 것을 나타낸다.
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. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go here. 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).
"---" 표시 이후에 부가적인 코멘트들의 좋은 예는 diffstat이다. diffstat은 변경된 파일들마다 새로 추가된 라인과 삭제된 라인을 보여준다. diffstat는 특히 큰 패치에 유용하다. 영구히 기록되는 changelog에는 적합하지 않으며 단지 그때에만, 혹은 메인테이너에게만 관련된 코멘트들이 이곳에 와야 한다. diffstat 옵션을 "-p 1 -w 70" 으로 사용해서 파일 이름들이 커널 소스 트리의 맨 위에 나열되도록하고 너무 많은 horizontal space를 사용하지 말게 하라. (대충 80개의 컬럼이 적당하며 아마 약간의 들여쓰기
See more details on the proper patch format in the following references.
올바른 패치 포맷에 관한 더 자세한 사항은 다음을 참조하라.
SECTION 2 - HINTS, TIPS, AND TRICKS
SECTION 2 - 힌트, 팁과 트릭
This section lists many of the common "rules" associated with code submitted to the kernel. There are always exceptions... but you must have a really good reason for doing so. You could probably call this section Linus Computer Science 101.
이 섹션은 커널에 제출된 코드와 관련된 일반적인 많은 "규칙"들을 나열한다. 항상 예외가 있긴 하지만 여러분은 여러분은 그렇게 한 이유를 가지고 있어야 한다. 아마도 여러분은 이 섹션을 TODO Linux Computer Science 101이라 부를 것이다.
1) Read Documentation/CodingStyle
1) Documentation/CodingStyle을 읽어라.
Nuff said. If your code deviates too much from this, it is likely to be rejected without further review, and without comment.
충분히 말했다. 여러분의 코드가 CodingStyle 문서에서 많이 벗어나게 되면 더 이상의 검토나 코멘트없이 거절될 것이다.
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.
한가지 확실한 예외는 한 파일에서 다른 파일로 코드를 옮길 때이다. 이런 경우 여러분은 옮기는 코드의 내용을 절대 변경하지 말아야 한다. TODO 이렇게 하는 것은 코드를 단지 옮기며 수정하는 여러분의 의도를 그대로 나타낸다. 이렇게 하는 것은 실제 변경된 내용만을 검토할 수 있도록 도와주는 것이며 다른 도구들로 코드의 변경내용들을 더 추적하기 좋게 만든다.
Check your patches with the patch style checker prior to submission (scripts/checkpatch.pl). The style checker should be viewed as a guide not as the final word. If your code looks better with a violation then its probably best left alone.
여러분의 패치를 제출 전에 패치 스타일 체커로 체크하라.(scripts/checkpatch.pl) 스타일 체커는 최종본이 아닌 단지 안내자로 봐야 한다. 여러분의 코드가 좀 위반을 했더라도 더 좋아보인다면 그것을 남겨 놓는 것이 아마 더 잘하는 일일 것이다.
The checker reports at three levels:
체커는 3가지 레벨로 보고한다.
You should be able to justify all violations that remain in your patch.
여러분은 여러분의 패치에 남아 있는 모든 위반사항을 정당화 시킬 수 있어야 한다.
2) #ifdefs are ugly
2) #ifdefs은 좋지않다.
Code cluttered with ifdefs is difficult to read and maintain. Don't do it. Instead, put your ifdefs in a header, and conditionally define 'static inline' functions, or macros, which are used in the code. Let the compiler optimize away the "no-op" case.
ifdef로 어지럽혀져 있는 코드는 읽고 유지보수하기가 어렵다. 그렇게 하지마라. 대신에 여러분의 ifdef들을 하나의 헤더로 넣고 조건에 따라 'static inline'함수나 매크로로 두어라. 컴파일러가 "no-op"의 경우를 최적하하여 없애버리도록 하자.
Simple example, of poor code:
dev = alloc_etherdev (sizeof(struct funky_private)); if (!dev)
Cleaned-up example: return -ENODEV;
#ifdef CONFIG_NET_FUNKINESS init_funky_net(dev); #endif (in header)
#ifndef CONFIG_NET_FUNKINESS static inline void init_funky_net (struct net_device *d) {} #endif
(in the code itself)
dev = alloc_etherdev (sizeof(struct funky_private)); if (!dev)
3) 'static inline' is better than a macro return -ENODEV;
init_funky_net(dev); 3) 'static inline'은 매크로보다 더 선호된다.
Static inline functions are greatly preferred over macros. They provide type safety, have no length limitations, no formatting limitations, and under gcc they are as cheap as macros.
Static inline 함수들이 매크로보다는 훨씬 선호된다. Static inline 함수들은 형 안정성(type safety)을 제공하며 어떤 길이제한이나 형식 제한도 있지 않으며 gcc의 경우 매크로만큼이나 가볍다.
Macros should only be used for cases where a static inline is clearly suboptimal [there a few, isolated cases of this in fast paths], or where it is impossible to use a static inline function [such as string-izing].
매크로들은 static inline이 분명히 suboptimalTODO 할 경우나 static inline 함수를 사용할 수 없는 경우예를들어 문자열화(string-izing)에만 사용되어져야 한다.
'static inline' is preferred over 'static inline', 'extern inline', and 'extern inline'.
'staic inlinke'이 'static inline', 'extern inline', 'extern inline'보다 선호 된다.
4) Don't over-design.
4) 너무 멀리 보는 설계는 피하자.
Don't try to anticipate nebulous future cases which may or may not be useful: "Make it as simple as you can, and no simpler."
유용하게 될지, 그렇지 않을 지도 모르는 불확실한 미래를 예측하려고 시도하지 마라. "할수 있는 한 최대한 간단하게 만들어라."
SECTION 3 - REFERENCES
Andrew Morton, "The perfect patch" (tpp).
Jeff Garzik, "Linux kernel patch submission format".
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/2005/03/31/> <http://www.kroah.com/log/2005/07/08/> <http://www.kroah.com/log/2005/10/19/> <http://www.kroah.com/log/2006/01/11/>
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
Kernel Documentation/CodingStyle:
Linus Torvalds's mail on the canonical patch format:
'Programming > Linux_Kernel' 카테고리의 다른 글
| Playing with ptrace, Part II (0) | 2008.11.14 |
|---|---|
| paper on debugging kernel oops or hang (0) | 2008.11.12 |
| diff를 이용한 kernel patch 만들기 (0) | 2008.11.12 |
| Linux Kernel 에 대한 문서들 (0) | 2008.11.12 |
| ptrace 번역 (0) | 2008.11.11 |