patch 게시

review를 위해 게시할 시점

작업이 community review를 받고 최종적으로 mainline kernel에 포함될 준비가 되는 시점이 온다. Kernel development community에는 patch 게시를 위한 관례와 절차가 있으며 이를 따르면 모든 참여자의 작업이 쉬워진다. 추가 정보는 Documentation/process/submitting-patches.rst와 Documentation/process/submit-checklist.rst에 있다.

Patch가 완전히 준비되기 전에는 공개하지 않으려는 유혹이 있다. 단순한 patch라면 문제가 없지만 복잡한 작업은 완료 전에 community feedback을 받는 이점이 크다. 진행 중인 작업을 게시하거나 관심 있는 개발자가 언제든 따라올 수 있도록 git tree를 공개하는 방법을 고려한다.

아직 merge할 준비가 되지 않은 code를 게시할 때에는 그 사실을 message에 분명히 적는다. 남은 주요 작업과 알려진 문제도 설명한다. 완성도가 낮다고 알려진 patch를 보는 사람은 줄겠지만, review하는 사람은 작업을 올바른 방향으로 이끄는 데 도움을 줄 수 있다는 전제로 참여한다.

작업이 review 가능한 상태가 되면 kernel community의 관례에 맞춰 mailing list에 patch를 게시합니다. 너무 늦게 완성품만 공개하면 설계 변경 비용이 커지므로 큰 project는 RFC와 초기 revision으로 방향을 먼저 확인합니다.

게시 전에 code가 compile되고 의도한 동작을 test했으며 알려진 warning과 style 문제를 정리해야 합니다. 미완성 부분이 있다면 숨기지 말고 cover letter나 changelog에 범위와 남은 작업을 명확히 적습니다.

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
:Translator: Federico Vaga <[email protected]>

.. _it_development_posting:

Pubblicare modifiche
====================

Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
presentato alla comunità per una revisione ed eventualmente per la sua
inclusione nel ramo principale del kernel.  Com'era prevedibile,
la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
e di procedure per la pubblicazione delle patch; seguirle renderà la vita
più facile a tutti quanti.  Questo documento cercherà di coprire questi
argomenti con un ragionevole livello di dettaglio; più informazioni possono
essere trovare nella cartella 'Documentation', nei file
:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.


Quando pubblicarle
------------------

C'è sempre una certa resistenza nel pubblicare patch finché non sono
veramente "pronte".  Per semplici patch questo non è un problema.
Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
dai riscontri che la comunità può darvi prima che completiate il lavoro.
Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
preparare un ramo git disponibile agli sviluppatori interessati, cosicché
possano stare al passo col vostro lavoro in qualunque momento.

Quando pubblicate del codice che non è considerato pronto per l'inclusione,
è bene che lo diciate al momento della pubblicazione.  Inoltre, aggiungete
informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
Poche persone guarderanno delle patch che si sa essere fatte a metà,
ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
sviluppo nella giusta direzione.

patch를 만들기 전 정리

• 가능한 범위까지 code를 시험한다. Kernel debugging tool을 사용하고 합리적인 configuration option 조합에서 build되는지 확인하며 cross-compiler로 여러 architecture를 build한다.
• Kernel coding style guideline을 준수하는지 확인한다.
• 성능에 영향이 있다면 변화의 영향 또는 이점을 보여 주는 benchmark를 실행하고 결과 요약을 patch에 포함한다.
• Code를 게시할 권리가 있는지 확인한다. 고용주를 위해 수행한 작업이라면 고용주가 권리를 가질 가능성이 높고 GPL에 따른 공개에 동의해야 한다.

일반적으로 code를 게시하기 전에 조금 더 생각하는 데 쓴 시간은 곧 보상받는다.

제출할 tree와 base commit을 선택하고 변경을 논리적인 단위로 나눕니다. 관련 없는 cleanup과 기능 변경을 한 patch에 섞지 않아야 reviewer가 목적과 위험을 독립적으로 판단하고 필요한 commit만 적용하거나 되돌릴 수 있습니다.

각 patch는 독립적으로 build 가능하고 series 안의 앞선 patch에만 의존해야 합니다. local debug code, 임시 print, generated file 누락과 private branch 전용 dependency가 없는지 확인합니다.

Prima di creare patch
---------------------

