387 lines · plain
1.. include:: ../disclaimer-ita.rst2 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 modifiche9====================10 11Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere12presentato alla comunità per una revisione ed eventualmente per la sua13inclusione nel ramo principale del kernel. Com'era prevedibile,14la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni15e di procedure per la pubblicazione delle patch; seguirle renderà la vita16più facile a tutti quanti. Questo documento cercherà di coprire questi17argomenti con un ragionevole livello di dettaglio; più informazioni possono18essere trovare nella cartella 'Documentation', nei file19:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`20e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.21 22 23Quando pubblicarle24------------------25 26C'è sempre una certa resistenza nel pubblicare patch finché non sono27veramente "pronte". Per semplici patch questo non è un problema.28Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare29dai riscontri che la comunità può darvi prima che completiate il lavoro.30Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche31preparare un ramo git disponibile agli sviluppatori interessati, cosicché32possano stare al passo col vostro lavoro in qualunque momento.33 34Quando pubblicate del codice che non è considerato pronto per l'inclusione,35è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete36informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.37Poche persone guarderanno delle patch che si sa essere fatte a metà,38ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro39sviluppo nella giusta direzione.40 41 42Prima di creare patch43---------------------44 45Ci sono un certo numero di cose che dovreste fare prima di considerare46l'invio delle patch alla comunità di sviluppo. Queste cose includono:47 48 - Verificare il codice fino al massimo che vi è consentito. Usate gli49 strumenti di debug del kernel, assicuratevi che il kernel compili con50 tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori51 per compilare il codice per differenti architetture, eccetera.52 53 - Assicuratevi che il vostro codice sia conforme alla linee guida del54 kernel sullo stile del codice.55 56 - La vostra patch ha delle conseguenze in termini di prestazioni?57 Se è così, dovreste eseguire dei *benchmark* che mostrino il loro58 impatto (anche positivo); un riassunto dei risultati dovrebbe essere59 incluso nella patch.60 61 - Siate certi d'avere i diritti per pubblicare il codice. Se questo62 lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su63 questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione64 con una licenza GPL65 66Come regola generale, pensarci un po' di più prima di inviare il codice67ripaga quasi sempre lo sforzo.68 69 70Preparazione di una patch71-------------------------72 73La preparazione delle patch per la pubblicazione può richiedere una quantità74di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo75di risparmiare tempo in questa fase, anche sul breve periodo.76 77Le patch devono essere preparate per una specifica versione del kernel.78Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale79così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo80principale, cominciate da un punto di rilascio ben noto - uno stabile o81un -rc - piuttosto che creare il vostro ramo da quello principale in un punto82a caso.83 84Per facilitare una revisione e una verifica più estesa, potrebbe diventare85necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un86sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere87un lavoro significativo nella risoluzione dei conflitti e nella correzione dei88cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse89della vostra patch e da quello che succede altrove nel kernel.90 91Solo le modifiche più semplici dovrebbero essere preparate come una singola92patch; tutto il resto dovrebbe essere preparato come una serie logica di93modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori94passano molto tempo nel capire come farlo in modo che piaccia alla comunità.95Ci sono alcune regole spannometriche, che comunque possono aiutare96considerevolmente:97 98 - La serie di patch che pubblicherete, quasi sicuramente, non sarà99 come quella che trovate nel vostro sistema di controllo di versione.100 Invece, le vostre modifiche dovranno essere considerate nella loro forma101 finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori102 sono interessati in modifiche che siano discrete e indipendenti, non103 alla strada che avete percorso per ottenerle.104 105 - Ogni modifica logicamente indipendente dovrebbe essere preparata come una106 patch separata. Queste modifiche possono essere piccole ("aggiunto un107 campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,108 per esempio), ma dovrebbero essere concettualmente piccole da permettere109 una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche110 specifiche che si possano revisionare indipendentemente e di cui si possa111 verificare la veridicità.112 113 - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di114 modifiche nella stessa patch. Se una modifica corregge un baco critico115 per la sicurezza, riorganizza alcune strutture, e riformatta il codice,116 ci sono buone probabilità che venga ignorata e che la correzione importante117 venga persa.118 119 - Ogni modifica dovrebbe portare ad un kernel che compila e funziona120 correttamente; se la vostra serie di patch si interrompe a metà il121 risultato dovrebbe essere comunque un kernel funzionante. L'applicazione122 parziale di una serie di patch è uno scenario comune nel quale il123 comando "git bisect" viene usato per trovare delle regressioni; se il124 risultato è un kernel guasto, renderete la vita degli sviluppatori più125 difficile così come quella di chi s'impegna nel nobile lavoro di126 scovare i problemi.127 128 - Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500129 patch che modificavano un unico file - un atto che non lo rese la persona130 più popolare sulla lista di discussione del kernel. Una singola patch131 può essere ragionevolmente grande fintanto che contenga un singolo132 cambiamento *logico*.133 134 - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura135 come una serie di patch, ma di lasciare questa infrastruttura inutilizzata136 finché l'ultima patch della serie non abilita tutto quanto. Quando è137 possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle138 regressioni, "bisect" indicherà quest'ultima patch come causa del139 problema anche se il baco si trova altrove. Possibilmente, quando una140 patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.141 142Lavorare per creare la serie di patch perfetta potrebbe essere frustrante143perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è144già stato fatto. Quando ben fatto, comunque, è tempo ben speso.145 146 147Formattazione delle patch e i changelog148---------------------------------------149 150Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,151ma il lavoro non è davvero finito. Ogni patch deve essere preparata con152un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,153il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi:154 155 - Un campo opzionale "From" col nome dell'autore della patch. Questa riga156 è necessaria solo se state passando la patch di qualcun altro via email,157 ma nel dubbio non fa di certo male aggiungerlo.158 159 - Una descrizione di una riga che spieghi cosa fa la patch. Questo160 messaggio dovrebbe essere sufficiente per far comprendere al lettore lo161 scopo della patch senza altre informazioni. Questo messaggio,162 solitamente, presenta in testa il nome del sottosistema a cui si riferisce,163 seguito dallo scopo della patch. Per esempio:164 165 ::166 167 gpio: fix build on CONFIG_GPIO_SYSFS=n168 169 - Una riga bianca seguita da una descrizione dettagliata della patch.170 Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare171 cosa fa e perché dovrebbe essere aggiunta al kernel.172 173 - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*174 col nome dall'autore della patch. Queste etichette verranno descritte175 meglio più avanti.176 177Gli elementi qui sopra, assieme, formano il changelog di una patch.178Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;179vale la pena spendere qualche parola in più al riguardo. Quando scrivete180un changelog dovreste tenere ben presente che molte persone leggeranno181le vostre parole. Queste includono i manutentori di un sotto-sistema, e i182revisori che devono decidere se la patch debba essere inclusa o no,183le distribuzioni e altri manutentori che cercano di valutare se la patch184debba essere applicata su kernel più vecchi, i cacciatori di bachi che si185chiederanno se la patch è la causa di un problema che stanno cercando,186gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.187Un buon changelog fornisce le informazioni necessarie a tutte queste188persone nel modo più diretto e conciso possibile.189 190A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della191modifica e la motivazione della patch nel modo migliore possibile nonostante192il limite di una sola riga. La descrizione dettagliata può spiegare meglio193i temi e fornire maggiori informazioni. Se una patch corregge un baco,194citate, se possibile, il commit che lo introdusse (e per favore, quando195citate un commit aggiungete sia il suo identificativo che il titolo),196Se il problema è associabile ad un file di log o all' output del compilatore,197includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso198problema. Se la modifica ha lo scopo di essere di supporto a sviluppi199successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste200modifiche e come gli altri dovrebbero agire per applicarle. In generale,201più riuscirete ad entrare nei panni di tutti quelli che leggeranno il202vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).203 204Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio205di commit in un sistema di controllo di versione. Sarà seguito da:206 207 - La patch stessa, nel formato unificato per patch ("-u"). Usare208 l'opzione "-p" assocerà alla modifica il nome della funzione alla quale209 si riferisce, rendendo il risultato più facile da leggere per gli altri.210 211Dovreste evitare di includere nelle patch delle modifiche per file212irrilevanti (quelli generati dal processo di generazione, per esempio, o i file213di backup del vostro editor). Il file "dontdiff" nella cartella Documentation214potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".215 216Le etichette sopracitate danno un'idea di come una patch prende vita e sono217descritte nel dettaglio nel documento218:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.219Qui di seguito un breve riassunto.220 221Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::222 223 Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")224 225Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti226maggiori informazioni, per esempio una discussione avvenuta precedentemente227circa il baco risolto dalla patch, oppure un documento con le specifiche228implementate dalla patch::229 230 Link: https://example.com/somewhere.html optional-other-stuff231 232Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento233alla più recente discussione pubblica. A volte questo è fatto automaticamente da234alcuni strumenti come b4 or un *hook* git come quello descritto qui235'Documentation/translations/it_IT/maintainer/configure-git.rst'236 237 238Se il collegamento indirizza verso un rapporto su un baco risolto dalla patch,239allora usate l'etichetta "Closes:"::240 241 Closes: https://example.com/issues/1234 optional-other-stuff242 243Alcune piattaforme di tracciamento di bachi hanno la capacità di chiudere244automaticamente il problema se l'etichetta è presente nel messaggio. Alcuni245automatismi che monitorano la liste di discussione possono anche tracciare246queste etichette e intraprendere azioni. Piattaforme private e URL invalidi sono247proibiti.248 249Un altro tipo di etichetta viene usato per indicare chi ha contribuito allo250sviluppo della patch. Tutte queste etichette seguono il formato::251 252 tag: Full Name <email address> optional-other-stuff253 254Le etichette in uso più comuni sono:255 256 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto257 di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta258 il consenso verso il certificato d'origine degli sviluppatori, il testo259 completo potrà essere trovato in260 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.261 Codice che non presenta una firma appropriata non potrà essere integrato.262 263 - Co-developed-by: indica che la patch è stata cosviluppata da diversi264 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello265 associato all'etichetta From:) quando più persone lavorano ad una patch.266 Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:267 del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili268 in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.269 270 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore271 del codice in oggetto) all'integrazione della patch nel kernel.272 273 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata274 funzionante.275 276 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per277 maggiori dettagli leggete la dichiarazione dei revisori in278 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`279 280 - Reported-by: menziona l'utente che ha riportato il problema corretto da281 questa patch; quest'etichetta viene usata per dare credito alle persone che282 hanno verificato il codice e ci hanno fatto sapere quando le cose non283 funzionavano correttamente. Questa etichetta dovrebbe essere seguita da284 quella Closes: con un indirizzo al rapporto, a meno che questo non sia285 disponibile sul web. L'etichetta Link: può essere usata in alternativa a286 Closes: se la patch corregge solo in parte il problema riportato nel287 rapporto.288 289 Se esiste un rapporto disponibile sul web, allora290 L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.291 292 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto293 l'opportunità di commentarla.294 295State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può296essere aggiunta senza il permesso esplicito della persona menzionata. Il più297delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente298se il baco è stato riportato in una comunicazione privata.299 300Inviare la modifica301-------------------302 303Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui304dovreste aver cura:305 306 - Siete sicuri che il vostro programma di posta non corromperà le patch?307 Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti308 dai programmi di posta non funzioneranno per chi le riceve, e spesso309 non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio,310 inviate la patch a voi stessi e verificate che sia integra.311 312 :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`313 contiene alcuni suggerimenti utili sulla configurazione dei programmi314 di posta al fine di inviare patch.315 316 - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste317 sempre processare le patch con scripts/checkpatch.pl e correggere eventuali318 problemi riportati. Per favore tenete ben presente che checkpatch.pl non è319 più intelligente di voi, nonostante sia il risultato di un certa quantità di320 ragionamenti su come debba essere una patch per il kernel. Se seguire321 i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.322 323Le patch dovrebbero essere sempre inviate come testo puro. Per favore non324inviatele come allegati; questo rende molto più difficile, per i revisori,325citare parti della patch che si vogliono commentare. Invece, mettete la vostra326patch direttamente nel messaggio.327 328Quando inviate le patch, è importante inviarne una copia a tutte le persone che329potrebbero esserne interessate. Al contrario di altri progetti, il kernel330incoraggia le persone a peccare nell'invio di tante copie; non presumente che331le persone interessate vedano i vostri messaggi sulla lista di discussione.332In particolare le copie dovrebbero essere inviate a:333 334 - I manutentori dei sottosistemi affetti della modifica. Come descritto335 in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi336 di queste persone.337 338 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente339 quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere340 utile per vedere chi altri ha modificato i file su cui state lavorando.341 342 - Se state rispondendo a un rapporto su un baco, o a una richiesta di343 funzionalità, includete anche gli autori di quei rapporti/richieste.344 345 - Inviate una copia alle liste di discussione interessate, o, se nient'altro346 è adatto, alla lista linux-kernel347 348 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa349 nel prossimo rilascio stabile. Se è così, la lista di discussione350 stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche351 l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo352 permetterà alla squadra *stable* di ricevere una notifica quando questa353 correzione viene integrata nel ramo principale.354 355Quando scegliete i destinatari della patch, è bene avere un'idea di chi356pensiate che sia colui che, eventualmente, accetterà la vostra patch e357la integrerà. Nonostante sia possibile inviare patch direttamente a358Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la359strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di360sotto-sistema che controllano una parte specifica del kernel. Solitamente,361vorreste che siano questi manutentori ad integrare le vostre patch. Se non362c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.363 364Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto365di una patch assomiglia a questo:366 367::368 369 [PATCH nn/mm] subsys: one-line description of the patch370 371dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch372nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente,373nn/mm può essere omesso per una serie composta da una singola patch.374 375Se avete una significative serie di patch, è prassi inviare una descrizione376introduttiva come parte zero. Tuttavia questa convenzione non è universalmente377seguita; se la usate, ricordate che le informazioni nell'introduzione non378faranno parte del changelog del kernel. Quindi per favore, assicuratevi che379ogni patch abbia un changelog completo.380 381In generale, la seconda parte e quelle successive di una patch "composta"382dovrebbero essere inviate come risposta alla prima, cosicché vengano viste383come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare384gruppi di patch con la struttura appropriata. Se avete una serie lunga385e state usando git, per favore state alla larga dall'opzione --chain-reply-to386per evitare di creare un annidamento eccessivo.387