Kernel patch 제출: 필수 안내서

현재 source tree와 subsystem workflow 확인

Linux kernel patch를 제출하려는 개인이나 회사는 익숙하지 않은 절차를 어렵게 느낄 수 있습니다. 이 문서는 patch가 accept될 가능성을 크게 높이는 간결한 지침을 모읍니다.

개발 절차는 `Documentation/translations/it_IT/process/development-process.rst`, 제출 전 점검표는 `Documentation/translations/it_IT/process/submit-checklist.rst`를 참고합니다. 이 원문은 Device Tree binding patch에도 `Documentation/translations/it_IT/process/submitting-patches.rst`를 가리키며, subsystem별 workflow는 `Documentation/translations/it_IT/process/maintainer-handbooks.rst`에서 확인합니다.

이 문서는 `git`으로 patch를 준비할 수 있다고 가정합니다. 익숙하지 않다면 먼저 익히는 것이 kernel 개발을 훨씬 수월하게 합니다.

최신 kernel source repository가 없다면 mainline repository를 clone합니다.

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

다만 mainline을 직접 base로 쓰지 않을 수 있습니다. Maintainer 대부분은 자체 tree 기준 patch를 원하므로 원문의 표기대로 `MAINTANERS`에서 해당 subsystem의 `T:` entry를 찾고, 나열되지 않았다면 maintainer에게 묻습니다.

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

:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
:Translator: Federico Vaga <[email protected]>

.. _it_submittingpatches:

Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
=========================================================================

Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
una certa familiarità col "sistema".  Questo testo è una raccolta di
suggerimenti che aumenteranno significativamente le probabilità di vedere le
vostre patch accettate.

Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
dettagli su come funziona il processo di sviluppo del kernel leggete
Documentation/translations/it_IT/process/development-process.rst. Leggete anche
Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
punti da verificare prima di inviare del codice.
Per delle patch relative alle associazioni per Device Tree leggete
Documentation/translations/it_IT/process/submitting-patches.rst.

Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
Se non siete pratici di ``git``, allora è bene che lo impariate;
renderà la vostra vita di sviluppatore del kernel molto più semplice.