Ci sono un certo numero di cose che dovreste fare prima di considerare
l'invio delle patch alla comunità di sviluppo.  Queste cose includono:

 - Verificare il codice fino al massimo che vi è consentito. Usate gli
   strumenti di debug del kernel, assicuratevi che il kernel compili con
   tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
   per compilare il codice per differenti architetture, eccetera.

 - Assicuratevi che il vostro codice sia conforme alla linee guida del
   kernel sullo stile del codice.

 - La vostra patch ha delle conseguenze in termini di prestazioni?
   Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
   impatto (anche positivo); un riassunto dei risultati dovrebbe essere
   incluso nella patch.

 - Siate certi d'avere i diritti per pubblicare il codice.  Se questo
   lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
   questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
   con una licenza GPL

Come regola generale, pensarci un po' di più prima di inviare il codice
ripaga quasi sempre lo sforzo.

base, series와 patch 파일 준비

게시할 patch를 준비하는 데 예상보다 많은 작업이 들 수 있지만 여기서 시간을 아끼려는 시도는 단기적으로도 좋지 않다.

Patch는 특정 kernel version을 기준으로 만들어야 한다. 일반적으로 Linus의 git tree에 있는 현재 mainline을 기준으로 하되 mainline의 임의 지점에서 branch하지 말고 stable release 또는 -rc release처럼 널리 알려진 release point에서 시작한다.

더 넓은 test와 review를 위해 -mm, linux-next 또는 subsystem tree를 기준으로 version을 만들어야 할 때도 있다. Patch 영역과 다른 개발 상황에 따라 이런 tree를 기준으로 하면 conflict 해결과 API change 대응에 상당한 작업이 필요할 수 있다.

아주 단순한 변경만 single patch로 만들고 나머지는 논리적인 change series로 구성한다. Patch 분할은 경험이 필요한 작업이지만 다음 원칙이 도움이 된다.

• 게시하는 series는 working revision control system에 기록된 개발 과정과 거의 확실히 다르다. Community가 원하는 것은 최종 change를 이해하기 좋게 나눈 discrete하고 self-contained한 단위이지 개발자가 그 결과에 도달한 경로가 아니다.
• 논리적으로 독립된 change마다 별도 patch를 만든다. Structure field 하나 추가처럼 작거나 큰 driver 추가처럼 실제 code 양이 많을 수 있지만 개념적으로 작고 한 줄로 설명할 수 있어야 한다. 각 patch는 독립적으로 review하고 설명대로 동작하는지 검증할 수 있는 구체적인 change를 수행해야 한다.
• 서로 다른 종류의 change를 한 patch에 섞지 않는다. Critical security bug fix, structure 재배치, code formatting을 한 patch에 넣으면 review에서 지나쳐 중요한 fix까지 잃을 수 있다.
• 각 patch를 적용한 뒤 kernel이 build되고 정상 동작해야 한다. git bisect로 regression을 찾을 때 series 중간까지만 적용되는 경우가 흔하다. 중간 kernel이 깨지면 문제를 찾는 개발자와 user의 작업이 어려워진다.
• 지나치게 잘게 나누지도 않는다. 한 개발자가 file 하나의 edit를 500개 patch로 보낸 사례처럼 분할 자체가 review를 방해할 수 있다. 하나의 logical change라면 single patch가 상당히 커도 괜찮다.
• 새 infrastructure를 여러 patch로 추가한 뒤 마지막 patch에서야 전부 활성화하는 구성을 가능하면 피한다. Regression이 생기면 bisect는 실제 bug가 앞 patch에 있어도 마지막 enable patch를 원인으로 지목한다. 새 code를 추가하는 patch는 가능한 한 즉시 그 code를 활성화해야 한다.

완벽한 patch series를 만드는 과정은 실제 기능 구현이 끝난 뒤에도 많은 시간과 사고를 요구해 답답할 수 있지만 올바르게 수행하면 가치 있는 작업이다.

patch는 current maintainer tree를 올바른 base로 삼아 생성하며 오래된 release나 임의 distribution tree 위 변경을 그대로 보내지 않습니다. `git format-patch`는 commit metadata와 series 순서를 보존하고 cover letter를 생성하는 표준 도구입니다.

