1.. include:: ../disclaimer-ita.rst
2
3:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
4:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
5
6.. _it_submittingpatches:
7
8Inviare patch: la guida essenziale per vedere il vostro codice nel kernel
9=========================================================================
10
11Una persona o un'azienda che volesse inviare una patch al kernel potrebbe
12sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca
13una certa familiarità col "sistema".  Questo testo è una raccolta di
14suggerimenti che aumenteranno significativamente le probabilità di vedere le
15vostre patch accettate.
16
17Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
18dettagli su come funziona il processo di sviluppo del kernel leggete
19Documentation/translations/it_IT/process/development-process.rst. Leggete anche
20Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
21punti da verificare prima di inviare del codice.
22Per delle patch relative alle associazioni per Device Tree leggete
23Documentation/translations/it_IT/process/submitting-patches.rst.
24
25Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
26Se non siete pratici di ``git``, allora è bene che lo impariate;
27renderà la vostra vita di sviluppatore del kernel molto più semplice.
28
29I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
30riguardo al loro modo di lavorare ed aspettative. Consultate
31:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`
32
33Ottenere i sorgenti attuali
34---------------------------
35
36Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate
37``git`` per ottenerli.  Vorrete iniziare col repositorio principale che può
38essere recuperato col comando::
39
40  git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
41
42Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti
43principali del kernel.  La maggior parte dei manutentori hanno i propri
44sorgenti e desiderano che le patch siano preparate basandosi su di essi.
45Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS
46che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso
47in cui i sorgenti da usare non siano elencati il quel file.
48
49.. _it_describe_changes:
50
51Descrivete le vostre modifiche
52------------------------------
53
54Descrivete il vostro problema. Esiste sempre un problema che via ha spinto
55ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una
56nuova funzionalità da 5000 righe di codice.  Convincete i revisori che vale
57la pena risolvere il vostro problema e che ha senso continuare a leggere oltre
58al primo paragrafo.
59
60Descrivete ciò che sarà visibile agli utenti.  Chiari incidenti nel sistema
61e blocchi sono abbastanza convincenti, ma non tutti i bachi sono così evidenti.
62Anche se il problema è stato scoperto durante la revisione del codice,
63descrivete l'impatto che questo avrà sugli utenti.  Tenete presente che
64la maggior parte delle installazioni Linux usa un kernel che arriva dai
65sorgenti stabili o dai sorgenti di una distribuzione particolare che prende
66singolarmente le patch dai sorgenti principali; quindi, includete tutte
67le informazioni che possono essere utili a capire le vostre modifiche:
68le circostanze che causano il problema, estratti da dmesg, descrizioni di
69un incidente di sistema, prestazioni di una regressione, picchi di latenza,
70blocchi, eccetera.
71
72Quantificare le ottimizzazioni e i compromessi.  Se affermate di aver
73migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,
74o la dimensione del file binario, includete dei numeri a supporto della
75vostra dichiarazione.  Ma ricordatevi di descrivere anche eventuali costi
76che non sono ovvi.  Solitamente le ottimizzazioni non sono gratuite, ma sono
77un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si
78parla di ipotesi euristiche, fra differenti carichi.  Descrivete i lati
79negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano
80valutare i costi e i benefici.
81
82Una volta che il problema è chiaro, descrivete come lo risolvete andando
83nel dettaglio tecnico.  È molto importante che descriviate la modifica
84in un inglese semplice cosicché i revisori possano verificare che il codice si
85comporti come descritto.
86
87I manutentori vi saranno grati se scrivete la descrizione della patch in un
88formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
89``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.
90
91Risolvete solo un problema per patch.  Se la vostra descrizione inizia ad
92essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
93divisa. Leggete :ref:`it_split_changes`.
94
95Quando inviate o rinviate una patch o una serie, includete la descrizione
96completa delle modifiche e la loro giustificazione.  Non limitatevi a dire che
97questa è la versione N della patch (o serie).  Non aspettatevi che i
98manutentori di un sottosistema vadano a cercare le versioni precedenti per
99cercare la descrizione da aggiungere.  In pratica, la patch (o serie) e la sua
100descrizione devono essere un'unica cosa.  Questo aiuta i manutentori e i
101revisori.  Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto
102le versioni precedenti della patch.
103
104Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy
105do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
106xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
107comportamento.
108
109Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
110riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
111riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere
112quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
113o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
114riferimento ad una discussione precedentemente avvenuta su una lista di
115discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
116questione.
117
118Quando volete fare riferimento ad una lista di discussione, preferite il
119servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
120sufficiente usare il campo ``Message-Id``, presente nell'intestazione del
121messaggio, senza parentesi angolari. Per esempio::
122
123     Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
124
125Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
126creato funzioni e che indirizzi verso il messaggio desiderato.
127
128Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
129accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
130condotto all'invio della patch.
131
132Se volete far riferimento a uno specifico commit, non usate solo
133l'identificativo SHA-1.  Per cortesia, aggiungete anche la breve riga
134riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.
135Per esempio::
136
137	Commit e21d2170f36602ae2708 ("video: remove unnecessary
138	platform_set_drvdata()") removed the unnecessary
139	platform_set_drvdata(), but left the variable "dev" unused,
140	delete it.
141
142Dovreste anche assicurarvi di usare almeno i primi 12 caratteri
143dell'identificativo SHA-1.  Il repositorio del kernel ha *molti* oggetti e
144questo rende possibile la collisione fra due identificativi con pochi
145caratteri.  Tenete ben presente che anche se oggi non ci sono collisioni con il
146vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.
147
148Se la vostra patch corregge un baco in un commit specifico, per esempio avete
149trovato un problema usando ``git bisect``, per favore usate l'etichetta
150'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti
151dalla riga riassuntiva.  Per esempio::
152
153	Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
154
155La seguente configurazione di ``git config`` può essere usata per formattare
156i risultati dei comandi ``git log`` o ``git show`` come nell'esempio
157precedente::
158
159	[core]
160		abbrev = 12
161	[pretty]
162		fixes = Fixes: %h (\"%s\")
163
164Un esempio::
165
166       $ git log -1 --pretty=fixes 54a4f0239f2e
167       Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
168
169.. _it_split_changes:
170
171Separate le vostre modifiche
172----------------------------
173
174Separate ogni **cambiamento logico** in patch distinte.
175
176Per esempio, se i vostri cambiamenti per un singolo driver includono
177sia delle correzioni di bachi che miglioramenti alle prestazioni,
178allora separateli in due o più patch.  Se i vostri cambiamenti includono
179un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli
180in due patch.
181
182D'altro canto, se fate una singola modifica su più file, raggruppate tutte
183queste modifiche in una singola patch.  Dunque, un singolo cambiamento logico
184è contenuto in una sola patch.
185
186Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche
187che siano facilmente comprensibili e che possano essere verificate dai revisori.
188Ogni patch dovrebbe essere giustificabile di per sé.
189
190Se al fine di ottenere un cambiamento completo una patch dipende da un'altra,
191va bene.  Semplicemente scrivete una nota nella descrizione della patch per
192farlo presente: **"this patch depends on patch X"**.
193
194Quando dividete i vostri cambiamenti in una serie di patch, prestate
195particolare attenzione alla verifica di ogni patch della serie; per ognuna
196il kernel deve compilare ed essere eseguito correttamente.  Gli sviluppatori
197che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo
198della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo
199avete introdotto dei bachi.
200
201Se non potete condensare la vostra serie di patch in una più piccola, allora
202pubblicatene una quindicina alla volta e aspettate che vengano revisionate
203ed integrate.
204
205
2064) Verificate lo stile delle vostre modifiche
207---------------------------------------------
208
209Controllate che la vostra patch non violi lo stile del codice, maggiori
210dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.
211Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e
212voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata
213letta.
214
215Un'eccezione importante si ha quando del codice viene spostato da un file
216ad un altro -- in questo caso non dovreste modificare il codice spostato
217per nessun motivo, almeno non nella patch che lo sposta.  Questo separa
218chiaramente l'azione di spostare il codice e il vostro cambiamento.
219Questo aiuta enormemente la revisione delle vere differenze e permette agli
220strumenti di tenere meglio la traccia della storia del codice.
221
222Prima di inviare una patch, verificatene lo stile usando l'apposito
223verificatore (scripts/checkpatch.pl).  Da notare, comunque, che il verificator
224di stile dovrebbe essere visto come una guida, non come un sostituto al
225giudizio umano.  Se il vostro codice è migliore nonostante una violazione
226dello stile, probabilmente è meglio lasciarlo com'è.
227
228Il verificatore ha tre diversi livelli di severità:
229 - ERROR: le cose sono molto probabilmente sbagliate
230 - WARNING: le cose necessitano d'essere revisionate con attenzione
231 - CHECK: le cose necessitano di un pensierino
232
233Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste
234nella vostra patch.
235
236
2375) Selezionate i destinatari della vostra patch
238-----------------------------------------------
239
240Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
241interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
242delle revisioni per scoprire chi si occupa del codice. Lo script
243scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle
244vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su
245cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la
246vostra ultima possibilità.
247
248Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
249vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
250dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui
251diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la
252lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra
253patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste
254di discussione che non sono interessate al vostro lavoro.
255
256Molte delle liste di discussione relative al kernel vengono ospitate su
257vger.kernel.org; potete trovare un loro elenco alla pagina
258http://vger.kernel.org/vger-lists.html.  Tuttavia, ci sono altre liste di
259discussione ospitate altrove.
260
261Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!
262
263L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a
264Linux Torvalds.  Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.
265Riceve moltissime e-mail, e, a questo punto, solo poche patch passano
266direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro
267meglio per -evitare di- inviargli e-mail.
268
269Se avete una patch che corregge un baco di sicurezza che potrebbe essere
270sfruttato, inviatela a security@kernel.org.  Per bachi importanti, un breve
271embargo potrebbe essere preso in considerazione per dare il tempo alle
272distribuzioni di prendere la patch e renderla disponibile ai loro utenti;
273in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna
274lista di discussione pubblica. Leggete anche
275Documentation/admin-guide/security-bugs.rst.
276
277Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero
278essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::
279
280  Cc: stable@vger.kernel.org
281
282nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario
283delle e-mail).  In aggiunta a questo file, dovreste leggere anche
284Documentation/translations/it_IT/process/stable-kernel-rules.rst.
285
286Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore
287inviate una patch per le pagine man ai manutentori di suddette pagine (elencati
288nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,
289cosicché l'informazione possa trovare la sua strada nel manuale.  Le modifiche
290all'API dello spazio utente dovrebbero essere inviate in copia anche a
291linux-api@vger.kernel.org.
292
293Niente: MIME, links, compressione, allegati.  Solo puro testo
294-------------------------------------------------------------
295
296Linus e gli altri sviluppatori del kernel devono poter commentare
297le modifiche che sottomettete.  Per uno sviluppatore è importante
298essere in grado di "citare" le vostre modifiche, usando normali
299programmi di posta elettronica, cosicché sia possibile commentare
300una porzione specifica del vostro codice.
301
302Per questa ragione tutte le patch devono essere inviate via e-mail
303come testo. Il modo più facile, e quello raccomandato, è con ``git
304send-email``.  Al sito https://git-send-email.io è disponibile una
305guida interattiva sull'uso di ``git send-email``.
306
307Se decidete di non usare ``git send-email``:
308
309.. warning::
310
311  Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state
312  attenti che il vostro programma non corrompa il contenuto con andate
313  a capo automatiche.
314
315La patch non deve essere un allegato MIME, compresso o meno.  Molti
316dei più popolari programmi di posta elettronica non trasmettono un allegato
317MIME come puro testo, e questo rende impossibile commentare il vostro codice.
318Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo
319così la possibilità che il vostro allegato-MIME venga accettato.
320
321Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno
322potrebbe chiedervi di rinviarle come allegato MIME.
323
324Leggete Documentation/translations/it_IT/process/email-clients.rst
325per dei suggerimenti sulla configurazione del programmi di posta elettronica
326per l'invio di patch intatte.
327
328Rispondere ai commenti di revisione
329-----------------------------------
330
331In risposta alla vostra email, quasi certamente i revisori vi
332invieranno dei commenti su come migliorare la vostra patch.  Dovete
333rispondere a questi commenti; ignorare i revisori è un ottimo modo per
334essere ignorati.  Riscontri o domande che non conducono ad una
335modifica del codice quasi certamente dovrebbero portare ad un commento
336nel changelog cosicché il prossimo revisore potrà meglio comprendere
337cosa stia accadendo.
338
339Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
340ringraziarli per il loro tempo.  Revisionare codice è un lavoro faticoso e che
341richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
342questo caso, rispondete con educazione e concentratevi sul problema che hanno
343evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un
344``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
345le differenze rispetto a sottomissioni precedenti (vedere
346:ref:`it_the_canonical_patch_format`).
347
348Leggete Documentation/translations/it_IT/process/email-clients.rst per
349le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
350sulle liste di discussione.
351
352.. _it_resend_reminders:
353
354Non scoraggiatevi - o impazientitevi
355------------------------------------
356
357Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.
358I revisori sono persone occupate e potrebbero non ricevere la vostra patch
359immediatamente.
360
361Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento,
362ma ora il processo di sviluppo funziona meglio.  Dovreste ricevere commenti
363in una settimana o poco più; se questo non dovesse accadere, assicuratevi di
364aver inviato le patch correttamente.  Aspettate almeno una settimana prima di
365rinviare le modifiche o sollecitare i revisori - probabilmente anche di più
366durante la finestra d'integrazione.
367
368Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane
369aggiungendo la parola "RESEND" nel titolo::
370
371    [PATCH Vx RESEND] sub/sys: Condensed patch summary
372
373Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata
374della vostra patch, o serie di patch - "RESEND" si applica solo alla
375sottomissione di patch, o serie di patch, che non hanno subito modifiche
376dall'ultima volta che sono state inviate.
377
378Aggiungete PATCH nell'oggetto
379-----------------------------
380
381Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi
382prefiggere il vostro oggetto con [PATCH].  Questo permette a Linus e agli
383altri sviluppatori del kernel di distinguere facilmente le patch dalle altre
384discussioni.
385
386``git send-email`` lo fa automaticamente.
387
388
389Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore
390----------------------------------------------------------------------
391
392Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per
393quelle patch che per raggiungere lo stadio finale passano attraverso
394diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"
395delle patch che vengono inviate per e-mail.
396
397La firma è una semplice riga alla fine della descrizione della patch che
398certifica che l'avete scritta voi o che avete il diritto di pubblicarla
399come patch open-source.  Le regole sono abbastanza semplici: se potete
400certificare quanto segue:
401
402Il certificato d'origine dello sviluppatore 1.1
403^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
404
405Contribuendo a questo progetto, io certifico che:
406
407        (a) Il contributo è stato creato interamente, o in parte, da me e che
408            ho il diritto di inviarlo in accordo con la licenza open-source
409            indicata nel file; oppure
410
411        (b) Il contributo è basato su un lavoro precedente che, nei limiti
412            della mia conoscenza, è coperto da un'appropriata licenza
413            open-source che mi da il diritto di modificarlo e inviarlo,
414            le cui modifiche sono interamente o in parte mie, in accordo con
415            la licenza open-source (a meno che non abbia il permesso di usare
416            un'altra licenza) indicata nel file; oppure
417
418        (c) Il contributo mi è stato fornito direttamente da qualcuno che
419            ha certificato (a), (b) o (c) e non l'ho modificata.
420
421        (d) Capisco e concordo col fatto che questo progetto e i suoi
422            contributi sono pubblici e che un registro dei contributi (incluse
423            tutte le informazioni personali che invio con essi, inclusa la mia
424            firma) verrà mantenuto indefinitamente e che possa essere
425            ridistribuito in accordo con questo progetto o le licenze
426            open-source coinvolte.
427
428poi dovete solo aggiungere una riga che dice::
429
430	Signed-off-by: Random J Developer <random@developer.example.org>
431
432usando il vostro vero nome (spiacenti, non si accettano pseudonimi o
433contributi anonimi). Questo verrà fatto automaticamente se usate
434``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe
435includere "Signed-off-by", se usate ``git revert -s`` questo verrà
436fatto automaticamente.
437
438Alcune persone aggiungono delle etichette alla fine.  Per ora queste verranno
439ignorate, ma potete farlo per meglio identificare procedure aziendali interne o
440per aggiungere dettagli circa la firma.
441
442In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da
443parte di tutte quelle persone che si sono occupate della gestione e
444del trasporto della patch. Queste però non sono state coinvolte nello
445sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso
446**reale** che una patch a intrapreso dallo sviluppatore, fino al
447manutentore, per poi giungere a Linus.
448
449
450Quando utilizzare Acked-by:, Cc:, e Co-developed-by:
451----------------------------------------------------
452
453L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello
454sviluppo della patch, o che era nel suo percorso di consegna.
455
456Se una persona non è direttamente coinvolta con la preparazione o gestione
457della patch ma desidera firmare e mettere agli atti la loro approvazione,
458allora queste persone possono chiedere di aggiungere al changelog della patch
459una riga Acked-by:.
460
461Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto
462quando quello stesso manutentore non ha contribuito né trasmesso la patch.
463
464Acked-by: non è formale come Signed-off-by:.  Questo indica che la persona ha
465revisionato la patch e l'ha trovata accettabile.  Per cui, a volte, chi
466integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:
467(ma tenete presente che solitamente è meglio chiedere esplicitamente).
468
469Acked-by: non indica l'accettazione di un'intera patch.  Per esempio, quando
470una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un
471manutentore di uno di questi, significa che il manutentore accetta quella
472parte di codice relativa al sottosistema che mantiene.  Qui dovremmo essere
473giudiziosi.  Quando si hanno dei dubbi si dovrebbe far riferimento alla
474discussione originale negli archivi della lista di discussione.
475
476Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha
477fatto, potete aggiungere l'etichetta ``Cc:`` alla patch.  Questa è l'unica
478etichetta che può essere aggiunta senza che la persona in questione faccia
479alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della
480patch.  Questa etichetta documenta che terzi potenzialmente interessati sono
481stati inclusi nella discussione.
482
483Co-developed-by: indica che la patch è stata cosviluppata da diversi
484sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
485associato all'etichetta From:) quando più persone lavorano ad una patch.  Dato
486che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:
487dev'essere seguito immediatamente dal Signed-off-by: del corrispondente
488coautore. Qui si applica la procedura di base per sign-off, in pratica
489l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile
490l'ordine cronologico della storia della patch, indipendentemente dal fatto che
491la paternità venga assegnata via From: o Co-developed-by:. Da notare che
492l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.
493
494Notate anche che l'etichetta From: è opzionale quando l'autore in From: è
495anche la persona (e indirizzo email) indicato nel From: dell'intestazione
496dell'email.
497
498Esempio di una patch sottomessa dall'autore in From:::
499
500	<changelog>
501
502	Co-developed-by: First Co-Author <first@coauthor.example.org>
503	Signed-off-by: First Co-Author <first@coauthor.example.org>
504	Co-developed-by: Second Co-Author <second@coauthor.example.org>
505	Signed-off-by: Second Co-Author <second@coauthor.example.org>
506	Signed-off-by: From Author <from@author.example.org>
507
508Esempio di una patch sottomessa dall'autore Co-developed-by:::
509
510	From: From Author <from@author.example.org>
511
512	<changelog>
513
514	Co-developed-by: Random Co-Author <random@coauthor.example.org>
515	Signed-off-by: Random Co-Author <random@coauthor.example.org>
516	Signed-off-by: From Author <from@author.example.org>
517	Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
518	Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
519
520Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
521-------------------------------------------------------------------------
522
523L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
524e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
525Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
526permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
527usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
528
529L'etichetta Tested-by: indica che la patch è stata verificata con successo
530(su un qualche sistema) dalla persona citata.  Questa etichetta informa i
531manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare
532persone che possano verificare il codice in futuro, e garantisce che queste
533stesse persone ricevano credito per il loro lavoro.
534
535Reviewd-by:, invece, indica che la patch è stata revisionata ed è stata
536considerata accettabile in accordo con la dichiarazione dei revisori:
537
538Dichiarazione di svista dei revisori
539^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
540
541Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:
542
543	 (a) Ho effettuato una revisione tecnica di questa patch per valutarne
544	     l'adeguatezza ai fini dell'inclusione nel ramo principale del
545	     kernel.
546
547	 (b) Tutti i problemi e le domande riguardanti la patch sono stati
548	     comunicati al mittente.  Sono soddisfatto dalle risposte
549	     del mittente.
550
551	 (c) Nonostante ci potrebbero essere cose migliorabili in queste
552	     sottomissione, credo che sia, in questo momento, (1) una modifica
553	     di interesse per il kernel, e (2) libera da problemi che
554	     potrebbero metterne in discussione l'integrazione.
555
556	 (d) Nonostante abbia revisionato la patch e creda che vada bene,
557	     non garantisco (se non specificato altrimenti) che questa
558	     otterrà quello che promette o funzionerà correttamente in tutte
559	     le possibili situazioni.
560
561L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di
562una modifica che si ritiene appropriata e senza alcun problema tecnico
563importante.  Qualsiasi revisore interessato (quelli che lo hanno fatto)
564possono offrire il proprio Reviewed-by per la patch.  Questa etichetta serve
565a dare credito ai revisori e a informare i manutentori sul livello di revisione
566che è stato fatto sulla patch.  L'etichetta Reviewd-by, quando fornita da
567revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la
568loro serietà nella revisione, accrescerà le probabilità che la vostra patch
569venga integrate nel kernel.
570
571Quando si riceve una email sulla lista di discussione da un tester o
572un revisore, le etichette Tested-by o Reviewd-by devono essere
573aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se
574la patch è cambiata in modo significativo, queste etichette potrebbero
575non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia
576della rimozione nel changelog della patch (subito dopo il separatore '---').
577
578L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita
579dalla persona nominata e le da credito. Tenete a mente che questa etichetta
580non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se
581l'idea non è stata pubblicata in un forum pubblico.  Detto ciò, dando credito
582a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci
583nuovamente in futuro.
584
585L'etichetta Fixes: indica che la patch corregge un problema in un commit
586precedente.  Serve a chiarire l'origine di un baco, il che aiuta la revisione
587del baco stesso.  Questa etichetta è di aiuto anche per i manutentori dei
588kernel stabili al fine di capire quale kernel deve ricevere la correzione.
589Questo è il modo suggerito per indicare che un baco è stato corretto nella
590patch. Per maggiori dettagli leggete :ref:`it_describe_changes`
591
592Da notare che aggiungere un tag "Fixes:" non esime dalle regole
593previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
594in copia conoscenza stable@vger.kernel.org su tutte le patch per
595suddetti kernel.
596
597.. _it_the_canonical_patch_format:
598
599Il formato canonico delle patch
600-------------------------------
601
602Questa sezione descrive il formato che dovrebbe essere usato per le patch.
603Notate che se state usando un repositorio ``git`` per salvare le vostre patch
604potere usare il comando ``git format-patch`` per ottenere patch nel formato
605appropriato.  Lo strumento non crea il testo necessario, per cui, leggete
606le seguenti istruzioni.
607
608L'oggetto di una patch canonica è la riga::
609
610    Subject: [PATCH 001/123] subsystem: summary phrase
611
612Il corpo di una patch canonica contiene i seguenti elementi:
613
614  - Una riga ``from`` che specifica l'autore della patch, seguita
615    da una riga vuota (necessaria soltanto se la persona che invia la
616    patch non ne è l'autore).
617
618  - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,
619    che verrà copiato permanentemente nel changelog per descrivere la patch.
620
621  - Una riga vuota
622
623  - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno
624    anch'esse nel changelog.
625
626  - Una linea di demarcazione contenente semplicemente ``---``.
627
628  - Qualsiasi altro commento che non deve finire nel changelog.
629
630  - Le effettive modifiche al codice (il prodotto di ``diff``).
631
632Il formato usato per l'oggetto permette ai programmi di posta di usarlo
633per ordinare le patch alfabeticamente - tutti i programmi di posta hanno
634questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;
635in questo modo l'ordine numerico ed alfabetico coincidono.
636
637Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area
638o il sottosistema modificato dalla patch.
639
640La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente
641il contenuto della patch.  La ``summary phrase`` non dovrebbe essere un nome
642di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in
643una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse
644patch correlate).
645
646Ricordatevi che la ``summary phrase`` della vostra email diventerà un
647identificatore globale ed unico per quella patch.  Si propaga fino al
648changelog ``git``.  La ``summary phrase`` potrà essere usata in futuro
649dagli sviluppatori per riferirsi a quella patch.  Le persone vorranno
650cercare la ``summary phrase`` su internet per leggere le discussioni che la
651riguardano.  Potrebbe anche essere l'unica cosa che le persone vedranno
652quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti
653come ``gitk`` o ``git log --oneline``.
654
655Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve
656descrivere sia cosa viene modificato, sia il perché sia necessario. Essere
657brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto
658ben scritto.
659
660La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra
661le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".
662Le etichette non verranno considerate come parte della frase riassuntiva, ma
663indicano come la patch dovrebbe essere trattata.  Fra le etichette più comuni
664ci sono quelle di versione che vengono usate quando una patch è stata inviata
665più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si
666attendono dei commenti (*Request For Comments*).
667
668Se ci sono quattro patch nella serie, queste dovrebbero essere
669enumerate così: 1/4, 2/4, 3/4, 4/4.  Questo assicura che gli
670sviluppatori capiranno l'ordine in cui le patch dovrebbero essere
671applicate, e per tracciare quelle che hanno revisionate o che hanno
672applicato.
673
674Un paio di esempi di oggetti::
675
676    Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
677    Subject: [PATCH v2 01/27] x86: fix eflags tracking
678    Subject: [PATCH v2] sub/sys: Condensed patch summary
679    Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary
680
681La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel
682formato:
683
684        From: Patch Author <author@example.com>
685
686La riga ``from`` indica chi verrà accreditato nel changelog permanente come
687l'autore della patch.  Se la riga ``from`` è mancante, allora per determinare
688l'autore da inserire nel changelog verrà usata la riga ``From``
689nell'intestazione dell'email.
690
691Il corpo della spiegazione verrà incluso nel changelog permanente, per cui
692deve aver senso per un lettore esperto che è ha dimenticato i dettagli della
693discussione che hanno portato alla patch.  L'inclusione di informazioni
694sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,
695eccetera) è particolarmente utile per le persone che potrebbero cercare fra
696i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto
697con abbastanza dettagli da far capire al lettore **perché** quella
698patch fu creata, e questo a distanza di settimane, mesi, o addirittura
699anni.
700
701Se la patch corregge un errore di compilazione, non sarà necessario
702includere proprio _tutto_ quello che è uscito dal compilatore;
703aggiungete solo quello che è necessario per far si che la vostra patch
704venga trovata.  Come nella ``summary phrase``, è importante essere sia
705brevi che descrittivi.
706
707La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce
708il messaggio di changelog.
709
710Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per
711mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.
712Un ``diffstat`` è particolarmente utile per le patch grandi. Se
713includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``
714cosicché i nomi dei file elencati non occupino troppo spazio
715(facilmente rientreranno negli 80 caratteri, magari con qualche
716indentazione).  (``git`` genera di base dei diffstat adatti).
717
718I commenti che sono importanti solo per i manutentori, quindi
719inadatti al changelog permanente, dovrebbero essere messi qui.  Un
720buon esempio per questo tipo di commenti potrebbe essere il cosiddetto
721``patch changelogs`` che descrivere le differenze fra le versioni
722della patch.
723
724Queste informazioni devono andare **dopo** la linea ``---`` che separa
725il *changelog* dal resto della patch. Le informazioni riguardanti la
726versione di una patch non sono parte del *chagelog* che viene incluso
727in git. Queste sono informazioni utili solo ai revisori. Se venissero
728messe sopra la riga, qualcuno dovrà fare del lavoro manuale per
729rimuoverle; cosa che invece viene fatta automaticamente quando vengono
730messe correttamente oltre la riga.::
731
732  <commit message>
733  ...
734  Signed-off-by: Author <author@mail>
735  ---
736  V2 -> V3: Removed redundant helper function
737  V1 -> V2: Cleaned up coding style and addressed review comments
738
739  path/to/file | 5+++--
740  ...
741
742Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
743
744.. _it_backtraces:
745
746Aggiungere i *backtrace* nei messaggi di commit
747^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
748
749I *backtrace* aiutano a documentare la sequenza di chiamate a funzione
750che portano ad un problema. Tuttavia, non tutti i *backtrace* sono
751davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche
752e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante
753informazioni che distraggono dal vero problema (per esempio, i
754marcatori temporali, la lista dei moduli, la lista dei registri, lo
755stato dello stack).
756
757Quindi, per rendere utile un *backtrace* dovreste eliminare le
758informazioni inutili, cosicché ci si possa focalizzare sul
759problema. Ecco un esempio di un *backtrace* essenziale::
760
761  unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
762  at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
763  Call Trace:
764  mba_wrmsr
765  update_domains
766  rdtgroup_mkdir
767
768.. _it_explicit_in_reply_to:
769
770Usare esplicitamente In-Reply-To nell'intestazione
771--------------------------------------------------
772
773Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail
774potrebbe essere d'aiuto per associare una patch ad una discussione
775precedente, per esempio per collegare la correzione di un baco con l'e-mail
776che lo riportava.  Tuttavia, per serie di patch multiple è generalmente
777sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
778In questo modo versioni multiple di una patch non diventeranno un'ingestibile
779giungla di riferimenti all'interno dei programmi di posta.  Se un collegamento
780è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
781ad una versione precedente di una serie di patch (per esempio, potete usarlo
782per l'email introduttiva alla serie).
783
784Riferimenti
785-----------
786
787Andrew Morton, "La patch perfetta" (tpp).
788  <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
789
790Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"
791  <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
792
793Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"
794  <http://www.kroah.com/log/linux/maintainer.html>
795
796  <http://www.kroah.com/log/linux/maintainer-02.html>
797
798  <http://www.kroah.com/log/linux/maintainer-03.html>
799
800  <http://www.kroah.com/log/linux/maintainer-04.html>
801
802  <http://www.kroah.com/log/linux/maintainer-05.html>
803
804  <http://www.kroah.com/log/linux/maintainer-06.html>
805
806No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!
807  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
808
809Kernel Documentation/translations/it_IT/process/coding-style.rst.
810
811E-mail di Linus Torvalds sul formato canonico di una patch:
812  <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
813
814Andi Kleen, "Su come sottomettere patch del kernel"
815  Alcune strategie su come sottomettere modifiche toste o controverse.
816
817  http://halobates.de/on-submitting-patches.pdf
818