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 volete far riferimento a uno specifico commit, non usate solo 110l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga 111riassuntiva del commit per rendere la chiaro ai revisori l'oggetto. 112Per esempio:: 113 114 Commit e21d2170f36602ae2708 ("video: remove unnecessary 115 platform_set_drvdata()") removed the unnecessary 116 platform_set_drvdata(), but left the variable "dev" unused, 117 delete it. 118 119Dovreste anche assicurarvi di usare almeno i primi 12 caratteri 120dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e 121questo rende possibile la collisione fra due identificativi con pochi 122caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il 123vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi. 124 125Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno 126riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi 127riferimento. Se la patch è il risultato di una discussione avvenuta 128precedentemente o di un documento sul presente sul web, allora fatevi 129riferimento. 130 131Per esempio, se la vostra patch corregge un baco potete aggiungere 132quest'etichetta per fare riferimento ad un rapporto su una lista di discussione 133o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far 134riferimento ad una discussione precedentemente avvenuta su una lista di 135discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in 136questione. 137 138Quando volete fare riferimento ad una lista di discussione, preferite il 139servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è 140sufficiente usare il campo ``Message-ID``, presente nell'intestazione del 141messaggio, senza parentesi angolari. Per esempio:: 142 143 Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI 144 145Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così 146creato funzioni e che indirizzi verso il messaggio desiderato. 147 148Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza 149accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno 150condotto all'invio della patch. 151 152Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch, 153allora usate l'etichetta "Closes:":: 154 155 Closes: https://example.com/issues/1234 optional-other-stuff 156 157Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere 158automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni 159automatismi che monitorano la liste di discussione possono anche tracciare 160queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono 161proibiti. 162 163Se la vostra patch corregge un baco in un commit specifico, per esempio avete 164trovato un problema usando ``git bisect``, per favore usate l'etichetta 165'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti 166dalla riga riassuntiva. Per esempio:: 167 168 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") 169 170La seguente configurazione di ``git config`` può essere usata per formattare 171i risultati dei comandi ``git log`` o ``git show`` come nell'esempio 172precedente:: 173 174 [core] 175 abbrev = 12 176 [pretty] 177 fixes = Fixes: %h (\"%s\") 178 179Un esempio:: 180 181 $ git log -1 --pretty=fixes 54a4f0239f2e 182 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") 183 184.. _it_split_changes: 185 186Separate le vostre modifiche 187---------------------------- 188 189Separate ogni **cambiamento logico** in patch distinte. 190 191Per esempio, se i vostri cambiamenti per un singolo driver includono 192sia delle correzioni di bachi che miglioramenti alle prestazioni, 193allora separateli in due o più patch. Se i vostri cambiamenti includono 194un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli 195in due patch. 196 197D'altro canto, se fate una singola modifica su più file, raggruppate tutte 198queste modifiche in una singola patch. Dunque, un singolo cambiamento logico 199è contenuto in una sola patch. 200 201Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche 202che siano facilmente comprensibili e che possano essere verificate dai revisori. 203Ogni patch dovrebbe essere giustificabile di per sé. 204 205Se al fine di ottenere un cambiamento completo una patch dipende da un'altra, 206va bene. Semplicemente scrivete una nota nella descrizione della patch per 207farlo presente: **"this patch depends on patch X"**. 208 209Quando dividete i vostri cambiamenti in una serie di patch, prestate 210particolare attenzione alla verifica di ogni patch della serie; per ognuna 211il kernel deve compilare ed essere eseguito correttamente. Gli sviluppatori 212che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo 213della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo 214avete introdotto dei bachi. 215 216Se non potete condensare la vostra serie di patch in una più piccola, allora 217pubblicatene una quindicina alla volta e aspettate che vengano revisionate 218ed integrate. 219 220 2214) Verificate lo stile delle vostre modifiche 222--------------------------------------------- 223 224Controllate che la vostra patch non violi lo stile del codice, maggiori 225dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst. 226Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e 227voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata 228letta. 229 230Un'eccezione importante si ha quando del codice viene spostato da un file 231ad un altro -- in questo caso non dovreste modificare il codice spostato 232per nessun motivo, almeno non nella patch che lo sposta. Questo separa 233chiaramente l'azione di spostare il codice e il vostro cambiamento. 234Questo aiuta enormemente la revisione delle vere differenze e permette agli 235strumenti di tenere meglio la traccia della storia del codice. 236 237Prima di inviare una patch, verificatene lo stile usando l'apposito 238verificatore (scripts/checkpatch.pl). Da notare, comunque, che il verificator 239di stile dovrebbe essere visto come una guida, non come un sostituto al 240giudizio umano. Se il vostro codice è migliore nonostante una violazione 241dello stile, probabilmente è meglio lasciarlo com'è. 242 243Il verificatore ha tre diversi livelli di severità: 244 - ERROR: le cose sono molto probabilmente sbagliate 245 - WARNING: le cose necessitano d'essere revisionate con attenzione 246 - CHECK: le cose necessitano di un pensierino 247 248Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste 249nella vostra patch. 250 251 2525) Selezionate i destinatari della vostra patch 253----------------------------------------------- 254 255Dovreste sempre inviare una copia della patch ai manutentori e alle liste di 256discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al 257file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del 258codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il 259percorso alle vostre patch). Se non riuscite a trovare un manutentore per il 260sottosistema su cui state lavorando, allora Andrew Morton 261(akpm@linux-foundation.org) sarà la vostra ultima possibilità. 262 263La lista linux-kernel@vger.kernel.org dovrebbe essere usata per l'invio di tutte 264le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni 265sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi 266scorrelati al tema della lista o a persone che non dovrebbero essere 267interessate all'argomento. 268 269Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la 270vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org 271dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui 272diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la 273lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra 274patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste 275di discussione che non sono interessate al vostro lavoro. 276 277Molte delle liste di discussione relative al kernel vengono ospitate su 278kernel.org; potete trovare un loro elenco alla pagina 279https://subspace.kernel.org. Tuttavia, ci sono altre liste di discussione 280ospitate altrove. 281 282L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a 283Linux Torvalds. Il suo indirizzo e-mail è <torvalds@linux-foundation.org>. 284Riceve moltissime e-mail, e, a questo punto, solo poche patch passano 285direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro 286meglio per -evitare di- inviargli e-mail. 287 288Se avete una patch che corregge un baco di sicurezza che potrebbe essere 289sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve 290embargo potrebbe essere preso in considerazione per dare il tempo alle 291distribuzioni di prendere la patch e renderla disponibile ai loro utenti; 292in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna 293lista di discussione pubblica. Leggete anche 294Documentation/process/security-bugs.rst. 295 296Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero 297essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga:: 298 299 Cc: stable@vger.kernel.org 300 301nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario 302delle e-mail). In aggiunta a questo file, dovreste leggere anche 303Documentation/translations/it_IT/process/stable-kernel-rules.rst. 304 305Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore 306inviate una patch per le pagine man ai manutentori di suddette pagine (elencati 307nel file MAINTAINERS), o almeno una notifica circa la vostra modifica, 308cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche 309all'API dello spazio utente dovrebbero essere inviate in copia anche a 310linux-api@vger.kernel.org. 311 312Niente: MIME, links, compressione, allegati. Solo puro testo 313------------------------------------------------------------- 314 315Linus e gli altri sviluppatori del kernel devono poter commentare 316le modifiche che sottomettete. Per uno sviluppatore è importante 317essere in grado di "citare" le vostre modifiche, usando normali 318programmi di posta elettronica, cosicché sia possibile commentare 319una porzione specifica del vostro codice. 320 321Per questa ragione tutte le patch devono essere inviate via e-mail 322come testo. Il modo più facile, e quello raccomandato, è con ``git 323send-email``. Al sito https://git-send-email.io è disponibile una 324guida interattiva sull'uso di ``git send-email``. 325 326Se decidete di non usare ``git send-email``: 327 328.. warning:: 329 330 Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state 331 attenti che il vostro programma non corrompa il contenuto con andate 332 a capo automatiche. 333 334La patch non deve essere un allegato MIME, compresso o meno. Molti 335dei più popolari programmi di posta elettronica non trasmettono un allegato 336MIME come puro testo, e questo rende impossibile commentare il vostro codice. 337Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo 338così la possibilità che il vostro allegato-MIME venga accettato. 339 340Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno 341potrebbe chiedervi di rinviarle come allegato MIME. 342 343Leggete Documentation/translations/it_IT/process/email-clients.rst 344per dei suggerimenti sulla configurazione del programmi di posta elettronica 345per l'invio di patch intatte. 346 347Rispondere ai commenti di revisione 348----------------------------------- 349 350In risposta alla vostra email, quasi certamente i revisori vi 351invieranno dei commenti su come migliorare la vostra patch. Dovete 352rispondere a questi commenti; ignorare i revisori è un ottimo modo per 353essere ignorati. Riscontri o domande che non conducono ad una 354modifica del codice quasi certamente dovrebbero portare ad un commento 355nel changelog cosicché il prossimo revisore potrà meglio comprendere 356cosa stia accadendo. 357 358Assicuratevi di dire ai revisori quali cambiamenti state facendo e di 359ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che 360richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in 361questo caso, rispondete con educazione e concentratevi sul problema che hanno 362evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un 363``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando 364le differenze rispetto a sottomissioni precedenti (vedere 365:ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che 366vi hanno fornito dei commenti per notificarle di eventuali nuove versioni. 367 368Leggete Documentation/translations/it_IT/process/email-clients.rst per 369le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare 370sulle liste di discussione. 371 372.. _it_interleaved_replies: 373 374Rispondere alle email in riga e riducendo la citazioni 375------------------------------------------------------ 376 377Nelle discussioni riguardo allo sviluppo del kernel viene fortemente scoraggiato 378l'uso di risposte in cima ai messaggi di posta elettronica. Rispondere in riga 379rende le conversazioni molto più scorrevoli. Maggiori dettagli possono essere 380trovati qui: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style 381 382Come spesso citato nelle liste di discussione:: 383 384 R: http://en.wikipedia.org/wiki/Top_post 385 D: Dove posso trovare informazioni riguardo alle "risposte in cima"? 386 R: Perché incasina il normale ordine con cui si legge un testo. 387 D: Perché è così terribile rispondere in cima? 388 R: Risposte in cima. 389 Q: Qual è la cosa più fastidiosa nei messaggi di posta elettronica? 390 391Allo stesso modo, per favore eliminate tutte le citazioni non necessarie per la 392vostra risposta. Questo permette di trovare più facilmente le risposte, e 393permette di risparmiare tempo e spazio. Per maggiori dettagli: 394http://daringfireball.net/2007/07/on_top :: 395 396 R: No. 397 D: Dovrei includere un blocco di citazione dopo la mia risposta? 398 399.. _it_resend_reminders: 400 401Non scoraggiatevi - o impazientitevi 402------------------------------------ 403 404Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate. 405I revisori sono persone occupate e potrebbero non ricevere la vostra patch 406immediatamente. 407 408Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma 409ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche 410settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di 411aver inviato le patch correttamente. Aspettate almeno una settimana prima di 412rinviare le modifiche o sollecitare i revisori - probabilmente anche di più 413durante la finestra d'integrazione. 414 415Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane 416aggiungendo la parola "RESEND" nel titolo:: 417 418 [PATCH Vx RESEND] sub/sys: Condensed patch summary 419 420Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata 421della vostra patch, o serie di patch - "RESEND" si applica solo alla 422sottomissione di patch, o serie di patch, che non hanno subito modifiche 423dall'ultima volta che sono state inviate. 424 425Aggiungete PATCH nell'oggetto 426----------------------------- 427 428Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi 429prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli 430altri sviluppatori del kernel di distinguere facilmente le patch dalle altre 431discussioni. 432 433``git send-email`` lo fa automaticamente. 434 435 436Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore 437---------------------------------------------------------------------- 438 439Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per 440quelle patch che per raggiungere lo stadio finale passano attraverso 441diversi livelli di manutentori, abbiamo introdotto la procedura di "firma" 442delle patch che vengono inviate per e-mail. 443 444La firma è una semplice riga alla fine della descrizione della patch che 445certifica che l'avete scritta voi o che avete il diritto di pubblicarla 446come patch open-source. Le regole sono abbastanza semplici: se potete 447certificare quanto segue: 448 449Il certificato d'origine dello sviluppatore 1.1 450^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 451 452Contribuendo a questo progetto, io certifico che: 453 454 (a) Il contributo è stato creato interamente, o in parte, da me e che 455 ho il diritto di inviarlo in accordo con la licenza open-source 456 indicata nel file; oppure 457 458 (b) Il contributo è basato su un lavoro precedente che, nei limiti 459 della mia conoscenza, è coperto da un'appropriata licenza 460 open-source che mi da il diritto di modificarlo e inviarlo, 461 le cui modifiche sono interamente o in parte mie, in accordo con 462 la licenza open-source (a meno che non abbia il permesso di usare 463 un'altra licenza) indicata nel file; oppure 464 465 (c) Il contributo mi è stato fornito direttamente da qualcuno che 466 ha certificato (a), (b) o (c) e non l'ho modificata. 467 468 (d) Capisco e concordo col fatto che questo progetto e i suoi 469 contributi sono pubblici e che un registro dei contributi (incluse 470 tutte le informazioni personali che invio con essi, inclusa la mia 471 firma) verrà mantenuto indefinitamente e che possa essere 472 ridistribuito in accordo con questo progetto o le licenze 473 open-source coinvolte. 474 475poi dovete solo aggiungere una riga che dice:: 476 477 Signed-off-by: Random J Developer <random@developer.example.org> 478 479usando il vostro vero nome (spiacenti, non si accettano 480contributi anonimi). Questo verrà fatto automaticamente se usate 481``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe 482includere "Signed-off-by", se usate ``git revert -s`` questo verrà 483fatto automaticamente. 484 485Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno 486ignorate, ma potete farlo per meglio identificare procedure aziendali interne o 487per aggiungere dettagli circa la firma. 488 489In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da 490parte di tutte quelle persone che si sono occupate della gestione e 491del trasporto della patch. Queste però non sono state coinvolte nello 492sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso 493**reale** che una patch a intrapreso dallo sviluppatore, fino al 494manutentore, per poi giungere a Linus. 495 496 497Quando utilizzare Acked-by:, Cc:, e Co-developed-by: 498---------------------------------------------------- 499 500L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello 501sviluppo della patch, o che era nel suo percorso di consegna. 502 503Se una persona non è direttamente coinvolta con la preparazione o gestione 504della patch ma desidera firmare e mettere agli atti la loro approvazione, 505allora queste persone possono chiedere di aggiungere al changelog della patch 506una riga Acked-by:. 507 508Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto 509quando quello stesso manutentore non ha contribuito né trasmesso la patch. 510 511Acked-by: non è formale come Signed-off-by:. Questo indica che la persona ha 512revisionato la patch e l'ha trovata accettabile. Per cui, a volte, chi 513integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by: 514(ma tenete presente che solitamente è meglio chiedere esplicitamente). 515 516Acked-by: non indica l'accettazione di un'intera patch. Per esempio, quando 517una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un 518manutentore di uno di questi, significa che il manutentore accetta quella 519parte di codice relativa al sottosistema che mantiene. Qui dovremmo essere 520giudiziosi. Quando si hanno dei dubbi si dovrebbe far riferimento alla 521discussione originale negli archivi della lista di discussione. 522 523Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha 524fatto, potete aggiungere l'etichetta ``Cc:`` alla patch. Questa è l'unica 525etichetta che può essere aggiunta senza che la persona in questione faccia 526alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della 527patch. Questa etichetta documenta che terzi potenzialmente interessati sono 528stati inclusi nella discussione. 529 530Co-developed-by: indica che la patch è stata cosviluppata da diversi 531sviluppatori; viene usato per assegnare più autori (in aggiunta a quello 532associato all'etichetta From:) quando più persone lavorano ad una patch. Dato 533che Co-developed-by: implica la paternità della patch, ogni Co-developed-by: 534dev'essere seguito immediatamente dal Signed-off-by: del corrispondente 535coautore. Qui si applica la procedura di base per sign-off, in pratica 536l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile 537l'ordine cronologico della storia della patch, indipendentemente dal fatto che 538la paternità venga assegnata via From: o Co-developed-by:. Da notare che 539l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch. 540 541Notate anche che l'etichetta From: è opzionale quando l'autore in From: è 542anche la persona (e indirizzo email) indicato nel From: dell'intestazione 543dell'email. 544 545Esempio di una patch sottomessa dall'autore in From::: 546 547 <changelog> 548 549 Co-developed-by: First Co-Author <first@coauthor.example.org> 550 Signed-off-by: First Co-Author <first@coauthor.example.org> 551 Co-developed-by: Second Co-Author <second@coauthor.example.org> 552 Signed-off-by: Second Co-Author <second@coauthor.example.org> 553 Signed-off-by: From Author <from@author.example.org> 554 555Esempio di una patch sottomessa dall'autore Co-developed-by::: 556 557 From: From Author <from@author.example.org> 558 559 <changelog> 560 561 Co-developed-by: Random Co-Author <random@coauthor.example.org> 562 Signed-off-by: Random Co-Author <random@coauthor.example.org> 563 Signed-off-by: From Author <from@author.example.org> 564 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> 565 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> 566 567Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: 568------------------------------------------------------------------------- 569 570L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi 571e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro. 572Rammentate che se il baco è stato riportato in privato, dovrete chiedere il 573permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va 574usata per i bachi, dunque non usatela per richieste di nuove funzionalità. 575Questa etichetta dovrebbe essere seguita da quella Closes: con un indirizzo al 576rapporto, a meno che questo non sia disponibile sul web. L'etichetta Link: può 577essere usata in alternativa a Closes: se la patch corregge solo in parte il 578problema riportato nel rapporto. 579 580L'etichetta Tested-by: indica che la patch è stata verificata con successo 581(su un qualche sistema) dalla persona citata. Questa etichetta informa i 582manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare 583persone che possano verificare il codice in futuro, e garantisce che queste 584stesse persone ricevano credito per il loro lavoro. 585 586Reviewed-by:, invece, indica che la patch è stata revisionata ed è stata 587considerata accettabile in accordo con la dichiarazione dei revisori: 588 589Dichiarazione di svista dei revisori 590^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 591 592Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue: 593 594 (a) Ho effettuato una revisione tecnica di questa patch per valutarne 595 l'adeguatezza ai fini dell'inclusione nel ramo principale del 596 kernel. 597 598 (b) Tutti i problemi e le domande riguardanti la patch sono stati 599 comunicati al mittente. Sono soddisfatto dalle risposte 600 del mittente. 601 602 (c) Nonostante ci potrebbero essere cose migliorabili in queste 603 sottomissione, credo che sia, in questo momento, (1) una modifica 604 di interesse per il kernel, e (2) libera da problemi che 605 potrebbero metterne in discussione l'integrazione. 606 607 (d) Nonostante abbia revisionato la patch e creda che vada bene, 608 non garantisco (se non specificato altrimenti) che questa 609 otterrà quello che promette o funzionerà correttamente in tutte 610 le possibili situazioni. 611 612L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di 613una modifica che si ritiene appropriata e senza alcun problema tecnico 614importante. Qualsiasi revisore interessato (quelli che lo hanno fatto) 615possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve 616a dare credito ai revisori e a informare i manutentori sul livello di revisione 617che è stato fatto sulla patch. L'etichetta Reviewed-by, quando fornita da 618revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la 619loro serietà nella revisione, accrescerà le probabilità che la vostra patch 620venga integrate nel kernel. 621 622Quando si riceve una email sulla lista di discussione da un tester o 623un revisore, le etichette Tested-by o Reviewed-by devono essere 624aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se 625la patch è cambiata in modo significativo, queste etichette potrebbero 626non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia 627della rimozione nel changelog della patch (subito dopo il separatore '---'). 628 629L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita 630dalla persona nominata e le da credito. Tenete a mente che questa etichetta 631non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se 632l'idea non è stata pubblicata in un forum pubblico. Detto ciò, dando credito 633a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci 634nuovamente in futuro. 635 636L'etichetta Fixes: indica che la patch corregge un problema in un commit 637precedente. Serve a chiarire l'origine di un baco, il che aiuta la revisione 638del baco stesso. Questa etichetta è di aiuto anche per i manutentori dei 639kernel stabili al fine di capire quale kernel deve ricevere la correzione. 640Questo è il modo suggerito per indicare che un baco è stato corretto nella 641patch. Per maggiori dettagli leggete :ref:`it_describe_changes` 642 643Da notare che aggiungere un tag "Fixes:" non esime dalle regole 644previste per i kernel stabili, e nemmeno dalla necessità di aggiungere 645in copia conoscenza stable@vger.kernel.org su tutte le patch per 646suddetti kernel. 647 648.. _it_the_canonical_patch_format: 649 650Il formato canonico delle patch 651------------------------------- 652 653Questa sezione descrive il formato che dovrebbe essere usato per le patch. 654Notate che se state usando un repositorio ``git`` per salvare le vostre patch 655potere usare il comando ``git format-patch`` per ottenere patch nel formato 656appropriato. Lo strumento non crea il testo necessario, per cui, leggete 657le seguenti istruzioni. 658 659L'oggetto di una patch canonica è la riga:: 660 661 Subject: [PATCH 001/123] subsystem: summary phrase 662 663Il corpo di una patch canonica contiene i seguenti elementi: 664 665 - Una riga ``from`` che specifica l'autore della patch, seguita 666 da una riga vuota (necessaria soltanto se la persona che invia la 667 patch non ne è l'autore). 668 669 - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri, 670 che verrà copiato permanentemente nel changelog per descrivere la patch. 671 672 - Una riga vuota 673 674 - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno 675 anch'esse nel changelog. 676 677 - Una linea di demarcazione contenente semplicemente ``---``. 678 679 - Qualsiasi altro commento che non deve finire nel changelog. 680 681 - Le effettive modifiche al codice (il prodotto di ``diff``). 682 683Il formato usato per l'oggetto permette ai programmi di posta di usarlo 684per ordinare le patch alfabeticamente - tutti i programmi di posta hanno 685questa funzionalità - dato che al numero sequenziale si antepongono degli zeri; 686in questo modo l'ordine numerico ed alfabetico coincidono. 687 688Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area 689o il sottosistema modificato dalla patch. 690 691La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente 692il contenuto della patch. La ``summary phrase`` non dovrebbe essere un nome 693di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in 694una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse 695patch correlate). 696 697Ricordatevi che la ``summary phrase`` della vostra email diventerà un 698identificatore globale ed unico per quella patch. Si propaga fino al 699changelog ``git``. La ``summary phrase`` potrà essere usata in futuro 700dagli sviluppatori per riferirsi a quella patch. Le persone vorranno 701cercare la ``summary phrase`` su internet per leggere le discussioni che la 702riguardano. Potrebbe anche essere l'unica cosa che le persone vedranno 703quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti 704come ``gitk`` o ``git log --oneline``. 705 706Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve 707descrivere sia cosa viene modificato, sia il perché sia necessario. Essere 708brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto 709ben scritto. 710 711La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra 712le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>". 713Le etichette non verranno considerate come parte della frase riassuntiva, ma 714indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni 715ci sono quelle di versione che vengono usate quando una patch è stata inviata 716più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si 717attendono dei commenti (*Request For Comments*). 718 719Se ci sono quattro patch nella serie, queste dovrebbero essere 720enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli 721sviluppatori capiranno l'ordine in cui le patch dovrebbero essere 722applicate, e per tracciare quelle che hanno revisionate o che hanno 723applicato. 724 725Un paio di esempi di oggetti:: 726 727 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching 728 Subject: [PATCH v2 01/27] x86: fix eflags tracking 729 Subject: [PATCH v2] sub/sys: Condensed patch summary 730 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary 731 732La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel 733formato: 734 735 From: Patch Author <author@example.com> 736 737La riga ``from`` indica chi verrà accreditato nel changelog permanente come 738l'autore della patch. Se la riga ``from`` è mancante, allora per determinare 739l'autore da inserire nel changelog verrà usata la riga ``From`` 740nell'intestazione dell'email. 741 742Il corpo della spiegazione verrà incluso nel changelog permanente, per cui 743deve aver senso per un lettore esperto che è ha dimenticato i dettagli della 744discussione che hanno portato alla patch. L'inclusione di informazioni 745sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops, 746eccetera) è particolarmente utile per le persone che potrebbero cercare fra 747i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto 748con abbastanza dettagli da far capire al lettore **perché** quella 749patch fu creata, e questo a distanza di settimane, mesi, o addirittura 750anni. 751 752Se la patch corregge un errore di compilazione, non sarà necessario 753includere proprio _tutto_ quello che è uscito dal compilatore; 754aggiungete solo quello che è necessario per far si che la vostra patch 755venga trovata. Come nella ``summary phrase``, è importante essere sia 756brevi che descrittivi. 757 758La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce 759il messaggio di changelog. 760 761Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per 762mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi. 763Un ``diffstat`` è particolarmente utile per le patch grandi. Se 764includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70`` 765cosicché i nomi dei file elencati non occupino troppo spazio 766(facilmente rientreranno negli 80 caratteri, magari con qualche 767indentazione). (``git`` genera di base dei diffstat adatti). 768 769I commenti che sono importanti solo per i manutentori, quindi 770inadatti al changelog permanente, dovrebbero essere messi qui. Un 771buon esempio per questo tipo di commenti potrebbe essere il cosiddetto 772``patch changelogs`` che descrivere le differenze fra le versioni 773della patch. 774 775Queste informazioni devono andare **dopo** la linea ``---`` che separa 776il *changelog* dal resto della patch. Le informazioni riguardanti la 777versione di una patch non sono parte del *chagelog* che viene incluso 778in git. Queste sono informazioni utili solo ai revisori. Se venissero 779messe sopra la riga, qualcuno dovrà fare del lavoro manuale per 780rimuoverle; cosa che invece viene fatta automaticamente quando vengono 781messe correttamente oltre la riga.:: 782 783 <commit message> 784 ... 785 Signed-off-by: Author <author@mail> 786 --- 787 V2 -> V3: Removed redundant helper function 788 V1 -> V2: Cleaned up coding style and addressed review comments 789 790 path/to/file | 5+++-- 791 ... 792 793Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. 794 795.. _it_backtraces: 796 797Aggiungere i *backtrace* nei messaggi di commit 798^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 799 800I *backtrace* aiutano a documentare la sequenza di chiamate a funzione 801che portano ad un problema. Tuttavia, non tutti i *backtrace* sono 802davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche 803e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante 804informazioni che distraggono dal vero problema (per esempio, i 805marcatori temporali, la lista dei moduli, la lista dei registri, lo 806stato dello stack). 807 808Quindi, per rendere utile un *backtrace* dovreste eliminare le 809informazioni inutili, cosicché ci si possa focalizzare sul 810problema. Ecco un esempio di un *backtrace* essenziale:: 811 812 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) 813 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) 814 Call Trace: 815 mba_wrmsr 816 update_domains 817 rdtgroup_mkdir 818 819.. _it_explicit_in_reply_to: 820 821Usare esplicitamente In-Reply-To nell'intestazione 822-------------------------------------------------- 823 824Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail 825potrebbe essere d'aiuto per associare una patch ad una discussione 826precedente, per esempio per collegare la correzione di un baco con l'e-mail 827che lo riportava. Tuttavia, per serie di patch multiple è generalmente 828sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni. 829In questo modo versioni multiple di una patch non diventeranno un'ingestibile 830giungla di riferimenti all'interno dei programmi di posta. Se un collegamento 831è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti 832ad una versione precedente di una serie di patch (per esempio, potete usarlo 833per l'email introduttiva alla serie). 834 835Fornire informazioni circa i sorgenti 836------------------------------------- 837 838Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di 839revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base 840su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei 841manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:** 842nel file MAINTAINERS spiegato sopra. 843 844Questo è ancora più importante per i processi automatizzati di CI che tentano di 845eseguire una serie di test per stabilire la qualità del codice prima che il 846manutentore inizi la revisione. 847 848Se si usa ``git format-patch`` per generare le patch, si possono includere 849automaticamente le informazioni sull'albero di base nell'invio usando il flag 850``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami 851topici:: 852 853 $ git checkout -t -b my-topical-branch master 854 Branch 'my-topical-branch' set up to track local branch 'master'. 855 Switched to a new branch 'my-topical-branch' 856 857 [perform your edits and commits] 858 859 $ git format-patch --base=auto --cover-letter -o outgoing/ master 860 outgoing/0000-cover-letter.patch 861 outgoing/0001-First-Commit.patch 862 outgoing/... 863 864Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà 865che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli 866strumenti CI informazioni sufficienti per eseguire correttamente ``git am`` 867senza preoccuparsi dei conflitti:: 868 869 $ git checkout -b patch-review [base-commit-id] 870 Switched to a new branch 'patch-review' 871 $ git am patches.mbox 872 Applying: First Commit 873 Applying: ... 874 875Consultate ``man git-format-patch`` per maggiori informazioni circa questa 876opzione. 877 878.. note:: 879 880 L'opzione ``--base`` fu introdotta con git versione 2.9.0 881 882Se non si usa git per produrre le patch, si può comunque includere 883``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il 884lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima 885patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a 886tutti gli altri contenuti, subito prima della vostra firma e-mail. 887 888Assicuratevi che il commit si basi su sorgenti ufficiali del 889manutentore/mainline e non su sorgenti interni, accessibile solo a voi, 890altrimenti sarebbe inutile. 891 892Strumenti 893--------- 894 895Molti degli aspetti più tecnici di questo processo possono essere automatizzati 896usando b4, la cui documentazione è disponibile all'indirizzo 897<https://b4.docs.kernel.org/en/latest/>. Può aiutare a tracciare la dipendenze, 898eseguire checkpatch e con la formattazione e l'invio di messaggi di posta. 899 900Riferimenti 901----------- 902 903Andrew Morton, "La patch perfetta" (tpp). 904 <https://www.ozlabs.org/~akpm/stuff/tpp.txt> 905 906Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux" 907 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> 908 909Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema" 910 <http://www.kroah.com/log/linux/maintainer.html> 911 912 <http://www.kroah.com/log/linux/maintainer-02.html> 913 914 <http://www.kroah.com/log/linux/maintainer-03.html> 915 916 <http://www.kroah.com/log/linux/maintainer-04.html> 917 918 <http://www.kroah.com/log/linux/maintainer-05.html> 919 920 <http://www.kroah.com/log/linux/maintainer-06.html> 921 922Kernel Documentation/translations/it_IT/process/coding-style.rst. 923 924E-mail di Linus Torvalds sul formato canonico di una patch: 925 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> 926 927Andi Kleen, "Su come sottomettere patch del kernel" 928 Alcune strategie su come sottomettere modifiche toste o controverse. 929 930 http://halobates.de/on-submitting-patches.pdf 931