큰 변경은 review 가능한 작은 patch series로 나누되 중간 상태가 깨지지 않게 순서를 설계합니다. revision 번호와 이전 posting 대비 변경점을 기록하고, series 전체가 최신 base에 clean하게 적용되는지 다시 확인합니다.

Preparazione di una patch
-------------------------

La preparazione delle patch per la pubblicazione può richiedere una quantità
di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
di risparmiare tempo in questa fase, anche sul breve periodo.

Le patch devono essere preparate per una specifica versione del kernel.
Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
così come lo si trova nei sorgenti git di Linus.  Quando vi basate sul ramo
principale, cominciate da un punto di rilascio ben noto - uno stabile o
un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
a caso.

Per facilitare una revisione e una verifica più estesa, potrebbe diventare
necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
sottosistema.  Basare questa patch sui suddetti sorgenti potrebbe richiedere
un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
della vostra patch e da quello che succede altrove nel kernel.

Solo le modifiche più semplici dovrebbero essere preparate come una singola
patch; tutto il resto dovrebbe essere preparato come una serie logica di
modifiche.  Spezzettare le patch è un po' un'arte; alcuni sviluppatori
passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
Ci sono alcune regole spannometriche, che comunque possono aiutare
considerevolmente:

 - La serie di patch che pubblicherete, quasi sicuramente, non sarà
   come quella che trovate nel vostro sistema di controllo di versione.
   Invece, le vostre modifiche dovranno essere considerate nella loro forma
   finale, e quindi separate in parti che abbiano un senso.  Gli sviluppatori
   sono interessati in modifiche che siano discrete e indipendenti, non
   alla strada che avete percorso per ottenerle.

 - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
   patch separata.  Queste modifiche possono essere piccole ("aggiunto un
   campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
   per esempio), ma dovrebbero essere concettualmente piccole da permettere
   una descrizione in una sola riga.  Ogni patch dovrebbe fare modifiche
   specifiche che si possano revisionare indipendentemente e di cui si possa
   verificare la veridicità.

 - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
   modifiche nella stessa patch.  Se una modifica corregge un baco critico
   per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
   ci sono buone probabilità che venga ignorata e che la correzione importante
   venga persa.

 - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
   correttamente; se la vostra serie di patch si interrompe a metà il
   risultato dovrebbe essere comunque un kernel funzionante.  L'applicazione
   parziale di una serie di patch è uno scenario comune nel quale il
   comando "git bisect" viene usato per trovare delle regressioni; se il
   risultato è un kernel guasto, renderete la vita degli sviluppatori più
   difficile così come quella di chi s'impegna nel nobile lavoro di
   scovare i problemi.

 - Però, non strafate.  Una volta uno sviluppatore pubblicò una serie di 500
   patch che modificavano un unico file - un atto che non lo rese la persona
   più popolare sulla lista di discussione del kernel.  Una singola patch
   può essere ragionevolmente grande fintanto che contenga un singolo
   cambiamento *logico*.

 - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
   come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
   finché l'ultima patch della serie non abilita tutto quanto.  Quando è
   possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
   regressioni, "bisect" indicherà quest'ultima patch come causa del
   problema anche se il baco si trova altrove.  Possibilmente, quando una
   patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.

Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
già stato fatto.  Quando ben fatto, comunque, è tempo ben speso.

commit message와 tag

각 patch는 목적을 빠르고 명확하게 전달하는 message로 format해야 한다.

• 선택적인 From line: 다른 사람의 patch를 email로 전달할 때 author를 나타낸다. 확신이 없을 때 추가해도 해가 없다.
• Patch가 하는 일을 설명하는 한 줄 summary: 다른 맥락 없이 읽어도 범위를 알 수 있어야 하며 short-form changelog에 나타난다. 보통 subsystem 이름을 먼저 쓰고 patch 목적을 적는다.
• Blank line 뒤의 상세 설명: 필요한 만큼 길게 작성하며 patch가 무엇을 하고 왜 kernel에 적용해야 하는지 설명한다.
• 하나 이상의 tag line: 최소한 patch author의 Signed-off-by 한 줄이 필요하다.

gpio: fix build on CONFIG_GPIO_SYSFS=n

