928 lines · plain
1.. include:: ../disclaimer-ita.rst2 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 kernel9=========================================================================10 11Una persona o un'azienda che volesse inviare una patch al kernel potrebbe12sentirsi scoraggiata dal processo di sottomissione, specialmente quando manca13una certa familiarità col "sistema". Questo testo è una raccolta di14suggerimenti che aumenteranno significativamente le probabilità di vedere le15vostre patch accettate.16 17Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori18dettagli su come funziona il processo di sviluppo del kernel leggete19Documentation/translations/it_IT/process/development-process.rst. Leggete anche20Documentation/translations/it_IT/process/submit-checklist.rst per una lista di21punti da verificare prima di inviare del codice.22Per delle patch relative alle associazioni per Device Tree leggete23Documentation/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ù informazioni30riguardo al loro modo di lavorare ed aspettative. Consultate31:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`32 33Ottenere i sorgenti attuali34---------------------------35 36Se non avete un repositorio coi sorgenti del kernel più recenti, allora usate37``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.git41 42Notate, comunque, che potreste non voler sviluppare direttamente coi sorgenti43principali del kernel. La maggior parte dei manutentori hanno i propri44sorgenti e desiderano che le patch siano preparate basandosi su di essi.45Guardate l'elemento **T:** per un determinato sottosistema nel file MAINTANERS46che troverete nei sorgenti, o semplicemente chiedete al manutentore nel caso47in cui i sorgenti da usare non siano elencati il quel file.48 49.. _it_describe_changes:50 51Descrivete le vostre modifiche52------------------------------53 54Descrivete il vostro problema. Esiste sempre un problema che via ha spinto55ha fare il vostro lavoro, che sia la correzione di un baco da una riga o una56nuova funzionalità da 5000 righe di codice. Convincete i revisori che vale57la pena risolvere il vostro problema e che ha senso continuare a leggere oltre58al primo paragrafo.59 60Descrivete ciò che sarà visibile agli utenti. Chiari incidenti nel sistema61e 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 che64la maggior parte delle installazioni Linux usa un kernel che arriva dai65sorgenti stabili o dai sorgenti di una distribuzione particolare che prende66singolarmente le patch dai sorgenti principali; quindi, includete tutte67le informazioni che possono essere utili a capire le vostre modifiche:68le circostanze che causano il problema, estratti da dmesg, descrizioni di69un incidente di sistema, prestazioni di una regressione, picchi di latenza,70blocchi, eccetera.71 72Quantificare le ottimizzazioni e i compromessi. Se affermate di aver73migliorato le prestazioni, il consumo di memoria, l'impatto sollo stack,74o la dimensione del file binario, includete dei numeri a supporto della75vostra dichiarazione. Ma ricordatevi di descrivere anche eventuali costi76che non sono ovvi. Solitamente le ottimizzazioni non sono gratuite, ma sono77un compromesso fra l'uso di CPU, la memoria e la leggibilità; o, quando si78parla di ipotesi euristiche, fra differenti carichi. Descrivete i lati79negativi che vi aspettate dall'ottimizzazione cosicché i revisori possano80valutare i costi e i benefici.81 82Una volta che il problema è chiaro, descrivete come lo risolvete andando83nel dettaglio tecnico. È molto importante che descriviate la modifica84in un inglese semplice cosicché i revisori possano verificare che il codice si85comporti come descritto.86 87I manutentori vi saranno grati se scrivete la descrizione della patch in un88formato 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 ad92essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere93divisa. Leggete :ref:`it_split_changes`.94 95Quando inviate o rinviate una patch o una serie, includete la descrizione96completa delle modifiche e la loro giustificazione. Non limitatevi a dire che97questa è la versione N della patch (o serie). Non aspettatevi che i98manutentori di un sottosistema vadano a cercare le versioni precedenti per99cercare la descrizione da aggiungere. In pratica, la patch (o serie) e la sua100descrizione devono essere un'unica cosa. Questo aiuta i manutentori e i101revisori. Probabilmente, alcuni revisori non hanno nemmeno ricevuto o visto102le versioni precedenti della patch.103 104Descrivete le vostro modifiche usando l'imperativo, per esempio "make xyzzy105do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed106xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo107comportamento.108 109Se volete far riferimento a uno specifico commit, non usate solo110l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga111riassuntiva del commit per rendere la chiaro ai revisori l'oggetto.112Per esempio::113 114 Commit e21d2170f36602ae2708 ("video: remove unnecessary115 platform_set_drvdata()") removed the unnecessary116 platform_set_drvdata(), but left the variable "dev" unused,117 delete it.118 119Dovreste anche assicurarvi di usare almeno i primi 12 caratteri120dell'identificativo SHA-1. Il repositorio del kernel ha *molti* oggetti e121questo rende possibile la collisione fra due identificativi con pochi122caratteri. Tenete ben presente che anche se oggi non ci sono collisioni con il123vostro identificativo a 6 caratteri, potrebbero essercene fra 5 anni da oggi.124 125Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno126riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi127riferimento. Se la patch è il risultato di una discussione avvenuta128precedentemente o di un documento sul presente sul web, allora fatevi129riferimento.130 131Per esempio, se la vostra patch corregge un baco potete aggiungere132quest'etichetta per fare riferimento ad un rapporto su una lista di discussione133o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far134riferimento ad una discussione precedentemente avvenuta su una lista di135discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in136questione.137 138Quando volete fare riferimento ad una lista di discussione, preferite il139servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è140sufficiente usare il campo ``Message-Id``, presente nell'intestazione del141messaggio, senza parentesi angolari. Per esempio::142 143 Link: https://lore.kernel.org/r/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 senza149accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno150condotto 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-stuff156 157Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere158automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni159automatismi che monitorano la liste di discussione possono anche tracciare160queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono161proibiti.162 163Se la vostra patch corregge un baco in un commit specifico, per esempio avete164trovato un problema usando ``git bisect``, per favore usate l'etichetta165'Fixes:' indicando i primi 12 caratteri dell'identificativo SHA-1 seguiti166dalla 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 formattare171i risultati dei comandi ``git log`` o ``git show`` come nell'esempio172precedente::173 174 [core]175 abbrev = 12176 [pretty]177 fixes = Fixes: %h (\"%s\")178 179Un esempio::180 181 $ git log -1 --pretty=fixes 54a4f0239f2e182 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 modifiche187----------------------------188 189Separate ogni **cambiamento logico** in patch distinte.190 191Per esempio, se i vostri cambiamenti per un singolo driver includono192sia delle correzioni di bachi che miglioramenti alle prestazioni,193allora separateli in due o più patch. Se i vostri cambiamenti includono194un aggiornamento dell'API e un nuovo driver che lo sfrutta, allora separateli195in due patch.196 197D'altro canto, se fate una singola modifica su più file, raggruppate tutte198queste modifiche in una singola patch. Dunque, un singolo cambiamento logico199è contenuto in una sola patch.200 201Il punto da ricordare è che ogni modifica dovrebbe fare delle modifiche202che 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 per207farlo presente: **"this patch depends on patch X"**.208 209Quando dividete i vostri cambiamenti in una serie di patch, prestate210particolare attenzione alla verifica di ogni patch della serie; per ognuna211il kernel deve compilare ed essere eseguito correttamente. Gli sviluppatori212che usano ``git bisect`` per scovare i problemi potrebbero finire nel mezzo213della vostra serie in un punto qualsiasi; non vi saranno grati se nel mezzo214avete introdotto dei bachi.215 216Se non potete condensare la vostra serie di patch in una più piccola, allora217pubblicatene una quindicina alla volta e aspettate che vengano revisionate218ed integrate.219 220 2214) Verificate lo stile delle vostre modifiche222---------------------------------------------223 224Controllate che la vostra patch non violi lo stile del codice, maggiori225dettagli sono disponibili in Documentation/translations/it_IT/process/coding-style.rst.226Non farlo porta semplicemente a una perdita di tempo da parte dei revisori e227voi vedrete la vostra patch rifiutata, probabilmente senza nemmeno essere stata228letta.229 230Un'eccezione importante si ha quando del codice viene spostato da un file231ad un altro -- in questo caso non dovreste modificare il codice spostato232per nessun motivo, almeno non nella patch che lo sposta. Questo separa233chiaramente l'azione di spostare il codice e il vostro cambiamento.234Questo aiuta enormemente la revisione delle vere differenze e permette agli235strumenti di tenere meglio la traccia della storia del codice.236 237Prima di inviare una patch, verificatene lo stile usando l'apposito238verificatore (scripts/checkpatch.pl). Da notare, comunque, che il verificator239di stile dovrebbe essere visto come una guida, non come un sostituto al240giudizio umano. Se il vostro codice è migliore nonostante una violazione241dello stile, probabilmente è meglio lasciarlo com'è.242 243Il verificatore ha tre diversi livelli di severità:244 - ERROR: le cose sono molto probabilmente sbagliate245 - WARNING: le cose necessitano d'essere revisionate con attenzione246 - CHECK: le cose necessitano di un pensierino247 248Dovreste essere in grado di giustificare tutte le eventuali violazioni rimaste249nella vostra patch.250 251 2525) Selezionate i destinatari della vostra patch253-----------------------------------------------254 255Dovreste sempre inviare una copia della patch ai manutentori e alle liste di256discussione dei sottosistemi interessati dalle modifiche; date un'occhiata al257file MAINTAINERS e alla storia delle revisioni per scoprire chi si occupa del258codice. Lo script scripts/get_maintainer.pl può esservi d'aiuto (passategli il259percorso alle vostre patch). Se non riuscite a trovare un manutentore per il260sottosistema su cui state lavorando, allora Andrew Morton261(akpm@linux-foundation.org) sarà la vostra ultima possibilità.262 263La lista linux-kernel@vger.kernel.org dovrebbe essere usata per l'invio di tutte264le patch, ma il volume ha raggiunto un livello tale d'aver spinto alcuni265sviluppatori a non seguirla più. Dunque, per favore, evitate di inviare messaggi266scorrelati al tema della lista o a persone che non dovrebbero essere267interessate all'argomento.268 269Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la270vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org271dovrebbe essere usata per inviare tutte le patch, ma il traffico è tale per cui272diversi sviluppatori la trascurano. Guardate nel file MAINTAINERS per trovare la273lista di discussione dedicata ad un sottosistema; probabilmente lì la vostra274patch riceverà molta più attenzione. Tuttavia, per favore, non spammate le liste275di discussione che non sono interessate al vostro lavoro.276 277Molte delle liste di discussione relative al kernel vengono ospitate su278vger.kernel.org; potete trovare un loro elenco alla pagina279http://vger.kernel.org/vger-lists.html. Tuttavia, ci sono altre liste di280discussione ospitate altrove.281 282Non inviate più di 15 patch alla volta sulle liste di discussione vger!!!283 284L'ultimo giudizio sull'integrazione delle modifiche accettate spetta a285Linux Torvalds. Il suo indirizzo e-mail è <torvalds@linux-foundation.org>.286Riceve moltissime e-mail, e, a questo punto, solo poche patch passano287direttamente attraverso il suo giudizio; quindi, dovreste fare del vostro288meglio per -evitare di- inviargli e-mail.289 290Se avete una patch che corregge un baco di sicurezza che potrebbe essere291sfruttato, inviatela a security@kernel.org. Per bachi importanti, un breve292embargo potrebbe essere preso in considerazione per dare il tempo alle293distribuzioni di prendere la patch e renderla disponibile ai loro utenti;294in questo caso, ovviamente, la patch non dovrebbe essere inviata su alcuna295lista di discussione pubblica. Leggete anche296Documentation/process/security-bugs.rst.297 298Patch che correggono bachi importanti su un kernel già rilasciato, dovrebbero299essere inviate ai manutentori dei kernel stabili aggiungendo la seguente riga::300 301 Cc: stable@vger.kernel.org302 303nella vostra patch, nell'area dedicata alle firme (notate, NON come destinatario304delle e-mail). In aggiunta a questo file, dovreste leggere anche305Documentation/translations/it_IT/process/stable-kernel-rules.rst.306 307Se le modifiche hanno effetti sull'interfaccia con lo spazio utente, per favore308inviate una patch per le pagine man ai manutentori di suddette pagine (elencati309nel file MAINTAINERS), o almeno una notifica circa la vostra modifica,310cosicché l'informazione possa trovare la sua strada nel manuale. Le modifiche311all'API dello spazio utente dovrebbero essere inviate in copia anche a312linux-api@vger.kernel.org.313 314Niente: MIME, links, compressione, allegati. Solo puro testo315-------------------------------------------------------------316 317Linus e gli altri sviluppatori del kernel devono poter commentare318le modifiche che sottomettete. Per uno sviluppatore è importante319essere in grado di "citare" le vostre modifiche, usando normali320programmi di posta elettronica, cosicché sia possibile commentare321una porzione specifica del vostro codice.322 323Per questa ragione tutte le patch devono essere inviate via e-mail324come testo. Il modo più facile, e quello raccomandato, è con ``git325send-email``. Al sito https://git-send-email.io è disponibile una326guida interattiva sull'uso di ``git send-email``.327 328Se decidete di non usare ``git send-email``:329 330.. warning::331 332 Se decidete di copiare ed incollare la patch nel corpo dell'e-mail, state333 attenti che il vostro programma non corrompa il contenuto con andate334 a capo automatiche.335 336La patch non deve essere un allegato MIME, compresso o meno. Molti337dei più popolari programmi di posta elettronica non trasmettono un allegato338MIME come puro testo, e questo rende impossibile commentare il vostro codice.339Inoltre, un allegato MIME rende l'attività di Linus più laboriosa, diminuendo340così la possibilità che il vostro allegato-MIME venga accettato.341 342Eccezione: se il vostro servizio di posta storpia le patch, allora qualcuno343potrebbe chiedervi di rinviarle come allegato MIME.344 345Leggete Documentation/translations/it_IT/process/email-clients.rst346per dei suggerimenti sulla configurazione del programmi di posta elettronica347per l'invio di patch intatte.348 349Rispondere ai commenti di revisione350-----------------------------------351 352In risposta alla vostra email, quasi certamente i revisori vi353invieranno dei commenti su come migliorare la vostra patch. Dovete354rispondere a questi commenti; ignorare i revisori è un ottimo modo per355essere ignorati. Riscontri o domande che non conducono ad una356modifica del codice quasi certamente dovrebbero portare ad un commento357nel changelog cosicché il prossimo revisore potrà meglio comprendere358cosa stia accadendo.359 360Assicuratevi di dire ai revisori quali cambiamenti state facendo e di361ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che362richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in363questo caso, rispondete con educazione e concentratevi sul problema che hanno364evidenziato. Quando inviate una versione successiva ricordatevi di aggiungere un365``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando366le differenze rispetto a sottomissioni precedenti (vedere367:ref:`it_the_canonical_patch_format`). Aggiungete a CC tutte le persone che368vi hanno fornito dei commenti per notificarle di eventuali nuove versioni.369 370Leggete Documentation/translations/it_IT/process/email-clients.rst per371le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare372sulle liste di discussione.373 374.. _it_interleaved_replies:375 376Rispondere alle email in riga e riducendo la citazioni377------------------------------------------------------378 379Nelle discussioni riguardo allo sviluppo del kernel viene fortemente scoraggiato380l'uso di risposte in cima ai messaggi di posta elettronica. Rispondere in riga381rende le conversazioni molto più scorrevoli. Maggiori dettagli possono essere382trovati qui: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style383 384Come spesso citato nelle liste di discussione::385 386 R: http://en.wikipedia.org/wiki/Top_post387 D: Dove posso trovare informazioni riguardo alle "risposte in cima"?388 R: Perché incasina il normale ordine con cui si legge un testo.389 D: Perché è così terribile rispondere in cima?390 R: Risposte in cima.391 Q: Qual è la cosa più fastidiosa nei messaggi di posta elettronica?392 393Allo stesso modo, per favore eliminate tutte le citazioni non necessarie per la394vostra risposta. Questo permette di trovare più facilmente le risposte, e395permette di risparmiare tempo e spazio. Per maggiori dettagli:396http://daringfireball.net/2007/07/on_top ::397 398 R: No.399 D: Dovrei includere un blocco di citazione dopo la mia risposta?400 401.. _it_resend_reminders:402 403Non scoraggiatevi - o impazientitevi404------------------------------------405 406Dopo che avete inviato le vostre modifiche, siate pazienti e aspettate.407I revisori sono persone occupate e potrebbero non ricevere la vostra patch408immediatamente.409 410Un tempo, le patch erano solite scomparire nel vuoto senza alcun commento, ma411ora il processo di sviluppo funziona meglio. Dovreste ricevere commenti in poche412settimane (tipicamente 2 o 3); se questo non dovesse accadere, assicuratevi di413aver inviato le patch correttamente. Aspettate almeno una settimana prima di414rinviare le modifiche o sollecitare i revisori - probabilmente anche di più415durante la finestra d'integrazione.416 417Potete anche rinviare la patch, o la serie di patch, dopo un paio di settimane418aggiungendo la parola "RESEND" nel titolo::419 420 [PATCH Vx RESEND] sub/sys: Condensed patch summary421 422Ma non aggiungete "RESEND" quando state sottomettendo una versione modificata423della vostra patch, o serie di patch - "RESEND" si applica solo alla424sottomissione di patch, o serie di patch, che non hanno subito modifiche425dall'ultima volta che sono state inviate.426 427Aggiungete PATCH nell'oggetto428-----------------------------429 430Dato l'alto volume di e-mail per Linus, e la lista linux-kernel, è prassi431prefiggere il vostro oggetto con [PATCH]. Questo permette a Linus e agli432altri sviluppatori del kernel di distinguere facilmente le patch dalle altre433discussioni.434 435``git send-email`` lo fa automaticamente.436 437 438Firmate il vostro lavoro - Il certificato d'origine dello sviluppatore439----------------------------------------------------------------------440 441Per migliorare la tracciabilità su "chi ha fatto cosa", specialmente per442quelle patch che per raggiungere lo stadio finale passano attraverso443diversi livelli di manutentori, abbiamo introdotto la procedura di "firma"444delle patch che vengono inviate per e-mail.445 446La firma è una semplice riga alla fine della descrizione della patch che447certifica che l'avete scritta voi o che avete il diritto di pubblicarla448come patch open-source. Le regole sono abbastanza semplici: se potete449certificare quanto segue:450 451Il certificato d'origine dello sviluppatore 1.1452^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^453 454Contribuendo a questo progetto, io certifico che:455 456 (a) Il contributo è stato creato interamente, o in parte, da me e che457 ho il diritto di inviarlo in accordo con la licenza open-source458 indicata nel file; oppure459 460 (b) Il contributo è basato su un lavoro precedente che, nei limiti461 della mia conoscenza, è coperto da un'appropriata licenza462 open-source che mi da il diritto di modificarlo e inviarlo,463 le cui modifiche sono interamente o in parte mie, in accordo con464 la licenza open-source (a meno che non abbia il permesso di usare465 un'altra licenza) indicata nel file; oppure466 467 (c) Il contributo mi è stato fornito direttamente da qualcuno che468 ha certificato (a), (b) o (c) e non l'ho modificata.469 470 (d) Capisco e concordo col fatto che questo progetto e i suoi471 contributi sono pubblici e che un registro dei contributi (incluse472 tutte le informazioni personali che invio con essi, inclusa la mia473 firma) verrà mantenuto indefinitamente e che possa essere474 ridistribuito in accordo con questo progetto o le licenze475 open-source coinvolte.476 477poi dovete solo aggiungere una riga che dice::478 479 Signed-off-by: Random J Developer <random@developer.example.org>480 481usando il vostro vero nome (spiacenti, non si accettano482contributi anonimi). Questo verrà fatto automaticamente se usate483``git commit -s``. Anche il ripristino di uno stato precedente dovrebbe484includere "Signed-off-by", se usate ``git revert -s`` questo verrà485fatto automaticamente.486 487Alcune persone aggiungono delle etichette alla fine. Per ora queste verranno488ignorate, ma potete farlo per meglio identificare procedure aziendali interne o489per aggiungere dettagli circa la firma.490 491In seguito al SoB (Signed-off-by:) dell'autore ve ne sono altri da492parte di tutte quelle persone che si sono occupate della gestione e493del trasporto della patch. Queste però non sono state coinvolte nello494sviluppo, ma la loro sequenza d'apparizione ci racconta il percorso495**reale** che una patch a intrapreso dallo sviluppatore, fino al496manutentore, per poi giungere a Linus.497 498 499Quando utilizzare Acked-by:, Cc:, e Co-developed-by:500----------------------------------------------------501 502L'etichetta Signed-off-by: indica che il firmatario è stato coinvolto nello503sviluppo della patch, o che era nel suo percorso di consegna.504 505Se una persona non è direttamente coinvolta con la preparazione o gestione506della patch ma desidera firmare e mettere agli atti la loro approvazione,507allora queste persone possono chiedere di aggiungere al changelog della patch508una riga Acked-by:.509 510Acked-by: viene spesso utilizzato dai manutentori del sottosistema in oggetto511quando quello stesso manutentore non ha contribuito né trasmesso la patch.512 513Acked-by: non è formale come Signed-off-by:. Questo indica che la persona ha514revisionato la patch e l'ha trovata accettabile. Per cui, a volte, chi515integra le patch convertirà un "sì, mi sembra che vada bene" in un Acked-by:516(ma tenete presente che solitamente è meglio chiedere esplicitamente).517 518Acked-by: non indica l'accettazione di un'intera patch. Per esempio, quando519una patch ha effetti su diversi sottosistemi e ha un Acked-by: da un520manutentore di uno di questi, significa che il manutentore accetta quella521parte di codice relativa al sottosistema che mantiene. Qui dovremmo essere522giudiziosi. Quando si hanno dei dubbi si dovrebbe far riferimento alla523discussione originale negli archivi della lista di discussione.524 525Se una persona ha avuto l'opportunità di commentare la patch, ma non lo ha526fatto, potete aggiungere l'etichetta ``Cc:`` alla patch. Questa è l'unica527etichetta che può essere aggiunta senza che la persona in questione faccia528alcunché - ma dovrebbe indicare che la persona ha ricevuto una copia della529patch. Questa etichetta documenta che terzi potenzialmente interessati sono530stati inclusi nella discussione.531 532Co-developed-by: indica che la patch è stata cosviluppata da diversi533sviluppatori; viene usato per assegnare più autori (in aggiunta a quello534associato all'etichetta From:) quando più persone lavorano ad una patch. Dato535che Co-developed-by: implica la paternità della patch, ogni Co-developed-by:536dev'essere seguito immediatamente dal Signed-off-by: del corrispondente537coautore. Qui si applica la procedura di base per sign-off, in pratica538l'ordine delle etichette Signed-off-by: dovrebbe riflettere il più possibile539l'ordine cronologico della storia della patch, indipendentemente dal fatto che540la paternità venga assegnata via From: o Co-developed-by:. Da notare che541l'ultimo Signed-off-by: dev'essere quello di colui che ha sottomesso la patch.542 543Notate anche che l'etichetta From: è opzionale quando l'autore in From: è544anche la persona (e indirizzo email) indicato nel From: dell'intestazione545dell'email.546 547Esempio di una patch sottomessa dall'autore in From:::548 549 <changelog>550 551 Co-developed-by: First Co-Author <first@coauthor.example.org>552 Signed-off-by: First Co-Author <first@coauthor.example.org>553 Co-developed-by: Second Co-Author <second@coauthor.example.org>554 Signed-off-by: Second Co-Author <second@coauthor.example.org>555 Signed-off-by: From Author <from@author.example.org>556 557Esempio di una patch sottomessa dall'autore Co-developed-by:::558 559 From: From Author <from@author.example.org>560 561 <changelog>562 563 Co-developed-by: Random Co-Author <random@coauthor.example.org>564 Signed-off-by: Random Co-Author <random@coauthor.example.org>565 Signed-off-by: From Author <from@author.example.org>566 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>567 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>568 569Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:570-------------------------------------------------------------------------571 572L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi573e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.574Rammentate che se il baco è stato riportato in privato, dovrete chiedere il575permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va576usata per i bachi, dunque non usatela per richieste di nuove funzionalità.577Questa etichetta dovrebbe essere seguita da quella Closes: con un indirizzo al578rapporto, a meno che questo non sia disponibile sul web. L'etichetta Link: può579essere usata in alternativa a Closes: se la patch corregge solo in parte il580problema riportato nel rapporto.581 582L'etichetta Tested-by: indica che la patch è stata verificata con successo583(su un qualche sistema) dalla persona citata. Questa etichetta informa i584manutentori che qualche verifica è stata fatta, fornisce un mezzo per trovare585persone che possano verificare il codice in futuro, e garantisce che queste586stesse persone ricevano credito per il loro lavoro.587 588Reviewed-by:, invece, indica che la patch è stata revisionata ed è stata589considerata accettabile in accordo con la dichiarazione dei revisori:590 591Dichiarazione di svista dei revisori592^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^593 594Offrendo la mia etichetta Reviewed-by, dichiaro quanto segue:595 596 (a) Ho effettuato una revisione tecnica di questa patch per valutarne597 l'adeguatezza ai fini dell'inclusione nel ramo principale del598 kernel.599 600 (b) Tutti i problemi e le domande riguardanti la patch sono stati601 comunicati al mittente. Sono soddisfatto dalle risposte602 del mittente.603 604 (c) Nonostante ci potrebbero essere cose migliorabili in queste605 sottomissione, credo che sia, in questo momento, (1) una modifica606 di interesse per il kernel, e (2) libera da problemi che607 potrebbero metterne in discussione l'integrazione.608 609 (d) Nonostante abbia revisionato la patch e creda che vada bene,610 non garantisco (se non specificato altrimenti) che questa611 otterrà quello che promette o funzionerà correttamente in tutte612 le possibili situazioni.613 614L'etichetta Reviewed-by è la dichiarazione di un parere sulla bontà di615una modifica che si ritiene appropriata e senza alcun problema tecnico616importante. Qualsiasi revisore interessato (quelli che lo hanno fatto)617possono offrire il proprio Reviewed-by per la patch. Questa etichetta serve618a dare credito ai revisori e a informare i manutentori sul livello di revisione619che è stato fatto sulla patch. L'etichetta Reviewed-by, quando fornita da620revisori conosciuti per la loro conoscenza sulla materia in oggetto e per la621loro serietà nella revisione, accrescerà le probabilità che la vostra patch622venga integrate nel kernel.623 624Quando si riceve una email sulla lista di discussione da un tester o625un revisore, le etichette Tested-by o Reviewed-by devono essere626aggiunte dall'autore quando invierà nuovamente la patch. Tuttavia, se627la patch è cambiata in modo significativo, queste etichette potrebbero628non avere più senso e quindi andrebbero rimosse. Solitamente si tiene traccia629della rimozione nel changelog della patch (subito dopo il separatore '---').630 631L'etichetta Suggested-by: indica che l'idea della patch è stata suggerita632dalla persona nominata e le da credito. Tenete a mente che questa etichetta633non dovrebbe essere aggiunta senza un permesso esplicito, specialmente se634l'idea non è stata pubblicata in un forum pubblico. Detto ciò, dando credito635a chi ci fornisce delle idee, si spera di poterli ispirare ad aiutarci636nuovamente in futuro.637 638L'etichetta Fixes: indica che la patch corregge un problema in un commit639precedente. Serve a chiarire l'origine di un baco, il che aiuta la revisione640del baco stesso. Questa etichetta è di aiuto anche per i manutentori dei641kernel stabili al fine di capire quale kernel deve ricevere la correzione.642Questo è il modo suggerito per indicare che un baco è stato corretto nella643patch. Per maggiori dettagli leggete :ref:`it_describe_changes`644 645Da notare che aggiungere un tag "Fixes:" non esime dalle regole646previste per i kernel stabili, e nemmeno dalla necessità di aggiungere647in copia conoscenza stable@vger.kernel.org su tutte le patch per648suddetti kernel.649 650.. _it_the_canonical_patch_format:651 652Il formato canonico delle patch653-------------------------------654 655Questa sezione descrive il formato che dovrebbe essere usato per le patch.656Notate che se state usando un repositorio ``git`` per salvare le vostre patch657potere usare il comando ``git format-patch`` per ottenere patch nel formato658appropriato. Lo strumento non crea il testo necessario, per cui, leggete659le seguenti istruzioni.660 661L'oggetto di una patch canonica è la riga::662 663 Subject: [PATCH 001/123] subsystem: summary phrase664 665Il corpo di una patch canonica contiene i seguenti elementi:666 667 - Una riga ``from`` che specifica l'autore della patch, seguita668 da una riga vuota (necessaria soltanto se la persona che invia la669 patch non ne è l'autore).670 671 - Il corpo della spiegazione, con linee non più lunghe di 75 caratteri,672 che verrà copiato permanentemente nel changelog per descrivere la patch.673 674 - Una riga vuota675 676 - Le righe ``Signed-off-by:``, descritte in precedenza, che finiranno677 anch'esse nel changelog.678 679 - Una linea di demarcazione contenente semplicemente ``---``.680 681 - Qualsiasi altro commento che non deve finire nel changelog.682 683 - Le effettive modifiche al codice (il prodotto di ``diff``).684 685Il formato usato per l'oggetto permette ai programmi di posta di usarlo686per ordinare le patch alfabeticamente - tutti i programmi di posta hanno687questa funzionalità - dato che al numero sequenziale si antepongono degli zeri;688in questo modo l'ordine numerico ed alfabetico coincidono.689 690Il ``subsystem`` nell'oggetto dell'email dovrebbe identificare l'area691o il sottosistema modificato dalla patch.692 693La ``summary phrase`` nell'oggetto dell'email dovrebbe descrivere brevemente694il contenuto della patch. La ``summary phrase`` non dovrebbe essere un nome695di file. Non utilizzate la stessa ``summary phrase`` per tutte le patch in696una serie (dove una ``serie di patch`` è una sequenza ordinata di diverse697patch correlate).698 699Ricordatevi che la ``summary phrase`` della vostra email diventerà un700identificatore globale ed unico per quella patch. Si propaga fino al701changelog ``git``. La ``summary phrase`` potrà essere usata in futuro702dagli sviluppatori per riferirsi a quella patch. Le persone vorranno703cercare la ``summary phrase`` su internet per leggere le discussioni che la704riguardano. Potrebbe anche essere l'unica cosa che le persone vedranno705quando, in due o tre mesi, riguarderanno centinaia di patch usando strumenti706come ``gitk`` o ``git log --oneline``.707 708Per queste ragioni, dovrebbe essere lunga fra i 70 e i 75 caratteri, e deve709descrivere sia cosa viene modificato, sia il perché sia necessario. Essere710brevi e descrittivi è una bella sfida, ma questo è quello che fa un riassunto711ben scritto.712 713La ``summary phrase`` può avere un'etichetta (*tag*) di prefisso racchiusa fra714le parentesi quadre "Subject: [PATCH <tag>...] <summary phrase>".715Le etichette non verranno considerate come parte della frase riassuntiva, ma716indicano come la patch dovrebbe essere trattata. Fra le etichette più comuni717ci sono quelle di versione che vengono usate quando una patch è stata inviata718più volte (per esempio, "v1, v2, v3"); oppure "RFC" per indicare che si719attendono dei commenti (*Request For Comments*).720 721Se ci sono quattro patch nella serie, queste dovrebbero essere722enumerate così: 1/4, 2/4, 3/4, 4/4. Questo assicura che gli723sviluppatori capiranno l'ordine in cui le patch dovrebbero essere724applicate, e per tracciare quelle che hanno revisionate o che hanno725applicato.726 727Un paio di esempi di oggetti::728 729 Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching730 Subject: [PATCH v2 01/27] x86: fix eflags tracking731 Subject: [PATCH v2] sub/sys: Condensed patch summary732 Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary733 734La riga ``from`` dev'essere la prima nel corpo del messaggio ed è nel735formato:736 737 From: Patch Author <author@example.com>738 739La riga ``from`` indica chi verrà accreditato nel changelog permanente come740l'autore della patch. Se la riga ``from`` è mancante, allora per determinare741l'autore da inserire nel changelog verrà usata la riga ``From``742nell'intestazione dell'email.743 744Il corpo della spiegazione verrà incluso nel changelog permanente, per cui745deve aver senso per un lettore esperto che è ha dimenticato i dettagli della746discussione che hanno portato alla patch. L'inclusione di informazioni747sui problemi oggetto dalla patch (messaggi del kernel, messaggi di oops,748eccetera) è particolarmente utile per le persone che potrebbero cercare fra749i messaggi di log per la patch che li tratta. Il testo dovrebbe essere scritto750con abbastanza dettagli da far capire al lettore **perché** quella751patch fu creata, e questo a distanza di settimane, mesi, o addirittura752anni.753 754Se la patch corregge un errore di compilazione, non sarà necessario755includere proprio _tutto_ quello che è uscito dal compilatore;756aggiungete solo quello che è necessario per far si che la vostra patch757venga trovata. Come nella ``summary phrase``, è importante essere sia758brevi che descrittivi.759 760La linea di demarcazione ``---`` serve essenzialmente a segnare dove finisce761il messaggio di changelog.762 763Aggiungere il ``diffstat`` dopo ``---`` è un buon uso di questo spazio, per764mostrare i file che sono cambiati, e il numero di file aggiunto o rimossi.765Un ``diffstat`` è particolarmente utile per le patch grandi. Se766includete un ``diffstat`` dopo ``---``, usate le opzioni ``-p 1 -w70``767cosicché i nomi dei file elencati non occupino troppo spazio768(facilmente rientreranno negli 80 caratteri, magari con qualche769indentazione). (``git`` genera di base dei diffstat adatti).770 771I commenti che sono importanti solo per i manutentori, quindi772inadatti al changelog permanente, dovrebbero essere messi qui. Un773buon esempio per questo tipo di commenti potrebbe essere il cosiddetto774``patch changelogs`` che descrivere le differenze fra le versioni775della patch.776 777Queste informazioni devono andare **dopo** la linea ``---`` che separa778il *changelog* dal resto della patch. Le informazioni riguardanti la779versione di una patch non sono parte del *chagelog* che viene incluso780in git. Queste sono informazioni utili solo ai revisori. Se venissero781messe sopra la riga, qualcuno dovrà fare del lavoro manuale per782rimuoverle; cosa che invece viene fatta automaticamente quando vengono783messe correttamente oltre la riga.::784 785 <commit message>786 ...787 Signed-off-by: Author <author@mail>788 ---789 V2 -> V3: Removed redundant helper function790 V1 -> V2: Cleaned up coding style and addressed review comments791 792 path/to/file | 5+++--793 ...794 795Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.796 797.. _it_backtraces:798 799Aggiungere i *backtrace* nei messaggi di commit800^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^801 802I *backtrace* aiutano a documentare la sequenza di chiamate a funzione803che portano ad un problema. Tuttavia, non tutti i *backtrace* sono804davvero utili. Per esempio, le sequenze iniziali di avvio sono uniche805e ovvie. Copiare integralmente l'output di ``dmesg`` aggiunge tante806informazioni che distraggono dal vero problema (per esempio, i807marcatori temporali, la lista dei moduli, la lista dei registri, lo808stato dello stack).809 810Quindi, per rendere utile un *backtrace* dovreste eliminare le811informazioni inutili, cosicché ci si possa focalizzare sul812problema. Ecco un esempio di un *backtrace* essenziale::813 814 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)815 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)816 Call Trace:817 mba_wrmsr818 update_domains819 rdtgroup_mkdir820 821.. _it_explicit_in_reply_to:822 823Usare esplicitamente In-Reply-To nell'intestazione824--------------------------------------------------825 826Aggiungere manualmente In-Reply-To: nell'intestazione dell'e-mail827potrebbe essere d'aiuto per associare una patch ad una discussione828precedente, per esempio per collegare la correzione di un baco con l'e-mail829che lo riportava. Tuttavia, per serie di patch multiple è generalmente830sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.831In questo modo versioni multiple di una patch non diventeranno un'ingestibile832giungla di riferimenti all'interno dei programmi di posta. Se un collegamento833è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti834ad una versione precedente di una serie di patch (per esempio, potete usarlo835per l'email introduttiva alla serie).836 837Fornire informazioni circa i sorgenti838-------------------------------------839 840Quando gli altri sviluppatori ricevono le vostre patch e iniziano il processo di841revisione, è assolutamente necessario che sappiano qual è il commit/ramo di base842su cui si base il vostro lavoro: considerate l'enorme quantità di sorgenti dei843manutentori presenti al giorno d'oggi. Si noti ancora una volta la voce **T:**844nel file MAINTAINERS spiegato sopra.845 846Questo è ancora più importante per i processi automatizzati di CI che tentano di847eseguire una serie di test per stabilire la qualità del codice prima che il848manutentore inizi la revisione.849 850Se si usa ``git format-patch`` per generare le patch, si possono includere851automaticamente le informazioni sull'albero di base nell'invio usando il flag852``--base``. Il modo più semplice e comodo di usare questa opzione è con i rami853topici::854 855 $ git checkout -t -b my-topical-branch master856 Branch 'my-topical-branch' set up to track local branch 'master'.857 Switched to a new branch 'my-topical-branch'858 859 [perform your edits and commits]860 861 $ git format-patch --base=auto --cover-letter -o outgoing/ master862 outgoing/0000-cover-letter.patch863 outgoing/0001-First-Commit.patch864 outgoing/...865 866Aprendo ``outgoing/0000-cover-letter.patch`` per la modifica, si noterà867che ha ``base-commit:`` in fondo, questo fornisce al revisore e agli868strumenti CI informazioni sufficienti per eseguire correttamente ``git am``869senza preoccuparsi dei conflitti::870 871 $ git checkout -b patch-review [base-commit-id]872 Switched to a new branch 'patch-review'873 $ git am patches.mbox874 Applying: First Commit875 Applying: ...876 877Consultate ``man git-format-patch`` per maggiori informazioni circa questa878opzione.879 880.. note::881 882 L'opzione ``--base`` fu introdotta con git versione 2.9.0883 884Se non si usa git per produrre le patch, si può comunque includere885``base-commit`` per indicare l'hash del commit dei sorgenti su cui si basa il886lavoro. Dovreste aggiungerlo nella lettera di accompagnamento o nella prima887patch della serie e dovrebbe essere collocato sotto la riga ``---`` o in fondo a888tutti gli altri contenuti, subito prima della vostra firma e-mail.889 890Assicuratevi che il commit si basi su sorgenti ufficiali del891manutentore/mainline e non su sorgenti interni, accessibile solo a voi,892altrimenti sarebbe inutile.893 894Riferimenti895-----------896 897Andrew Morton, "La patch perfetta" (tpp).898 <https://www.ozlabs.org/~akpm/stuff/tpp.txt>899 900Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux"901 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>902 903Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema"904 <http://www.kroah.com/log/linux/maintainer.html>905 906 <http://www.kroah.com/log/linux/maintainer-02.html>907 908 <http://www.kroah.com/log/linux/maintainer-03.html>909 910 <http://www.kroah.com/log/linux/maintainer-04.html>911 912 <http://www.kroah.com/log/linux/maintainer-05.html>913 914 <http://www.kroah.com/log/linux/maintainer-06.html>915 916No!!!! Basta gigantesche bombe patch alle persone sulla lista linux-kernel@vger.kernel.org!917 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>918 919Kernel Documentation/translations/it_IT/process/coding-style.rst.920 921E-mail di Linus Torvalds sul formato canonico di una patch:922 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>923 924Andi Kleen, "Su come sottomettere patch del kernel"925 Alcune strategie su come sottomettere modifiche toste o controverse.926 927 http://halobates.de/on-submitting-patches.pdf928