I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
riguardo al loro modo di lavorare ed aspettative. Consultate
:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`

Ottenere i sorgenti attuali
---------------------------

Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
``git`` per ottenerli.  Vorrete iniziare col repositorio principale che può
essere recuperato col comando::

  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
principali del kernel.  La maggior parte dei manutentori hanno i propri
sorgenti e desiderano che le patch siano preparate basandosi su di essi.
Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
in cui i sorgenti da usare non siano elencati il quel file.

.. _it_describe_changes:

Problem, impact, trade-off와 solution 설명

한 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 54a4f0239f2e

Descrivete le vostre modifiche
------------------------------

Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
nuova funzionalità da 5000 righe di codice.  Convincete i revisori che vale
la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
al primo paragrafo.

Descrivete ciò che sarà visibile agli utenti.  Chiari incidenti nel sistema
e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
Anche se il problema è stato scoperto durante la revisione del codice,
descrivete l'impatto che questo avrà sugli utenti.  Tenete presente che
la maggior parte delle installazioni Linux usa un kernel che arriva dai
sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
singolarmente le patch dai sorgenti principali; quindi, includete tutte
le informazioni che possono essere utili a capire le vostre modifiche:
le circostanze che causano il problema, estratti da dmesg, descrizioni di
un incidente di sistema, prestazioni di una regressione, picchi di latenza,
blocchi, eccetera.

Quantificare le ottimizzazioni e i compromessi.  Se affermate di aver
migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
o la dimensione del file binario, includete dei numeri a supporto della
vostra dichiarazione.  Ma ricordatevi di descrivere anche eventuali costi
che non sono ovvi.  Solitamente le ottimizzazioni non sono gratuite, ma sono
un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
parla di ipotesi euristiche, fra differenti carichi.  Descrivete i lati
negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
valutare i costi e i benefici.

Una volta che il problema è chiaro, descrivete come lo risolvete andando
nel dettaglio tecnico.  È molto importante che descriviate la modifica
in un inglese semplice cosicché i revisori possano verificare che il codice si
comporti come descritto.

I manutentori vi saranno grati se scrivete la descrizione della patch in un
formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.

Risolvete solo un problema per patch.  Se la vostra descrizione inizia ad
essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
divisa. Leggete :ref:`it_split_changes`.

Quando inviate o rinviate una patch o una serie, includete la descrizione
completa delle modifiche e la loro giustificazione.  Non limitatevi a dire che
questa è la versione N della patch (o serie).  Non aspettatevi che i
manutentori di un sottosistema vadano a cercare le versioni precedenti per
cercare la descrizione da aggiungere.  In pratica, la patch (o serie) e la sua
descrizione devono essere un'unica cosa.  Questo aiuta i manutentori e i
revisori.  Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
le versioni precedenti della patch.

Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
comportamento.

Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1.  Per cortesia, aggiungete anche la breve riga
riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
Per esempio::

	Commit e21d2170f36602ae2708 ("video: remove unnecessary
	platform_set_drvdata()") removed the unnecessary
	platform_set_drvdata(), but left the variable "dev" unused,
	delete it.

Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
dell'identificativo SHA-1.  Il repositorio del kernel ha *molti* oggetti e
questo rende possibile la collisione fra due identificativi con pochi
caratteri.  Tenete ben presente che anche se oggi non ci sono collisioni con il
vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.

Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
riferimento. Se la patch è il risultato di una discussione avvenuta
precedentemente o di un documento sul presente sul web, allora fatevi
riferimento.

Per esempio, se la vostra patch corregge un baco potete aggiungere
quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
riferimento ad una discussione precedentemente avvenuta su una lista di
discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
questione.

Quando volete fare riferimento ad una lista di discussione, preferite il
servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
sufficiente usare il campo ``Message-ID``, presente nell'intestazione del
messaggio, senza parentesi angolari. Per esempio::

     Link: https://lore.kernel.org/[email protected]

Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
creato funzioni e che indirizzi verso il messaggio desiderato.

Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
condotto all'invio della patch.

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.

Se la vostra patch corregge un baco in un commit specifico, per esempio avete
trovato un problema usando ``git bisect``, per favore usate l'etichetta
'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
dalla riga riassuntiva.  Per esempio::

	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")

La seguente configurazione di ``git config`` può essere usata per formattare
i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
precedente::

	[core]
		abbrev = 12
	[pretty]
		fixes = Fixes: %h (\"%s\")

Un esempio::

       $ git log -1 --pretty=fixes 54a4f0239f2e
       Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")

.. _it_split_changes:

Logical change 분리와 style check

각 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/translations/it_IT/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을 설명할 수 있어야 한다.

Separate le vostre modifiche
----------------------------

Separate ogni **cambiamento logico** in patch distinte.

Per esempio, se i vostri cambiamenti per un singolo driver includono
sia delle correzioni di bachi che miglioramenti alle prestazioni,
allora separateli in due o più patch.  Se i vostri cambiamenti includono
un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
in due patch.

D'altro canto, se fate una singola modifica su più file, raggruppate tutte
queste modifiche in una singola patch.  Dunque, un singolo cambiamento logico
è contenuto in una sola patch.

Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
che siano facilmente comprensibili e che possano essere verificate dai revisori.
Ogni patch dovrebbe essere giustificabile di per sé.

Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
va bene.  Semplicemente scrivete una nota nella descrizione della patch per
farlo presente: **"this patch depends on patch X"**.

Quando dividete i vostri cambiamenti in una serie di patch, prestate
particolare attenzione alla verifica di ogni patch della serie; per ognuna
il kernel deve compilare ed essere eseguito correttamente.  Gli sviluppatori
che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
avete introdotto dei bachi.

Se non potete condensare la vostra serie di patch in una più piccola, allora
pubblicatene una quindicina alla volta e aspettate che vengano revisionate
ed integrate.


4) Verificate lo stile delle vostre modifiche
---------------------------------------------

Controllate che la vostra patch non violi lo stile del codice, maggiori
dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
letta.

Un'eccezione importante si ha quando del codice viene spostato da un file
ad un altro -- in questo caso non dovreste modificare il codice spostato
per nessun motivo, almeno non nella patch che lo sposta.  Questo separa
chiaramente l'azione di spostare il codice e il vostro cambiamento.
Questo aiuta enormemente la revisione delle vere differenze e permette agli
strumenti di tenere meglio la traccia della storia del codice.

Prima di inviare una patch, verificatene lo stile usando l'apposito
verificatore (scripts/checkpatch.pl).  Da notare, comunque, che il verificator
di stile dovrebbe essere visto come una guida, non come un sostituto al
giudizio umano.  Se il vostro codice è migliore nonostante una violazione
dello stile, probabilmente è meglio lasciarlo com'è.

Il verificatore ha tre diversi livelli di severità:
 - ERROR: le cose sono molto probabilmente sbagliate
 - WARNING: le cose necessitano d'essere revisionate con attenzione
 - CHECK: le cose necessitano di un pensierino

Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
nella vostra patch.

Patch recipient 선택

Maintained 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/translations/it_IT/process/security-bugs.rst를 참고한다.

Released kernel의 severe bug fix는 sign-off area에 Cc: [email protected]를 넣는다. 이는 email recipient가 아니다. Documentation/translations/it_IT/process/stable-kernel-rules.rst도 읽는다.

Userland-kernel interface change는 MAINTAINERS의 MAN-PAGES maintainer에게 man-page patch 또는 최소한 notification을 보내고 [email protected]도 CC한다.

• Kernel mailing listshttps://subspace.kernel.org

5) Selezionate i destinatari della vostra patch
-----------------------------------------------

Dovreste sempre inviare una copia della patch ai manutentori e alle liste di
discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al
file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del
codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il
percorso alle vostre patch). Se non riuscite a trovare un manutentore per il
sottosistema su cui state lavorando, allora Andrew Morton
([email protected]) sarà la vostra ultima possibilità.

La lista [email protected] dovrebbe essere usata per l'invio di tutte
le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni
sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi
scorrelati al tema della lista o a persone che non dovrebbero essere
interessate all'argomento.

Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
vostra serie di patch. La lista di discussione [email protected]
dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
di discussione che non sono interessate al vostro lavoro.

Molte delle liste di discussione relative al kernel vengono ospitate su
kernel.org; potete trovare un loro elenco alla pagina
https://subspace.kernel.org. Tuttavia, ci sono altre liste di discussione
ospitate altrove.

L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
Linux Torvalds.  Il suo indirizzo e-mail è <[email protected]>.
Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
meglio per -evitare di- inviargli e-mail.

Se avete una patch che corregge un baco di sicurezza che potrebbe essere
sfruttato, inviatela a [email protected].  Per bachi importanti, un breve
embargo potrebbe essere preso in considerazione per dare il tempo alle
distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
lista di discussione pubblica. Leggete anche
Documentation/process/security-bugs.rst.

Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::

  Cc: [email protected]

nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
delle e-mail).  In aggiunta a questo file, dovreste leggere anche
Documentation/translations/it_IT/process/stable-kernel-rules.rst.

Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
cosicché l'informazione possa trovare la sua strada nel manuale.  Le modifiche
all'API dello spazio utente dovrebbero essere inviate in copia anche a
[email protected].

Plain-text email, review response와 resend

Patch는 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를 요청하는 예외는 있다.

• git send-email tutorialhttps://git-send-email.io

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 summary

Mail traffic에서 patch를 구분하도록 subject에 [PATCH]를 붙인다. git send-email이 자동으로 처리한다.

Niente: MIME, links, compressione, allegati.  Solo puro testo
-------------------------------------------------------------

Linus e gli altri sviluppatori del kernel devono poter commentare
le modifiche che sottomettete.  Per uno sviluppatore è importante
essere in grado di "citare" le vostre modifiche, usando normali
programmi di posta elettronica, cosicché sia possibile commentare
una porzione specifica del vostro codice.

Per questa ragione tutte le patch devono essere inviate via e-mail
come testo. Il modo più facile, e quello raccomandato, è con ``git
send-email``.  Al sito https://git-send-email.io è disponibile una
guida interattiva sull'uso di ``git send-email``.

Se decidete di non usare ``git send-email``:

.. warning::

  Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
  attenti che il vostro programma non corrompa il contenuto con andate
  a capo automatiche.

La patch non deve essere un allegato MIME, compresso o meno.  Molti
dei più popolari programmi di posta elettronica non trasmettono un allegato
MIME come puro testo, e questo rende impossibile commentare il vostro codice.
Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
così la possibilità che il vostro allegato-MIME venga accettato.

Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
potrebbe chiedervi di rinviarle come allegato MIME.

Leggete Documentation/translations/it_IT/process/email-clients.rst
per dei suggerimenti sulla configurazione del programmi di posta elettronica
per l'invio di patch intatte.

Rispondere ai commenti di revisione
-----------------------------------

In risposta alla vostra email, quasi certamente i revisori vi
invieranno dei commenti su come migliorare la vostra patch.  Dovete
rispondere a questi commenti; ignorare i revisori è un ottimo modo per
essere ignorati.  Riscontri o domande che non conducono ad una
modifica del codice quasi certamente dovrebbero portare ad un commento
nel changelog cosicché il prossimo revisore potrà meglio comprendere
cosa stia accadendo.

Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
ringraziarli per il loro tempo.  Revisionare codice è un lavoro faticoso e che
richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
questo caso, rispondete con educazione e concentratevi sul problema che hanno
evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un
``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
le differenze rispetto a sottomissioni precedenti (vedere
:ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che
vi hanno fornito dei commenti per notificarle di eventuali nuove versioni.

Leggete Documentation/translations/it_IT/process/email-clients.rst per
le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
sulle liste di discussione.

.. _it_interleaved_replies:

Rispondere alle email in riga e riducendo la citazioni
------------------------------------------------------

Nelle discussioni riguardo allo sviluppo del kernel viene fortemente scoraggiato
l'uso di risposte in cima ai messaggi di posta elettronica. Rispondere in riga
rende le conversazioni molto più scorrevoli. Maggiori dettagli possono essere
trovati qui: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

Come spesso citato nelle liste di discussione::

  R: http://en.wikipedia.org/wiki/Top_post
  D: Dove posso trovare informazioni riguardo alle "risposte in cima"?
  R: Perché incasina il normale ordine con cui si legge un testo.
  D: Perché è così terribile rispondere in cima?
  R: Risposte in cima.
  Q: Qual è la cosa più fastidiosa nei messaggi di posta elettronica?

Allo stesso modo, per favore eliminate tutte le citazioni non necessarie per la
vostra risposta. Questo permette di trovare più facilmente le risposte, e
permette di risparmiare tempo e spazio. Per maggiori dettagli:
http://daringfireball.net/2007/07/on_top ::

  R: No.
  D: Dovrei includere un blocco di citazione dopo la mia risposta?

.. _it_resend_reminders:

Non scoraggiatevi - o impazientitevi
------------------------------------

Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
I revisori sono persone occupate e potrebbero non ricevere la vostra patch
immediatamente.

Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma
ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche
settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di
aver inviato le patch correttamente. Aspettate almeno una settimana prima di
rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
durante la finestra d'integrazione.

Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
aggiungendo la parola "RESEND" nel titolo::

    [PATCH Vx RESEND] sub/sys: Condensed patch summary

Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
della vostra patch, o serie di patch - "RESEND" si applica solo alla
sottomissione di patch, o serie di patch, che non hanno subito modifiche
dall'ultima volta che sono state inviate.

Aggiungete PATCH nell'oggetto
-----------------------------

Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
prefiggere il vostro oggetto con [PATCH].  Questo permette a Linus e agli
altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
discussioni.

``git send-email`` lo fa automaticamente.

Developer's Certificate of Origin 1.1

Developer's Certificate of Origin 1.1

여러 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을 나타낸다.

Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
----------------------------------------------------------------------

Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
quelle patch che per raggiungere lo stadio finale passano attraverso
diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
delle patch che vengono inviate per e-mail.

La firma è una semplice riga alla fine della descrizione della patch che
certifica che l'avete scritta voi o che avete il diritto di pubblicarla
come patch open-source.  Le regole sono abbastanza semplici: se potete
certificare quanto segue:

Il certificato d'origine dello sviluppatore 1.1
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Contribuendo a questo progetto, io certifico che:

        (a) Il contributo è stato creato interamente, o in parte, da me e che
            ho il diritto di inviarlo in accordo con la licenza open-source
            indicata nel file; oppure

        (b) Il contributo è basato su un lavoro precedente che, nei limiti
            della mia conoscenza, è coperto da un'appropriata licenza
            open-source che mi da il diritto di modificarlo e inviarlo,
            le cui modifiche sono interamente o in parte mie, in accordo con
            la licenza open-source (a meno che non abbia il permesso di usare
            un'altra licenza) indicata nel file; oppure

        (c) Il contributo mi è stato fornito direttamente da qualcuno che
            ha certificato (a), (b) o (c) e non l'ho modificata.

        (d) Capisco e concordo col fatto che questo progetto e i suoi
            contributi sono pubblici e che un registro dei contributi (incluse
            tutte le informazioni personali che invio con essi, inclusa la mia
            firma) verrà mantenuto indefinitamente e che possa essere
            ridistribuito in accordo con questo progetto o le licenze
            open-source coinvolte.

poi dovete solo aggiungere una riga che dice::

	Signed-off-by: Random J Developer <[email protected]>

usando il vostro vero nome (spiacenti, non si accettano
contributi anonimi). Questo verrà fatto automaticamente se usate
``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
includere "Signed-off-by", se usate ``git revert -s`` questo verrà
fatto automaticamente.

Alcune persone aggiungono delle etichette alla fine.  Per ora queste verranno
ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
per aggiungere dettagli circa la firma.

In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
parte di tutte quelle persone che si sono occupate della gestione e
del trasporto della patch. Queste però non sono state coinvolte nello
sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
**reale** che una patch a intrapreso dallo sviluppatore, fino al
manutentore, per poi giungere a Linus.

Acked-by, Cc와 Co-developed-by

Signed-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 user

Acked-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]>

Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
----------------------------------------------------

L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
sviluppo della patch, o che era nel suo percorso di consegna.

Se una persona non è direttamente coinvolta con la preparazione o gestione
della patch ma desidera firmare e mettere agli atti la loro approvazione,
allora queste persone possono chiedere di aggiungere al changelog della patch
una riga Acked-by:.

Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
quando quello stesso manutentore non ha contribuito né trasmesso la patch.

Acked-by: non è formale come Signed-off-by:.  Questo indica che la persona ha
revisionato la patch e l'ha trovata accettabile.  Per cui, a volte, chi
integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
(ma tenete presente che solitamente è meglio chiedere esplicitamente).

Acked-by: non indica l'accettazione di un'intera patch.  Per esempio, quando
una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
manutentore di uno di questi, significa che il manutentore accetta quella
parte di codice relativa al sottosistema che mantiene.  Qui dovremmo essere
giudiziosi.  Quando si hanno dei dubbi si dovrebbe far riferimento alla
discussione originale negli archivi della lista di discussione.

Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
fatto, potete aggiungere l'etichetta ``Cc:`` alla patch.  Questa è l'unica
etichetta che può essere aggiunta senza che la persona in questione faccia
alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
patch.  Questa etichetta documenta che terzi potenzialmente interessati sono
stati inclusi nella discussione.

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.  Dato
che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
coautore. Qui si applica la procedura di base per sign-off, in pratica
l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
l'ordine cronologico della storia della patch, indipendentemente dal fatto che
la paternità venga assegnata via From: o Co-developed-by:. Da notare che
l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.

Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
anche la persona (e indirizzo email) indicato nel From: dell'intestazione
dell'email.

Esempio di una patch sottomessa dall'autore in From:::

	<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]>

Esempio di una patch sottomessa dall'autore Co-developed-by:::

	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-by, Tested-by와 Reviewed-by

`Reported-by:`는 bug를 찾아 report한 사람에게 credit을 주고 다시 돕도록 장려합니다. Feature request에는 쓰지 않으며 private report였다면 사용 전에 permission을 받아야 합니다. Web report가 없다면 예외지만 보통 `Closes:`가 뒤따르고, report의 일부만 고치면 `Link:`를 대신 사용할 수 있습니다.

`Tested-by:`는 표시된 사람이 어떤 system에서 patch를 성공적으로 test했음을 뜻합니다. Maintainer에게 test 사실을 알리고 향후 tester를 찾을 수 있게 하며 tester에게 credit을 줍니다.

Reviewer's statement of oversight

`Reviewed-by:`를 제공하는 reviewer는 다음을 진술합니다.

• Mainline kernel inclusion의 적절성을 평가하기 위해 technical review를 수행했습니다.
• Patch의 problem과 question을 submitter에게 전달했고 그 response에 만족합니다.
• 더 개선할 점은 있을 수 있지만 현재 가치 있는 kernel change이며 integration을 막을 known issue가 없다고 믿습니다.
• Patch가 sound하다고 믿지만 별도 명시가 없는 한 목적 달성이나 모든 상황의 정상 동작을 보증하지 않습니다.

`Reviewed-by:`는 중요 technical issue가 남지 않은 적절한 change라는 opinion입니다. 실제 review를 수행한 사람이 제공하며 reviewer credit과 review 수준을 maintainer에게 알립니다.

Mailing list에서 받은 `Tested-by:`와 `Reviewed-by:`는 다음 version에 추가합니다. Patch가 크게 바뀌어 더는 적용되지 않으면 제거하고 보통 `---` 아래 patch changelog에 그 사실을 기록합니다.

Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
-------------------------------------------------------------------------

L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
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.

L'etichetta Tested-by: indica che la patch è stata verificata con successo
(su un qualche sistema) dalla persona citata.  Questa etichetta informa i
manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
persone che possano verificare il codice in futuro, e garantisce che queste
stesse persone ricevano credito per il loro lavoro.

Reviewed-by:, invece, indica che la patch è stata revisionata ed è stata
considerata accettabile in accordo con la dichiarazione dei revisori:

Dichiarazione di svista dei revisori
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:

	 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
	     l'adeguatezza ai fini dell'inclusione nel ramo principale del
	     kernel.

	 (b) Tutti i problemi e le domande riguardanti la patch sono stati
	     comunicati al mittente.  Sono soddisfatto dalle risposte
	     del mittente.

	 (c) Nonostante ci potrebbero essere cose migliorabili in queste
	     sottomissione, credo che sia, in questo momento, (1) una modifica
	     di interesse per il kernel, e (2) libera da problemi che
	     potrebbero metterne in discussione l'integrazione.

	 (d) Nonostante abbia revisionato la patch e creda che vada bene,
	     non garantisco (se non specificato altrimenti) che questa
	     otterrà quello che promette o funzionerà correttamente in tutte
	     le possibili situazioni.

L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
una modifica che si ritiene appropriata e senza alcun problema tecnico
importante.  Qualsiasi revisore interessato (quelli che lo hanno fatto)
possono offrire il proprio Reviewed-by per la patch.  Questa etichetta serve
a dare credito ai revisori e a informare i manutentori sul livello di revisione
che è stato fatto sulla patch.  L'etichetta Reviewed-by, quando fornita da
revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
loro serietà nella revisione, accrescerà le probabilità che la vostra patch
venga integrate nel kernel.

Quando si riceve una email sulla lista di discussione da un tester o
un revisore, le etichette Tested-by o Reviewed-by devono essere
aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
la patch è cambiata in modo significativo, queste etichette potrebbero
non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
della rimozione nel changelog della patch (subito dopo il separatore '---').

Suggested-by와 Fixes tag

`Suggested-by:`는 patch idea를 제안한 사람에게 credit을 줍니다. 특히 idea가 public forum에 공개되지 않았다면 explicit permission 없이 이 tag를 추가하지 않습니다.

`Fixes:`는 이전 commit의 bug를 고친다는 뜻으로 origin 파악과 review를 돕고 stable maintainer가 적용할 kernel을 정하는 데도 유용합니다. 이 tag가 stable rule을 우회하지 않으며 stable 대상 patch에는 `[email protected]`를 별도로 Cc해야 합니다.

L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
dalla persona nominata e le da credito. Tenete a mente che questa etichetta
non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
l'idea non è stata pubblicata in un forum pubblico.  Detto ciò, dando credito
a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
nuovamente in futuro.

L'etichetta Fixes: indica che la patch corregge un problema in un commit
precedente.  Serve a chiarire l'origine di un baco, il che aiuta la revisione
del baco stesso.  Questa etichetta è di aiuto anche per i manutentori dei
kernel stabili al fine di capire quale kernel deve ricevere la correzione.
Questo è il modo suggerito per indicare che un baco è stato corretto nella
patch. Per maggiori dettagli leggete :ref:`it_describe_changes`

Da notare che aggiungere un tag "Fixes:" non esime dalle regole
previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
in copia conoscenza [email protected] su tutte le patch per
suddetti kernel.

Canonical patch format과 subject

Git repository에 patch가 있다면 git format-patch가 올바른 formatting을 만든다. Tool은 필요한 설명 text를 만들 수 없으므로 지침을 직접 따라야 한다.

Subject: [PATCH 001/123] subsystem: summary phrase

Canonical 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다.

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 summary

Body의 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]>

.. _it_the_canonical_patch_format:

Il formato canonico delle patch
-------------------------------

Questa sezione descrive il formato che dovrebbe essere usato per le patch.
Notate che se state usando un repositorio ``git`` per salvare le vostre patch
potere usare il comando ``git format-patch`` per ottenere patch nel formato
appropriato.  Lo strumento non crea il testo necessario, per cui, leggete
le seguenti istruzioni.

L'oggetto di una patch canonica è la riga::

    Subject: [PATCH 001/123] subsystem: summary phrase

Il corpo di una patch canonica contiene i seguenti elementi:

  - Una riga ``from`` che specifica l'autore della patch, seguita
    da una riga vuota (necessaria soltanto se la persona che invia la
    patch non ne è l'autore).

  - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
    che verrà copiato permanentemente nel changelog per descrivere la patch.

  - Una riga vuota

  - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
    anch'esse nel changelog.

  - Una linea di demarcazione contenente semplicemente ``---``.

  - Qualsiasi altro commento che non deve finire nel changelog.

  - Le effettive modifiche al codice (il prodotto di ``diff``).

Il formato usato per l'oggetto permette ai programmi di posta di usarlo
per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
in questo modo l'ordine numerico ed alfabetico coincidono.

Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
o il sottosistema modificato dalla patch.

La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
il contenuto della patch.  La ``summary phrase`` non dovrebbe essere un nome
di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
patch correlate).

Ricordatevi che la ``summary phrase`` della vostra email diventerà un
identificatore globale ed unico per quella patch.  Si propaga fino al
changelog ``git``.  La ``summary phrase`` potrà essere usata in futuro
dagli sviluppatori per riferirsi a quella patch.  Le persone vorranno
cercare la ``summary phrase`` su internet per leggere le discussioni che la
riguardano.  Potrebbe anche essere l'unica cosa che le persone vedranno
quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
come ``gitk`` o ``git log --oneline``.

Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
ben scritto.

La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
Le etichette non verranno considerate come parte della frase riassuntiva, ma
indicano come la patch dovrebbe essere trattata.  Fra le etichette più comuni
ci sono quelle di versione che vengono usate quando una patch è stata inviata
più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
attendono dei commenti (*Request For Comments*).

Se ci sono quattro patch nella serie, queste dovrebbero essere
enumerate così: 1/4, 2/4, 3/4, 4/4.  Questo assicura che gli
sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
applicate, e per tracciare quelle che hanno revisionate o che hanno
applicato.

Un paio di esempi di oggetti::

    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

La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
formato:

        From: Patch Author <[email protected]>

La riga ``from`` indica chi verrà accreditato nel changelog permanente come
l'autore della patch.  Se la riga ``from`` è mancante, allora per determinare
l'autore da inserire nel changelog verrà usata la riga ``From``
nell'intestazione dell'email.

Explanation, backtrace와 --- 아래 commentary

Explanation 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+++--
...

Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
discussione che hanno portato alla patch.  L'inclusione di informazioni
sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
eccetera) è particolarmente utile per le persone che potrebbero cercare fra
i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
con abbastanza dettagli da far capire al lettore **perché** quella
patch fu creata, e questo a distanza di settimane, mesi, o addirittura
anni.

Se la patch corregge un errore di compilazione, non sarà necessario
includere proprio _tutto_ quello che è uscito dal compilatore;
aggiungete solo quello che è necessario per far si che la vostra patch
venga trovata.  Come nella ``summary phrase``, è importante essere sia
brevi che descrittivi.

La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
il messaggio di changelog.

Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
Un ``diffstat`` è particolarmente utile per le patch grandi. Se
includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
cosicché i nomi dei file elencati non occupino troppo spazio
(facilmente rientreranno negli 80 caratteri, magari con qualche
indentazione).  (``git`` genera di base dei diffstat adatti).

I commenti che sono importanti solo per i manutentori, quindi
inadatti al changelog permanente, dovrebbero essere messi qui.  Un
buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
``patch changelogs`` che descrivere le differenze fra le versioni
della patch.

Queste informazioni devono andare **dopo** la linea ``---`` che separa
il *changelog* dal resto della patch. Le informazioni riguardanti la
versione di una patch non sono parte del *chagelog* che viene incluso
in git. Queste sono informazioni utili solo ai revisori. Se venissero
messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
rimuoverle; cosa che invece viene fatta automaticamente quando vengono
messe correttamente oltre la riga.::

  <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+++--
  ...

Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.

.. _it_backtraces:

Aggiungere i *backtrace* nei messaggi di commit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
informazioni che distraggono dal vero problema (per esempio, i
marcatori temporali, la lista dei moduli, la lista dei registri, lo
stato dello stack).

Quindi, per rendere utile un *backtrace* dovreste eliminare le
informazioni inutili, cosicché ci si possa focalizzare sul
problema. Ecco un esempio di un *backtrace* essenziale::

  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

.. _it_explicit_in_reply_to:

In-Reply-To와 base tree 정보

Explicit 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이면 쓸모가 없다.

Usare esplicitamente In-Reply-To nell'intestazione
--------------------------------------------------

Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
potrebbe essere d'aiuto per associare una patch ad una discussione
precedente, per esempio per collegare la correzione di un baco con l'e-mail
che lo riportava.  Tuttavia, per serie di patch multiple è generalmente
sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
In questo modo versioni multiple di una patch non diventeranno un'ingestibile
giungla di riferimenti all'interno dei programmi di posta.  Se un collegamento
è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
ad una versione precedente di una serie di patch (per esempio, potete usarlo
per l'email introduttiva alla serie).

Fornire informazioni circa i sorgenti
-------------------------------------

Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di
revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base
su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei
manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:**
nel file MAINTAINERS spiegato sopra.

Questo è ancora più importante per i processi automatizzati di CI che tentano di
eseguire una serie di test per stabilire la qualità del codice prima che il
manutentore inizi la revisione.

Se si usa ``git format-patch`` per generare le patch, si possono includere
automaticamente le informazioni sull'albero di base nell'invio usando il flag
``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami
topici::

    $ 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/...

Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà
che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli
strumenti CI informazioni sufficienti per eseguire correttamente ``git am``
senza preoccuparsi dei conflitti::

    $ git checkout -b patch-review [base-commit-id]
    Switched to a new branch 'patch-review'
    $ git am patches.mbox
    Applying: First Commit
    Applying: ...

Consultate ``man git-format-patch`` per maggiori informazioni circa questa
opzione.

.. note::

   L'opzione ``--base`` fu introdotta con git versione 2.9.0

Se non si usa git per produrre le patch, si può comunque includere
``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il
lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima
patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a
tutti gli altri contenuti, subito prima della vostra firma e-mail.

Assicuratevi che il commit si basi su sorgenti ufficiali del
manutentore/mainline e non su sorgenti interni, accessibile solo a voi,
altrimenti sarebbe inutile.

Tooling과 참고 자료

B4는 dependency tracking, checkpatch 실행, mail formatting과 sending 등 process의 많은 technical aspect를 자동화한다.

• B4 documentationhttps://b4.docs.kernel.org/en/latest/
• Andrew Morton, The perfect patchhttps://www.ozlabs.org/~akpm/stuff/tpp.txt
• Linux kernel patch submission formathttps://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
• How to piss off a kernel subsystem maintainer, 1http://www.kroah.com/log/linux/maintainer.html
• How to piss off a kernel subsystem maintainer, 2http://www.kroah.com/log/linux/maintainer-02.html
• How to piss off a kernel subsystem maintainer, 3http://www.kroah.com/log/linux/maintainer-03.html
• How to piss off a kernel subsystem maintainer, 4http://www.kroah.com/log/linux/maintainer-04.html
• How to piss off a kernel subsystem maintainer, 5http://www.kroah.com/log/linux/maintainer-05.html
• How to piss off a kernel subsystem maintainer, 6http://www.kroah.com/log/linux/maintainer-06.html
• Linus on canonical patch formathttps://lore.kernel.org/r/[email protected]
• Andi Kleen, On submitting kernel patcheshttp://halobates.de/on-submitting-patches.pdf

Documentation/translations/it_IT/process/coding-style.rst도 참고한다. 마지막 Andi Kleen 자료는 어렵거나 논쟁적인 change를 받아들여지게 하는 전략을 다룬다.

Strumenti
---------

Molti degli aspetti più tecnici di questo processo possono essere automatizzati
usando b4, la cui documentazione è disponibile all'indirizzo
<https://b4.docs.kernel.org/en/latest/>. Può aiutare a tracciare la dipendenze,
eseguire checkpatch e con la formattazione e l'invio di messaggi di posta.

Riferimenti
-----------

Andrew Morton, "La patch perfetta" (tpp).
  <https://www.ozlabs.org/~akpm/stuff/tpp.txt>

Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>

Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
  <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/translations/it_IT/process/coding-style.rst.

E-mail di Linus Torvalds sul formato canonico di una patch:
  <https://lore.kernel.org/r/[email protected]>

Andi Kleen, "Su come sottomettere patch del kernel"
  Alcune strategie su come sottomettere modifiche toste o controverse.

  http://halobates.de/on-submitting-patches.pdf