이 요소를 합쳐 patch changelog를 만든다. Changelog는 subsystem maintainer와 reviewer, 다른 kernel로 backport할지 판단하는 distributor와 maintainer, bug 원인을 찾는 사람, kernel 변화가 궁금한 user 등 다양한 독자가 읽는다. 필요한 정보를 직접적이고 간결하게 전달해야 한다.

Summary line은 한 줄 제한 안에서 change의 효과와 동기를 최대한 잘 설명한다. 상세 설명은 이를 확장하고 필요한 추가 정보를 제공한다. Bug fix라면 가능할 때 bug를 만든 commit의 ID와 title을 함께 적는다. 특정 log 또는 compiler output과 관련된 문제면 같은 문제를 검색하는 사람을 위해 output을 포함한다.

뒤 patch의 change를 지원하기 위한 patch라면 그 사실을 말한다. Internal API를 바꾼다면 change와 다른 developer가 대응할 방법을 자세히 적는다. Changelog를 읽을 모든 사람의 입장을 고려할수록 changelog와 kernel 전체가 좋아진다.

Changelog는 revision control system에 commit할 때도 같은 text를 사용해야 한다. 그 뒤 unified(-u) format의 patch 본문이 온다. diff의 -p option을 사용하면 change에 function 이름이 연결되어 읽기 쉬워진다.

Tag는 patch가 만들어진 배경을 기록한다. 자세한 규칙은 Documentation/process/submitting-patches.rst에 있고 여기서는 핵심을 요약한다.

Fixes는 현재 patch가 수정하는 문제를 도입한 이전 commit을 가리킨다.

Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

Link는 patch로 이어진 이전 discussion이나 구현한 specification처럼 추가 배경과 상세 정보가 있는 web page를 연결한다.

Link: https://example.com/somewhere.html  optional-other-stuff

Chief Penguin의 지침에 따라 commit 자체에 없는 유용한 정보로 연결될 때만 Link를 추가한다. URL이 patch로 수정하는 public bug report라면 Closes를 사용한다.

Closes: https://example.com/issues/1234  optional-other-stuff

일부 bug tracker는 해당 tag가 있는 commit이 적용되면 issue를 자동으로 닫는다. Mailing list를 감시하는 bot도 tag를 추적해 동작할 수 있다. Private bug tracker와 유효하지 않은 URL은 사용할 수 없다.

tag: Full Name <email address>  optional-other-stuff

Cc, Reported-by, Suggested-by를 제외한 tag에는 기재되는 사람의 명시적 허락이 필요하다. 세 tag는 lore archive 또는 commit history에서 그 사람이 같은 이름과 email로 Linux kernel에 기여했고, Reported-by와 Suggested-by의 경우 public에서 신고 또는 제안했다면 묵시적 허락으로 충분하다.

bugzilla.kernel.org는 이 의미에서 public place지만 그곳에 쓴 email address는 private다. 그 사람이 이전 기여에서 같은 address를 사용하지 않았다면 tag로 공개해서는 안 된다.

subject는 변경 영역과 핵심 행동을 짧게 표현하고 본문은 해결할 문제, 현재 동작이 잘못된 이유, 선택한 해법과 사용자 영향을 설명합니다. code가 무엇을 하는지는 diff에서 보이므로 commit message는 왜 필요한지와 trade-off를 남겨야 합니다.

`Fixes:`는 문제가 시작된 commit을 짧은 hash와 정확한 subject로 가리키고, 관련 report나 issue는 적절한 reference tag로 연결합니다. 모든 제출에는 Developer's Certificate of Origin을 확인하는 `Signed-off-by:`가 필요합니다.

`Reported-by`, `Suggested-by`, `Co-developed-by`, `Reviewed-by`, `Acked-by`, `Tested-by` 같은 attribution tag는 실제 기여와 명시적 동의를 정확히 기록합니다. review나 test를 받지 않았는데 tag를 임의로 추가해서는 안 되며 `Co-developed-by` 뒤에는 해당 개발자의 `Signed-off-by`가 바로 이어져야 합니다.

