0001 .. include:: ../disclaimer-ita.rst
0002
0003 :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
0004 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
0005
0006 .. _it_development_posting:
0007
0008 Pubblicare modifiche
0009 ====================
0010
0011 Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere
0012 presentato alla comunità per una revisione ed eventualmente per la sua
0013 inclusione nel ramo principale del kernel. Com'era prevedibile,
0014 la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni
0015 e di procedure per la pubblicazione delle patch; seguirle renderà la vita
0016 più facile a tutti quanti. Questo documento cercherà di coprire questi
0017 argomenti con un ragionevole livello di dettaglio; più informazioni possono
0018 essere trovare nella cartella 'Documentation', nei file
0019 :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
0020 e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
0021
0022
0023 Quando pubblicarle
0024 ------------------
0025
0026 C'è sempre una certa resistenza nel pubblicare patch finché non sono
0027 veramente "pronte". Per semplici patch questo non è un problema.
0028 Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare
0029 dai riscontri che la comunità può darvi prima che completiate il lavoro.
0030 Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche
0031 preparare un ramo git disponibile agli sviluppatori interessati, cosicché
0032 possano stare al passo col vostro lavoro in qualunque momento.
0033
0034 Quando pubblicate del codice che non è considerato pronto per l'inclusione,
0035 è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete
0036 informazioni sulle cose ancora da sviluppare e sui problemi conosciuti.
0037 Poche persone guarderanno delle patch che si sa essere fatte a metà,
0038 ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro
0039 sviluppo nella giusta direzione.
0040
0041
0042 Prima di creare patch
0043 ---------------------
0044
0045 Ci sono un certo numero di cose che dovreste fare prima di considerare
0046 l'invio delle patch alla comunità di sviluppo. Queste cose includono:
0047
0048 - Verificare il codice fino al massimo che vi è consentito. Usate gli
0049 strumenti di debug del kernel, assicuratevi che il kernel compili con
0050 tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori
0051 per compilare il codice per differenti architetture, eccetera.
0052
0053 - Assicuratevi che il vostro codice sia conforme alla linee guida del
0054 kernel sullo stile del codice.
0055
0056 - La vostra patch ha delle conseguenze in termini di prestazioni?
0057 Se è così, dovreste eseguire dei *benchmark* che mostrino il loro
0058 impatto (anche positivo); un riassunto dei risultati dovrebbe essere
0059 incluso nella patch.
0060
0061 - Siate certi d'avere i diritti per pubblicare il codice. Se questo
0062 lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su
0063 questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione
0064 con una licenza GPL
0065
0066 Come regola generale, pensarci un po' di più prima di inviare il codice
0067 ripaga quasi sempre lo sforzo.
0068
0069
0070 Preparazione di una patch
0071 -------------------------
0072
0073 La preparazione delle patch per la pubblicazione può richiedere una quantità
0074 di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo
0075 di risparmiare tempo in questa fase, anche sul breve periodo.
0076
0077 Le patch devono essere preparate per una specifica versione del kernel.
0078 Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale
0079 così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo
0080 principale, cominciate da un punto di rilascio ben noto - uno stabile o
0081 un -rc - piuttosto che creare il vostro ramo da quello principale in un punto
0082 a caso.
0083
0084 Per facilitare una revisione e una verifica più estesa, potrebbe diventare
0085 necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un
0086 sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere
0087 un lavoro significativo nella risoluzione dei conflitti e nella correzione dei
0088 cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse
0089 della vostra patch e da quello che succede altrove nel kernel.
0090
0091 Solo le modifiche più semplici dovrebbero essere preparate come una singola
0092 patch; tutto il resto dovrebbe essere preparato come una serie logica di
0093 modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori
0094 passano molto tempo nel capire come farlo in modo che piaccia alla comunità.
0095 Ci sono alcune regole spannometriche, che comunque possono aiutare
0096 considerevolmente:
0097
0098 - La serie di patch che pubblicherete, quasi sicuramente, non sarà
0099 come quella che trovate nel vostro sistema di controllo di versione.
0100 Invece, le vostre modifiche dovranno essere considerate nella loro forma
0101 finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori
0102 sono interessati in modifiche che siano discrete e indipendenti, non
0103 alla strada che avete percorso per ottenerle.
0104
0105 - Ogni modifica logicamente indipendente dovrebbe essere preparata come una
0106 patch separata. Queste modifiche possono essere piccole ("aggiunto un
0107 campo in questa struttura") o grandi (l'aggiunta di un driver nuovo,
0108 per esempio), ma dovrebbero essere concettualmente piccole da permettere
0109 una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche
0110 specifiche che si possano revisionare indipendentemente e di cui si possa
0111 verificare la veridicità.
0112
0113 - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di
0114 modifiche nella stessa patch. Se una modifica corregge un baco critico
0115 per la sicurezza, riorganizza alcune strutture, e riformatta il codice,
0116 ci sono buone probabilità che venga ignorata e che la correzione importante
0117 venga persa.
0118
0119 - Ogni modifica dovrebbe portare ad un kernel che compila e funziona
0120 correttamente; se la vostra serie di patch si interrompe a metà il
0121 risultato dovrebbe essere comunque un kernel funzionante. L'applicazione
0122 parziale di una serie di patch è uno scenario comune nel quale il
0123 comando "git bisect" viene usato per trovare delle regressioni; se il
0124 risultato è un kernel guasto, renderete la vita degli sviluppatori più
0125 difficile così come quella di chi s'impegna nel nobile lavoro di
0126 scovare i problemi.
0127
0128 - Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500
0129 patch che modificavano un unico file - un atto che non lo rese la persona
0130 più popolare sulla lista di discussione del kernel. Una singola patch
0131 può essere ragionevolmente grande fintanto che contenga un singolo
0132 cambiamento *logico*.
0133
0134 - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura
0135 come una serie di patch, ma di lasciare questa infrastruttura inutilizzata
0136 finché l'ultima patch della serie non abilita tutto quanto. Quando è
0137 possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle
0138 regressioni, "bisect" indicherà quest'ultima patch come causa del
0139 problema anche se il baco si trova altrove. Possibilmente, quando una
0140 patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.
0141
0142 Lavorare per creare la serie di patch perfetta potrebbe essere frustrante
0143 perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è
0144 già stato fatto. Quando ben fatto, comunque, è tempo ben speso.
0145
0146
0147 Formattazione delle patch e i changelog
0148 ---------------------------------------
0149
0150 Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione,
0151 ma il lavoro non è davvero finito. Ogni patch deve essere preparata con
0152 un messaggio che spieghi al resto del mondo, in modo chiaro e veloce,
0153 il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi:
0154
0155 - Un campo opzionale "From" col nome dell'autore della patch. Questa riga
0156 è necessaria solo se state passando la patch di qualcun altro via email,
0157 ma nel dubbio non fa di certo male aggiungerlo.
0158
0159 - Una descrizione di una riga che spieghi cosa fa la patch. Questo
0160 messaggio dovrebbe essere sufficiente per far comprendere al lettore lo
0161 scopo della patch senza altre informazioni. Questo messaggio,
0162 solitamente, presenta in testa il nome del sottosistema a cui si riferisce,
0163 seguito dallo scopo della patch. Per esempio:
0164
0165 ::
0166
0167 gpio: fix build on CONFIG_GPIO_SYSFS=n
0168
0169 - Una riga bianca seguita da una descrizione dettagliata della patch.
0170 Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare
0171 cosa fa e perché dovrebbe essere aggiunta al kernel.
0172
0173 - Una o più righe etichette, con, minimo, una riga *Signed-off-by:*
0174 col nome dall'autore della patch. Queste etichette verranno descritte
0175 meglio più avanti.
0176
0177 Gli elementi qui sopra, assieme, formano il changelog di una patch.
0178 Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata;
0179 vale la pena spendere qualche parola in più al riguardo. Quando scrivete
0180 un changelog dovreste tenere ben presente che molte persone leggeranno
0181 le vostre parole. Queste includono i manutentori di un sotto-sistema, e i
0182 revisori che devono decidere se la patch debba essere inclusa o no,
0183 le distribuzioni e altri manutentori che cercano di valutare se la patch
0184 debba essere applicata su kernel più vecchi, i cacciatori di bachi che si
0185 chiederanno se la patch è la causa di un problema che stanno cercando,
0186 gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri.
0187 Un buon changelog fornisce le informazioni necessarie a tutte queste
0188 persone nel modo più diretto e conciso possibile.
0189
0190 A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della
0191 modifica e la motivazione della patch nel modo migliore possibile nonostante
0192 il limite di una sola riga. La descrizione dettagliata può spiegare meglio
0193 i temi e fornire maggiori informazioni. Se una patch corregge un baco,
0194 citate, se possibile, il commit che lo introdusse (e per favore, quando
0195 citate un commit aggiungete sia il suo identificativo che il titolo),
0196 Se il problema è associabile ad un file di log o all' output del compilatore,
0197 includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso
0198 problema. Se la modifica ha lo scopo di essere di supporto a sviluppi
0199 successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste
0200 modifiche e come gli altri dovrebbero agire per applicarle. In generale,
0201 più riuscirete ad entrare nei panni di tutti quelli che leggeranno il
0202 vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).
0203
0204 Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio
0205 di commit in un sistema di controllo di versione. Sarà seguito da:
0206
0207 - La patch stessa, nel formato unificato per patch ("-u"). Usare
0208 l'opzione "-p" assocerà alla modifica il nome della funzione alla quale
0209 si riferisce, rendendo il risultato più facile da leggere per gli altri.
0210
0211 Dovreste evitare di includere nelle patch delle modifiche per file
0212 irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
0213 di backup del vostro editor). Il file "dontdiff" nella cartella Documentation
0214 potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
0215
0216 Le etichette sopracitate danno un'idea di come una patch prende vita e sono
0217 descritte nel dettaglio nel documento
0218 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
0219 Qui di seguito un breve riassunto.
0220
0221 Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::
0222
0223 Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
0224
0225 Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
0226 maggiori informazioni, per esempio un rapporto circa il baco risolto dalla
0227 patch, oppure un documento con le specifiche implementate dalla patch::
0228
0229 Link: https://example.com/somewhere.html optional-other-stuff
0230
0231 Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
0232 alla più recente discussione pubblica. A volte questo è fatto automaticamente da
0233 alcuni strumenti come b4 or un *hook* git come quello descritto qui
0234 'Documentation/translations/it_IT/maintainer/configure-git.rst'
0235
0236 Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo
0237 sviluppo della patch. Tutte queste etichette seguono il formato::
0238
0239 tag: Full Name <email address> optional-other-stuff
0240
0241 Le etichette in uso più comuni sono:
0242
0243 - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto
0244 di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta
0245 il consenso verso il certificato d'origine degli sviluppatori, il testo
0246 completo potrà essere trovato in
0247 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
0248 Codice che non presenta una firma appropriata non potrà essere integrato.
0249
0250 - Co-developed-by: indica che la patch è stata cosviluppata da diversi
0251 sviluppatori; viene usato per assegnare più autori (in aggiunta a quello
0252 associato all'etichetta From:) quando più persone lavorano ad una patch.
0253 Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by:
0254 del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili
0255 in :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
0256
0257 - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore
0258 del codice in oggetto) all'integrazione della patch nel kernel.
0259
0260 - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata
0261 funzionante.
0262
0263 - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per
0264 maggiori dettagli leggete la dichiarazione dei revisori in
0265 :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
0266
0267 - Reported-by: menziona l'utente che ha riportato il problema corretto da
0268 questa patch; quest'etichetta viene usata per dare credito alle persone
0269 che hanno verificato il codice e ci hanno fatto sapere quando le cose non
0270 funzionavano correttamente.
0271
0272 - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto
0273 l'opportunità di commentarla.
0274
0275 State attenti ad aggiungere queste etichette alla vostra patch: solo
0276 "Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata.
0277
0278 Inviare la modifica
0279 -------------------
0280
0281 Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui
0282 dovreste aver cura:
0283
0284 - Siete sicuri che il vostro programma di posta non corromperà le patch?
0285 Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti
0286 dai programmi di posta non funzioneranno per chi le riceve, e spesso
0287 non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio,
0288 inviate la patch a voi stessi e verificate che sia integra.
0289
0290 :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>`
0291 contiene alcuni suggerimenti utili sulla configurazione dei programmi
0292 di posta al fine di inviare patch.
0293
0294 - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste
0295 sempre processare le patch con scripts/checkpatch.pl e correggere eventuali
0296 problemi riportati. Per favore tenete ben presente che checkpatch.pl non è
0297 più intelligente di voi, nonostante sia il risultato di un certa quantità di
0298 ragionamenti su come debba essere una patch per il kernel. Se seguire
0299 i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.
0300
0301 Le patch dovrebbero essere sempre inviate come testo puro. Per favore non
0302 inviatele come allegati; questo rende molto più difficile, per i revisori,
0303 citare parti della patch che si vogliono commentare. Invece, mettete la vostra
0304 patch direttamente nel messaggio.
0305
0306 Quando inviate le patch, è importante inviarne una copia a tutte le persone che
0307 potrebbero esserne interessate. Al contrario di altri progetti, il kernel
0308 incoraggia le persone a peccare nell'invio di tante copie; non presumente che
0309 le persone interessate vedano i vostri messaggi sulla lista di discussione.
0310 In particolare le copie dovrebbero essere inviate a:
0311
0312 - I manutentori dei sottosistemi affetti della modifica. Come descritto
0313 in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi
0314 di queste persone.
0315
0316 - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente
0317 quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere
0318 utile per vedere chi altri ha modificato i file su cui state lavorando.
0319
0320 - Se state rispondendo a un rapporto su un baco, o a una richiesta di
0321 funzionalità, includete anche gli autori di quei rapporti/richieste.
0322
0323 - Inviate una copia alle liste di discussione interessate, o, se nient'altro
0324 è adatto, alla lista linux-kernel
0325
0326 - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa
0327 nel prossimo rilascio stabile. Se è così, la lista di discussione
0328 stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche
0329 l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo
0330 permetterà alla squadra *stable* di ricevere una notifica quando questa
0331 correzione viene integrata nel ramo principale.
0332
0333 Quando scegliete i destinatari della patch, è bene avere un'idea di chi
0334 pensiate che sia colui che, eventualmente, accetterà la vostra patch e
0335 la integrerà. Nonostante sia possibile inviare patch direttamente a
0336 Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la
0337 strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di
0338 sotto-sistema che controllano una parte specifica del kernel. Solitamente,
0339 vorreste che siano questi manutentori ad integrare le vostre patch. Se non
0340 c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.
0341
0342 Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto
0343 di una patch assomiglia a questo:
0344
0345 ::
0346
0347 [PATCH nn/mm] subsys: one-line description of the patch
0348
0349 dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch
0350 nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente,
0351 nn/mm può essere omesso per una serie composta da una singola patch.
0352
0353 Se avete una significative serie di patch, è prassi inviare una descrizione
0354 introduttiva come parte zero. Tuttavia questa convenzione non è universalmente
0355 seguita; se la usate, ricordate che le informazioni nell'introduzione non
0356 faranno parte del changelog del kernel. Quindi per favore, assicuratevi che
0357 ogni patch abbia un changelog completo.
0358
0359 In generale, la seconda parte e quelle successive di una patch "composta"
0360 dovrebbero essere inviate come risposta alla prima, cosicché vengano viste
0361 come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare
0362 gruppi di patch con la struttura appropriata. Se avete una serie lunga
0363 e state usando git, per favore state alla larga dall'opzione --chain-reply-to
0364 per evitare di creare un annidamento eccessivo.
