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