Formattazione delle patch e i changelog
---------------------------------------

Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
ma il lavoro non è davvero finito.  Ogni patch deve essere preparata con
un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
il suo scopo.  Per ottenerlo, ogni patch sarà composta dai seguenti elementi:

 - Un campo opzionale "From" col nome dell'autore della patch.  Questa riga
   è necessaria solo se state passando la patch di qualcun altro via email,
   ma nel dubbio non fa di certo male aggiungerlo.

 - Una descrizione di una riga che spieghi cosa fa la patch.  Questo
   messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
   scopo della patch senza altre informazioni.  Questo messaggio,
   solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
   seguito dallo scopo della patch.  Per esempio:

   ::

	gpio: fix build on CONFIG_GPIO_SYSFS=n

 - Una riga bianca seguita da una descrizione dettagliata della patch.
   Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
   cosa fa e perché dovrebbe essere aggiunta al kernel.

 - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
   col nome dall'autore della patch.  Queste etichette verranno descritte
   meglio più avanti.

Gli elementi qui sopra, assieme, formano il changelog di una patch.
Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
vale la pena spendere qualche parola in più al riguardo.  Quando scrivete
un changelog dovreste tenere ben presente che molte persone leggeranno
le vostre parole.  Queste includono i manutentori di un sotto-sistema, e i
revisori che devono decidere se la patch debba essere inclusa o no,
le distribuzioni e altri manutentori che cercano di valutare se la patch
debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
chiederanno se la patch è la causa di un problema che stanno cercando,
gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
Un buon changelog fornisce le informazioni necessarie a tutte queste
persone nel modo più diretto e conciso possibile.

A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
modifica e la motivazione della patch nel modo migliore possibile nonostante
il limite di una sola riga.  La descrizione dettagliata può spiegare meglio
i temi e fornire maggiori informazioni.  Se una patch corregge un baco,
citate, se possibile, il commit che lo introdusse (e per favore, quando
citate un commit aggiungete sia il suo identificativo che il titolo),
Se il problema è associabile ad un file di log o all' output del compilatore,
includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
problema.  Se la modifica ha lo scopo di essere di supporto a sviluppi
successivi, ditelo.  Se le API interne vengono cambiate, dettagliate queste
modifiche e come gli altri dovrebbero agire per applicarle.  In generale,
più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).

Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
di commit in un sistema di controllo di versione.  Sarà seguito da:

 - La patch stessa, nel formato unificato per patch ("-u").  Usare
   l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
   si riferisce, rendendo il risultato più facile da leggere per gli altri.

Le etichette sopracitate danno un'idea di come una patch prende vita e sono
descritte nel dettaglio nel documento
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
Qui di seguito un breve riassunto.

Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::

       Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
maggiori informazioni, per esempio una discussione avvenuta precedentemente
circa il baco risolto dalla patch, oppure un documento con le specifiche
implementate dalla patch::

       Link: https://example.com/somewhere.html  optional-other-stuff

Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
alla più recente discussione pubblica. A volte questo è fatto automaticamente da
alcuni strumenti come b4 or un *hook* git come quello descritto qui
'Documentation/translations/it_IT/maintainer/configure-git.rst'


Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,
allora usate l'etichetta "Closes:"::

       Closes: https://example.com/issues/1234  optional-other-stuff

Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere
automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni
automatismi che monitorano la liste di discussione possono anche tracciare
queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono
proibiti.

Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo
sviluppo della patch. Tutte queste etichette seguono il formato::

	tag: Full Name <email address>  optional-other-stuff

