5.Posting.rst (18337B)
1.. include:: ../disclaimer-ita.rst 2 3:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` 4:Translator: Federico Vaga <federico.vaga@vaga.pv.it> 5 6.. _it_development_posting: 7 8Pubblicare modifiche 9==================== 10 11Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere 12presentato alla comunità per una revisione ed eventualmente per la sua 13inclusione nel ramo principale del kernel. Com'era prevedibile, 14la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni 15e di procedure per la pubblicazione delle patch; seguirle renderà la vita 16più facile a tutti quanti. Questo documento cercherà di coprire questi 17argomenti con un ragionevole livello di dettaglio; più informazioni possono 18essere trovare nella cartella 'Documentation', nei file 19:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`, 20:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e 21:ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. 22 23 24Quando pubblicarle 25------------------ 26 27C'è sempre una certa resistenza nel pubblicare patch finché non sono 28veramente "pronte". Per semplici patch questo non è un problema. 29Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare 30dai riscontri che la comunità può darvi prima che completiate il lavoro. 31Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche 32preparare un ramo git disponibile agli sviluppatori interessati, cosicché 33possano stare al passo col vostro lavoro in qualunque momento. 34 35Quando pubblicate del codice che non è considerato pronto per l'inclusione, 36è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete 37informazioni sulle cose ancora da sviluppare e sui problemi conosciuti. 38Poche persone guarderanno delle patch che si sa essere fatte a metà, 39ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro 40sviluppo nella giusta direzione. 41 42 43Prima di creare patch 44--------------------- 45 46Ci sono un certo numero di cose che dovreste fare prima di considerare 47l'invio delle patch alla comunità di sviluppo. Queste cose includono: 48 49 - Verificare il codice fino al massimo che vi è consentito. Usate gli 50 strumenti di debug del kernel, assicuratevi che il kernel compili con 51 tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori 52 per compilare il codice per differenti architetture, eccetera. 53 54 - Assicuratevi che il vostro codice sia conforme alla linee guida del 55 kernel sullo stile del codice. 56 57 - La vostra patch ha delle conseguenze in termini di prestazioni? 58 Se è così, dovreste eseguire dei *benchmark* che mostrino il loro 59 impatto (anche positivo); un riassunto dei risultati dovrebbe essere 60 incluso nella patch. 61 62 - Siate certi d'avere i diritti per pubblicare il codice. Se questo 63 lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su 64 questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione 65 con una licenza GPL 66 67Come regola generale, pensarci un po' di più prima di inviare il codice 68ripaga quasi sempre lo sforzo. 69 70 71Preparazione di una patch 72------------------------- 73 74La preparazione delle patch per la pubblicazione può richiedere una quantità 75di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo 76di risparmiare tempo in questa fase, anche sul breve periodo. 77 78Le patch devono essere preparate per una specifica versione del kernel. 79Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale 80così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo 81principale, cominciate da un punto di rilascio ben noto - uno stabile o 82un -rc - piuttosto che creare il vostro ramo da quello principale in un punto 83a caso. 84 85Per facilitare una revisione e una verifica più estesa, potrebbe diventare 86necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un 87sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere 88un lavoro significativo nella risoluzione dei conflitti e nella correzione dei 89cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse 90della vostra patch e da quello che succede altrove nel kernel. 91 92Solo le modifiche più semplici dovrebbero essere preparate come una singola 93patch; tutto il resto dovrebbe essere preparato come una serie logica di 94modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori 95passano molto tempo nel capire come farlo in modo che piaccia alla comunità. 96Ci sono alcune regole spannometriche, che comunque possono aiutare 97considerevolmente: 98 99 - La serie di patch che pubblicherete, quasi sicuramente, non sarà 100 come quella che trovate nel vostro sistema di controllo di versione. 101 Invece, le vostre modifiche dovranno essere considerate nella loro forma 102 finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori 103 sono interessati in modifiche che siano discrete e indipendenti, non 104 alla strada che avete percorso per ottenerle. 105 106 - Ogni modifica logicamente indipendente dovrebbe essere preparata come una 107 patch separata. Queste modifiche possono essere piccole ("aggiunto un 108 campo in questa struttura") o grandi (l'aggiunta di un driver nuovo, 109 per esempio), ma dovrebbero essere concettualmente piccole da permettere 110 una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche 111 specifiche che si possano revisionare indipendentemente e di cui si possa 112 verificare la veridicità. 113 114 - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di 115 modifiche nella stessa patch. Se una modifica corregge un baco critico 116 per la sicurezza, riorganizza alcune strutture, e riformatta il codice, 117 ci sono buone probabilità che venga ignorata e che la correzione importante 118 venga persa. 119 120 - Ogni modifica dovrebbe portare ad un kernel che compila e funziona 121 correttamente; se la vostra serie di patch si interrompe a metà il 122 risultato dovrebbe essere comunque un kernel funzionante. L'applicazione 123 parziale di una serie di patch è uno scenario comune nel quale il 124 comando "git bisect" viene usato per trovare delle regressioni; se il 125 risultato è un kernel guasto, renderete la vita degli sviluppatori più 126 difficile così come quella di chi s'impegna nel nobile lavoro di 127 scovare i problemi. 128 129 - Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500 130 patch che modificavano un unico file - un atto che non lo rese la persona 131 più popolare sulla lista di discussione del kernel. Una singola patch 132 può essere ragionevolmente grande fintanto che contenga un singolo 133 cambiamento *logico*. 134 135 - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura 136 come una serie di patch, ma di lasciare questa infrastruttura inutilizzata 137 finché l'ultima patch della serie non abilita tutto quanto. Quando è 138 possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle 139 regressioni, "bisect" indicherà quest'ultima patch come causa del 140 problema anche se il baco si trova altrove. Possibilmente, quando una 141 patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente. 142 143Lavorare per creare la serie di patch perfetta potrebbe essere frustrante 144perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è 145già stato fatto. Quando ben fatto, comunque, è tempo ben speso. 146 147 148Formattazione delle patch e i changelog 149--------------------------------------- 150 151Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione, 152ma il lavoro non è davvero finito. Ogni patch deve essere preparata con 153un messaggio che spieghi al resto del mondo, in modo chiaro e veloce, 154il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi: 155 156 - Un campo opzionale "From" col nome dell'autore della patch. Questa riga 157 è necessaria solo se state passando la patch di qualcun altro via email, 158 ma nel dubbio non fa di certo male aggiungerlo. 159 160 - Una descrizione di una riga che spieghi cosa fa la patch. Questo 161 messaggio dovrebbe essere sufficiente per far comprendere al lettore lo 162 scopo della patch senza altre informazioni. Questo messaggio, 163 solitamente, presenta in testa il nome del sottosistema a cui si riferisce, 164 seguito dallo scopo della patch. Per esempio: 165 166 :: 167 168 gpio: fix build on CONFIG_GPIO_SYSFS=n 169 170 - Una riga bianca seguita da una descrizione dettagliata della patch. 171 Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare 172 cosa fa e perché dovrebbe essere aggiunta al kernel. 173 174 - Una o più righe etichette, con, minimo, una riga *Signed-off-by:* 175 col nome dall'autore della patch. Queste etichette verranno descritte 176 meglio più avanti. 177 178Gli elementi qui sopra, assieme, formano il changelog di una patch. 179Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata; 180vale la pena spendere qualche parola in più al riguardo. Quando scrivete 181un changelog dovreste tenere ben presente che molte persone leggeranno 182le vostre parole. Queste includono i manutentori di un sotto-sistema, e i 183revisori che devono decidere se la patch debba essere inclusa o no, 184le distribuzioni e altri manutentori che cercano di valutare se la patch 185debba essere applicata su kernel più vecchi, i cacciatori di bachi che si 186chiederanno se la patch è la causa di un problema che stanno cercando, 187gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri. 188Un buon changelog fornisce le informazioni necessarie a tutte queste 189persone nel modo più diretto e conciso possibile. 190 191A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della 192modifica e la motivazione della patch nel modo migliore possibile nonostante 193il limite di una sola riga. La descrizione dettagliata può spiegare meglio 194i temi e fornire maggiori informazioni. Se una patch corregge un baco, 195citate, se possibile, il commit che lo introdusse (e per favore, quando 196citate un commit aggiungete sia il suo identificativo che il titolo), 197Se il problema è associabile ad un file di log o all' output del compilatore, 198includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso 199problema. Se la modifica ha lo scopo di essere di supporto a sviluppi 200successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste 201modifiche e come gli altri dovrebbero agire per applicarle. In generale, 202più riuscirete ad entrare nei panni di tutti quelli che leggeranno il 203vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme). 204 205Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio 206di commit in un sistema di controllo di versione. Sarà seguito da: 207 208 - La patch stessa, nel formato unificato per patch ("-u"). Usare 209 l'opzione "-p" assocerà alla modifica il nome della funzione alla quale 210 si riferisce, rendendo il risultato più facile da leggere per gli altri. 211 212Dovreste evitare di includere nelle patch delle modifiche per file 213irrilevanti (quelli generati dal processo di generazione, per esempio, o i file 214di backup del vostro editor). Il file "dontdiff" nella cartella Documentation 215potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X". 216 217Le etichette sopra menzionante sono usate per descrivere come i vari 218sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte 219in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`; 220quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente 221formato: 222 223:: 224 225 tag: Full Name <email address> optional-other-stuff 226 227Le etichette in uso più comuni sono: 228 229 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto 230 di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta 231 il consenso verso il certificato d'origine degli sviluppatori, il testo 232 completo potrà essere trovato in 233 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. 234 Codice che non presenta una firma appropriata non potrà essere integrato. 235 236 - Co-developed-by: indica che la patch è stata cosviluppata da diversi 237 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello 238 associato all'etichetta From:) quando più persone lavorano ad una patch. 239 Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by: 240 del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili 241 in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. 242 243 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore 244 del codice in oggetto) all'integrazione della patch nel kernel. 245 246 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata 247 funzionante. 248 249 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per 250 maggiori dettagli leggete la dichiarazione dei revisori in 251 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` 252 253 - Reported-by: menziona l'utente che ha riportato il problema corretto da 254 questa patch; quest'etichetta viene usata per dare credito alle persone 255 che hanno verificato il codice e ci hanno fatto sapere quando le cose non 256 funzionavano correttamente. 257 258 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto 259 l'opportunità di commentarla. 260 261State attenti ad aggiungere queste etichette alla vostra patch: solo 262"Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata. 263 264Inviare la modifica 265------------------- 266 267Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui 268dovreste aver cura: 269 270 - Siete sicuri che il vostro programma di posta non corromperà le patch? 271 Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti 272 dai programmi di posta non funzioneranno per chi le riceve, e spesso 273 non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio, 274 inviate la patch a voi stessi e verificate che sia integra. 275 276 :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>` 277 contiene alcuni suggerimenti utili sulla configurazione dei programmi 278 di posta al fine di inviare patch. 279 280 - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste 281 sempre processare le patch con scripts/checkpatch.pl e correggere eventuali 282 problemi riportati. Per favore tenete ben presente che checkpatch.pl non è 283 più intelligente di voi, nonostante sia il risultato di un certa quantità di 284 ragionamenti su come debba essere una patch per il kernel. Se seguire 285 i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo. 286 287Le patch dovrebbero essere sempre inviate come testo puro. Per favore non 288inviatele come allegati; questo rende molto più difficile, per i revisori, 289citare parti della patch che si vogliono commentare. Invece, mettete la vostra 290patch direttamente nel messaggio. 291 292Quando inviate le patch, è importante inviarne una copia a tutte le persone che 293potrebbero esserne interessate. Al contrario di altri progetti, il kernel 294incoraggia le persone a peccare nell'invio di tante copie; non presumente che 295le persone interessate vedano i vostri messaggi sulla lista di discussione. 296In particolare le copie dovrebbero essere inviate a: 297 298 - I manutentori dei sottosistemi affetti della modifica. Come descritto 299 in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi 300 di queste persone. 301 302 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente 303 quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere 304 utile per vedere chi altri ha modificato i file su cui state lavorando. 305 306 - Se state rispondendo a un rapporto su un baco, o a una richiesta di 307 funzionalità, includete anche gli autori di quei rapporti/richieste. 308 309 - Inviate una copia alle liste di discussione interessate, o, se nient'altro 310 è adatto, alla lista linux-kernel 311 312 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa 313 nel prossimo rilascio stabile. Se è così, la lista di discussione 314 stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche 315 l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo 316 permetterà alla squadra *stable* di ricevere una notifica quando questa 317 correzione viene integrata nel ramo principale. 318 319Quando scegliete i destinatari della patch, è bene avere un'idea di chi 320pensiate che sia colui che, eventualmente, accetterà la vostra patch e 321la integrerà. Nonostante sia possibile inviare patch direttamente a 322Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la 323strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di 324sotto-sistema che controllano una parte specifica del kernel. Solitamente, 325vorreste che siano questi manutentori ad integrare le vostre patch. Se non 326c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton. 327 328Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto 329di una patch assomiglia a questo: 330 331:: 332 333 [PATCH nn/mm] subsys: one-line description of the patch 334 335dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch 336nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente, 337nn/mm può essere omesso per una serie composta da una singola patch. 338 339Se avete una significative serie di patch, è prassi inviare una descrizione 340introduttiva come parte zero. Tuttavia questa convenzione non è universalmente 341seguita; se la usate, ricordate che le informazioni nell'introduzione non 342faranno parte del changelog del kernel. Quindi per favore, assicuratevi che 343ogni patch abbia un changelog completo. 344 345In generale, la seconda parte e quelle successive di una patch "composta" 346dovrebbero essere inviate come risposta alla prima, cosicché vengano viste 347come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare 348gruppi di patch con la struttura appropriata. Se avete una serie lunga 349e state usando git, per favore state alla larga dall'opzione --chain-reply-to 350per evitare di creare un annidamento eccessivo.