Le etichette in uso più comuni sono:

 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
   di sottomettere la patch per l'integrazione nel kernel.  Questo rappresenta
   il consenso verso il certificato d'origine degli sviluppatori, il testo
   completo potrà essere trovato in
   :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
   Codice che non presenta una firma appropriata non potrà essere integrato.

 - Co-developed-by: indica che la patch è stata cosviluppata da diversi
   sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
   associato all'etichetta From:) quando più persone lavorano ad una patch.
   Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
   del corrispondente coautore.  Maggiori dettagli ed esempi sono disponibili
   in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.

 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
   del codice in oggetto) all'integrazione della patch nel kernel.

 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
   funzionante.

 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
   maggiori dettagli leggete la dichiarazione dei revisori in
   :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`

 - Reported-by: menziona l'utente che ha riportato il problema corretto da
   questa patch; quest'etichetta viene usata per dare credito alle persone che
   hanno verificato il codice e ci hanno fatto sapere quando le cose non
   funzionavano correttamente. Questa etichetta dovrebbe essere seguita da
   quella Closes: con un indirizzo al rapporto, a meno che questo non sia
   disponibile sul web. L'etichetta Link: può essere usata in alternativa a
   Closes: se la patch corregge solo in parte il problema riportato nel
   rapporto.

   Se esiste un rapporto disponibile sul web, allora
   L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.

 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
   l'opportunità di commentarla.

State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può
essere aggiunta senza il permesso esplicito della persona menzionata. Il più
delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente
se il baco è stato riportato in una comunicazione privata.

전송 전 검사, 수신자와 threading

Mailer가 patch를 손상하지 않는지 확인한다. Client가 불필요한 whitespace change나 line wrapping을 적용하면 수신 측에서 patch가 적용되지 않고 상세 review도 받지 못할 가능성이 높다. 조금이라도 의심되면 자신에게 보내서 원형 그대로 도착하는지 확인한다. Client별 설정은 Documentation/process/email-clients.rst를 참조한다.

Patch를 scripts/checkpatch.pl로 검사하고 지적 사항을 검토한다. checkpatch.pl에는 kernel patch 형태에 관한 많은 경험이 반영되어 있지만 사람보다 현명한 것은 아니다. Warning을 고치는 것이 code를 더 나쁘게 만든다면 그대로 따르지 않는다.

scripts/checkpatch.pl <patch-file>

Patch는 항상 plain text로 보내고 attachment로 보내지 않는다. Reviewer가 reply에서 patch 일부를 quote하기 어렵기 때문이다. Patch를 message body에 직접 넣는다.

Patch에 관심을 가질 수 있는 사람에게 모두 사본을 보내는 것이 중요하다. 다른 project와 달리 kernel은 너무 적게 보내는 것보다 다소 많이 보내는 쪽을 권장한다. 관련자가 mailing list에서 알아서 볼 것이라고 가정하지 않는다.

• 영향받는 subsystem의 maintainer. MAINTAINERS file에서 먼저 찾는다.
• 같은 영역에서 작업했거나 현재 작업 중일 수 있는 다른 developer. git history로 대상 file을 수정한 사람을 확인할 수 있다.
• Bug report 또는 feature request에 대한 응답이면 original poster.
• 관련 mailing list. 해당 list가 없다면 linux-kernel list.
• Bug fix가 다음 stable update에 들어가야 한다면 [email protected]에도 보내고 patch tag에 Cc: [email protected]를 추가한다. Mainline merge 시 stable team이 notification을 받는다.

Recipient를 고를 때 최종적으로 누가 patch를 받아 merge할 것인지 생각해야 한다. Linus Torvalds에게 직접 보내 merge를 요청할 수는 있지만 일반적인 경로는 아니다. Linus는 매우 바쁘고 각 영역은 subsystem maintainer가 관리한다. 보통 그 maintainer가 patch를 merge하게 해야 한다. 명확한 maintainer가 없다면 Andrew Morton이 최후의 patch target이 되는 경우가 많다.

Patch에는 좋은 subject line이 필요하다. 표준적인 형식은 다음과 같다.

[PATCH nn/mm] subsys: one-line description of the patch

nn은 series 안의 patch 순번, mm은 전체 patch 수, subsys는 영향받는 subsystem 이름이다. 독립된 single patch라면 nn/mm을 생략할 수 있다.

큰 patch series에는 part zero로 소개 설명을 보내는 관례가 있다. 항상 지켜지는 것은 아니며 cover letter의 정보는 kernel changelog에 들어가지 않는다. 각 patch 자체에 완전한 changelog가 있어야 한다.

Multi-part patch의 두 번째 이후 message는 일반적으로 첫 part에 reply하여 수신 측에서 같은 thread로 묶이게 한다. git과 quilt에는 올바른 threading으로 series를 보내는 command가 있다. 긴 series를 git으로 보낼 때에는 지나치게 깊은 nesting을 만들지 않도록 --chain-reply-to option을 피한다.

전송 전 `checkpatch.pl`, build와 관련 test를 다시 실행하고 생성된 mail을 직접 읽어 diff와 whitespace, recipient, subject prefix가 올바른지 확인합니다. HTML이나 attachment가 아니라 inline plain-text mail로 보내야 합니다.

`scripts/get_maintainer.pl`과 `MAINTAINERS`로 subsystem list와 담당자를 찾고 reviewer와 이전 논의 참여자를 Cc에 유지합니다. patch는 관련 list로 공개 전송하며 private mail만으로 mainline review를 대신하지 않습니다.

subject에는 `[PATCH]`, subsystem, revision과 series 번호를 일관되게 표시하고 cover letter와 각 patch가 하나의 thread가 되게 보냅니다. 재전송 시 새 revision 전체를 보내고 이전 thread 링크와 변경 내역을 포함해 reviewer가 차이를 따라갈 수 있게 합니다.

Inviare la modifica
-------------------

Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
dovreste aver cura:

 - Siete sicuri che il vostro programma di posta non corromperà le patch?
   Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
   dai programmi di posta non funzioneranno per chi le riceve, e spesso
   non verranno nemmeno esaminate in dettaglio.  Se avete un qualsiasi dubbio,
   inviate la patch a voi stessi e verificate che sia integra.

   :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
   contiene alcuni suggerimenti utili sulla configurazione dei programmi
   di posta al fine di inviare patch.

 - Siete sicuri che la vostra patch non contenga sciocchi errori?  Dovreste
   sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
   problemi riportati.  Per favore tenete ben presente che checkpatch.pl non è
   più intelligente di voi, nonostante sia il risultato di un certa quantità di
   ragionamenti su come debba essere una patch per il kernel.  Se seguire
   i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.

Le patch dovrebbero essere sempre inviate come testo puro.  Per favore non
inviatele come allegati; questo rende molto più difficile, per i revisori,
citare parti della patch che si vogliono commentare.  Invece, mettete la vostra
patch direttamente nel messaggio.

Quando inviate le patch, è importante inviarne una copia a tutte le persone che
potrebbero esserne interessate.  Al contrario di altri progetti, il kernel
incoraggia le persone a peccare nell'invio di tante copie; non presumente che
le persone interessate vedano i vostri messaggi sulla lista di discussione.
In particolare le copie dovrebbero essere inviate a:

 - I manutentori dei sottosistemi affetti della modifica.  Come descritto
   in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
   di queste persone.

 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
   quelli che potrebbero lavorarci proprio ora.  Usate git potrebbe essere
   utile per vedere chi altri ha modificato i file su cui state lavorando.

 - Se state rispondendo a un rapporto su un baco, o a una richiesta di
   funzionalità, includete anche gli autori di quei rapporti/richieste.

 - Inviate una copia alle liste di discussione interessate, o, se nient'altro
   è adatto, alla lista linux-kernel

 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
   nel prossimo rilascio stabile.  Se è così, la lista di discussione
   [email protected] dovrebbe riceverne una copia.  Aggiungete anche
   l'etichetta "Cc: [email protected]" nella patch stessa; questo
   permetterà alla squadra *stable* di ricevere una notifica quando questa
   correzione viene integrata nel ramo principale.

Quando scegliete i destinatari della patch, è bene avere un'idea di chi
pensiate che sia colui che, eventualmente, accetterà la vostra patch e
la integrerà.  Nonostante sia possibile inviare patch direttamente a
Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
strada migliore da seguire.  Linus è occupato, e ci sono dei manutentori di
sotto-sistema che controllano una parte specifica del kernel.  Solitamente,
vorreste che siano questi manutentori ad integrare le vostre patch.  Se non
c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.

Le patch devono avere anche un buon oggetto.  Il tipico formato per l'oggetto
di una patch assomiglia a questo:

::

	[PATCH nn/mm] subsys: one-line description of the patch

dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
nella serie, e "subsys" è il nome del sottosistema interessato.  Chiaramente,
nn/mm può essere omesso per una serie composta da una singola patch.

Se avete una significative serie di patch, è prassi inviare una descrizione
introduttiva come parte zero.  Tuttavia questa convenzione non è universalmente
seguita; se la usate, ricordate che le informazioni nell'introduzione non
faranno parte del changelog del kernel.  Quindi per favore, assicuratevi che
ogni patch abbia un changelog completo.

In generale, la seconda parte e quelle successive di una patch "composta"
dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
come un unico *thread*.  Strumenti come git e quilt hanno comandi per inviare
gruppi di patch con la struttura appropriata.  Se avete una serie lunga
e state usando git, per favore state alla larga dall'opzione --chain-reply-to
per evitare di creare un annidamento eccessivo.