Warning

In caso di dubbi sulla correttezza del contenuto di questa traduzione, l'unico riferimento valido è la documentazione ufficiale in inglese. Per maggiori informazioni consultate le avvertenze.

Original:

Documentation/process/5.Posting.rst

Translator:

Federico Vaga <federico.vaga@vaga.pv.it>

5. Pubblicare modifiche

Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere presentato alla comunità per una revisione ed eventualmente per la sua inclusione nel ramo principale del kernel. Com'era prevedibile, la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni e di procedure per la pubblicazione delle patch; seguirle renderà la vita più facile a tutti quanti. Questo documento cercherà di coprire questi argomenti con un ragionevole livello di dettaglio; più informazioni possono essere trovare nella cartella 'Documentation', nei file translations/it_IT/process/submitting-patches.rst e translations/it_IT/process/submit-checklist.rst.

5.1. Quando pubblicarle

C'è sempre una certa resistenza nel pubblicare patch finché non sono veramente "pronte". Per semplici patch questo non è un problema. Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare dai riscontri che la comunità può darvi prima che completiate il lavoro. Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche preparare un ramo git disponibile agli sviluppatori interessati, cosicché possano stare al passo col vostro lavoro in qualunque momento.

Quando pubblicate del codice che non è considerato pronto per l'inclusione, è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete informazioni sulle cose ancora da sviluppare e sui problemi conosciuti. Poche persone guarderanno delle patch che si sa essere fatte a metà, ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro sviluppo nella giusta direzione.

5.2. Prima di creare patch

Ci sono un certo numero di cose che dovreste fare prima di considerare l'invio delle patch alla comunità di sviluppo. Queste cose includono:

  • Verificare il codice fino al massimo che vi è consentito. Usate gli strumenti di debug del kernel, assicuratevi che il kernel compili con tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori per compilare il codice per differenti architetture, eccetera.

  • Assicuratevi che il vostro codice sia conforme alla linee guida del kernel sullo stile del codice.

  • La vostra patch ha delle conseguenze in termini di prestazioni? Se è così, dovreste eseguire dei benchmark che mostrino il loro impatto (anche positivo); un riassunto dei risultati dovrebbe essere incluso nella patch.

  • Siate certi d'avere i diritti per pubblicare il codice. Se questo lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione con una licenza GPL

Come regola generale, pensarci un po' di più prima di inviare il codice ripaga quasi sempre lo sforzo.

5.3. Preparazione di una patch

La preparazione delle patch per la pubblicazione può richiedere una quantità di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo di risparmiare tempo in questa fase, anche sul breve periodo.

Le patch devono essere preparate per una specifica versione del kernel. Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo principale, cominciate da un punto di rilascio ben noto - uno stabile o un -rc - piuttosto che creare il vostro ramo da quello principale in un punto a caso.

Per facilitare una revisione e una verifica più estesa, potrebbe diventare necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere un lavoro significativo nella risoluzione dei conflitti e nella correzione dei cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse della vostra patch e da quello che succede altrove nel kernel.

Solo le modifiche più semplici dovrebbero essere preparate come una singola patch; tutto il resto dovrebbe essere preparato come una serie logica di modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori passano molto tempo nel capire come farlo in modo che piaccia alla comunità. Ci sono alcune regole spannometriche, che comunque possono aiutare considerevolmente:

  • La serie di patch che pubblicherete, quasi sicuramente, non sarà come quella che trovate nel vostro sistema di controllo di versione. Invece, le vostre modifiche dovranno essere considerate nella loro forma finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori sono interessati in modifiche che siano discrete e indipendenti, non alla strada che avete percorso per ottenerle.

  • Ogni modifica logicamente indipendente dovrebbe essere preparata come una patch separata. Queste modifiche possono essere piccole ("aggiunto un campo in questa struttura") o grandi (l'aggiunta di un driver nuovo, per esempio), ma dovrebbero essere concettualmente piccole da permettere una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche specifiche che si possano revisionare indipendentemente e di cui si possa verificare la veridicità.

  • Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di modifiche nella stessa patch. Se una modifica corregge un baco critico per la sicurezza, riorganizza alcune strutture, e riformatta il codice, ci sono buone probabilità che venga ignorata e che la correzione importante venga persa.

  • Ogni modifica dovrebbe portare ad un kernel che compila e funziona correttamente; se la vostra serie di patch si interrompe a metà il risultato dovrebbe essere comunque un kernel funzionante. L'applicazione parziale di una serie di patch è uno scenario comune nel quale il comando "git bisect" viene usato per trovare delle regressioni; se il risultato è un kernel guasto, renderete la vita degli sviluppatori più difficile così come quella di chi s'impegna nel nobile lavoro di scovare i problemi.

  • Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500 patch che modificavano un unico file - un atto che non lo rese la persona più popolare sulla lista di discussione del kernel. Una singola patch può essere ragionevolmente grande fintanto che contenga un singolo cambiamento logico.

  • Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura come una serie di patch, ma di lasciare questa infrastruttura inutilizzata finché l'ultima patch della serie non abilita tutto quanto. Quando è possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle regressioni, "bisect" indicherà quest'ultima patch come causa del problema anche se il baco si trova altrove. Possibilmente, quando una patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente.

Lavorare per creare la serie di patch perfetta potrebbe essere frustrante perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è già stato fatto. Quando ben fatto, comunque, è tempo ben speso.

5.4. Formattazione delle patch e i changelog

Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione, ma il lavoro non è davvero finito. Ogni patch deve essere preparata con un messaggio che spieghi al resto del mondo, in modo chiaro e veloce, il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi:

  • Un campo opzionale "From" col nome dell'autore della patch. Questa riga è necessaria solo se state passando la patch di qualcun altro via email, ma nel dubbio non fa di certo male aggiungerlo.

  • Una descrizione di una riga che spieghi cosa fa la patch. Questo messaggio dovrebbe essere sufficiente per far comprendere al lettore lo scopo della patch senza altre informazioni. Questo messaggio, solitamente, presenta in testa il nome del sottosistema a cui si riferisce, seguito dallo scopo della patch. Per esempio:

    gpio: fix build on CONFIG_GPIO_SYSFS=n

  • Una riga bianca seguita da una descrizione dettagliata della patch. Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare cosa fa e perché dovrebbe essere aggiunta al kernel.

  • Una o più righe etichette, con, minimo, una riga Signed-off-by: col nome dall'autore della patch. Queste etichette verranno descritte meglio più avanti.

Gli elementi qui sopra, assieme, formano il changelog di una patch. Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata; vale la pena spendere qualche parola in più al riguardo. Quando scrivete un changelog dovreste tenere ben presente che molte persone leggeranno le vostre parole. Queste includono i manutentori di un sotto-sistema, e i revisori che devono decidere se la patch debba essere inclusa o no, le distribuzioni e altri manutentori che cercano di valutare se la patch debba essere applicata su kernel più vecchi, i cacciatori di bachi che si chiederanno se la patch è la causa di un problema che stanno cercando, gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri. Un buon changelog fornisce le informazioni necessarie a tutte queste persone nel modo più diretto e conciso possibile.

A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della modifica e la motivazione della patch nel modo migliore possibile nonostante il limite di una sola riga. La descrizione dettagliata può spiegare meglio i temi e fornire maggiori informazioni. Se una patch corregge un baco, citate, se possibile, il commit che lo introdusse (e per favore, quando citate un commit aggiungete sia il suo identificativo che il titolo), Se il problema è associabile ad un file di log o all' output del compilatore, includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso problema. Se la modifica ha lo scopo di essere di supporto a sviluppi successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste modifiche e come gli altri dovrebbero agire per applicarle. In generale, più riuscirete ad entrare nei panni di tutti quelli che leggeranno il vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme).

Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio di commit in un sistema di controllo di versione. Sarà seguito da:

  • La patch stessa, nel formato unificato per patch ("-u"). Usare l'opzione "-p" assocerà alla modifica il nome della funzione alla quale si riferisce, rendendo il risultato più facile da leggere per gli altri.

Dovreste evitare di includere nelle patch delle modifiche per file irrilevanti (quelli generati dal processo di generazione, per esempio, o i file di backup del vostro editor). Il file "dontdiff" nella cartella Documentation potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".

Le etichette sopracitate danno un'idea di come una patch prende vita e sono descritte nel dettaglio nel documento Documentation/translations/it_IT/process/submitting-patches.rst. Qui di seguito un breve riassunto.

Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch:

Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")

Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti maggiori informazioni, per esempio un rapporto circa il baco risolto dalla patch, oppure un documento con le specifiche implementate dalla patch:

Link: https://example.com/somewhere.html  optional-other-stuff

Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento alla più recente discussione pubblica. A volte questo è fatto automaticamente da alcuni strumenti come b4 or un hook git come quello descritto qui 'Configurare Git'

Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo sviluppo della patch. Tutte queste etichette seguono il formato:

tag: Full Name <email address>  optional-other-stuff

Le etichette in uso più comuni sono:

  • Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta il consenso verso il certificato d'origine degli sviluppatori, il testo completo potrà essere trovato in Documentation/translations/it_IT/process/submitting-patches.rst. Codice che non presenta una firma appropriata non potrà essere integrato.

  • Co-developed-by: indica che la patch è stata cosviluppata da diversi sviluppatori; viene usato per assegnare più autori (in aggiunta a quello associato all'etichetta From:) quando più persone lavorano ad una patch. Ogni Co-developed-by: dev'essere seguito immediatamente da un Signed-off-by: del corrispondente coautore. Maggiori dettagli ed esempi sono disponibili in Documentation/translations/it_IT/process/submitting-patches.rst.

  • Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore del codice in oggetto) all'integrazione della patch nel kernel.

  • Tested-by: menziona la persona che ha verificato la patch e l'ha trovata funzionante.

  • Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per maggiori dettagli leggete la dichiarazione dei revisori in Documentation/translations/it_IT/process/submitting-patches.rst

  • Reported-by: menziona l'utente che ha riportato il problema corretto da questa patch; quest'etichetta viene usata per dare credito alle persone che hanno verificato il codice e ci hanno fatto sapere quando le cose non funzionavano correttamente. Se esiste un rapporto disponibile sul web, allora L'etichetta dovrebbe essere seguita da un collegamento al suddetto rapporto.

  • Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto l'opportunità di commentarla.

State attenti ad aggiungere queste etichette alla vostra patch: solo "Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata. Il più delle volte anche Reported-by: va bene, ma è sempre meglio chiedere specialmente se il baco è stato riportato in una comunicazione privata.

5.5. Inviare la modifica

Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui dovreste aver cura:

  • Siete sicuri che il vostro programma di posta non corromperà le patch? Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti dai programmi di posta non funzioneranno per chi le riceve, e spesso non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio, inviate la patch a voi stessi e verificate che sia integra.

    Documentation/translations/it_IT/process/email-clients.rst contiene alcuni suggerimenti utili sulla configurazione dei programmi di posta al fine di inviare patch.

  • Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste sempre processare le patch con scripts/checkpatch.pl e correggere eventuali problemi riportati. Per favore tenete ben presente che checkpatch.pl non è più intelligente di voi, nonostante sia il risultato di un certa quantità di ragionamenti su come debba essere una patch per il kernel. Se seguire i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo.

Le patch dovrebbero essere sempre inviate come testo puro. Per favore non inviatele come allegati; questo rende molto più difficile, per i revisori, citare parti della patch che si vogliono commentare. Invece, mettete la vostra patch direttamente nel messaggio.

Quando inviate le patch, è importante inviarne una copia a tutte le persone che potrebbero esserne interessate. Al contrario di altri progetti, il kernel incoraggia le persone a peccare nell'invio di tante copie; non presumente che le persone interessate vedano i vostri messaggi sulla lista di discussione. In particolare le copie dovrebbero essere inviate a:

  • I manutentori dei sottosistemi affetti della modifica. Come descritto in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi di queste persone.

  • Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere utile per vedere chi altri ha modificato i file su cui state lavorando.

  • Se state rispondendo a un rapporto su un baco, o a una richiesta di funzionalità, includete anche gli autori di quei rapporti/richieste.

  • Inviate una copia alle liste di discussione interessate, o, se nient'altro è adatto, alla lista linux-kernel

  • Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa nel prossimo rilascio stabile. Se è così, la lista di discussione stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo permetterà alla squadra stable di ricevere una notifica quando questa correzione viene integrata nel ramo principale.

Quando scegliete i destinatari della patch, è bene avere un'idea di chi pensiate che sia colui che, eventualmente, accetterà la vostra patch e la integrerà. Nonostante sia possibile inviare patch direttamente a Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di sotto-sistema che controllano una parte specifica del kernel. Solitamente, vorreste che siano questi manutentori ad integrare le vostre patch. Se non c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton.

Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto di una patch assomiglia a questo:

[PATCH nn/mm] subsys: one-line description of the patch

dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente, nn/mm può essere omesso per una serie composta da una singola patch.

Se avete una significative serie di patch, è prassi inviare una descrizione introduttiva come parte zero. Tuttavia questa convenzione non è universalmente seguita; se la usate, ricordate che le informazioni nell'introduzione non faranno parte del changelog del kernel. Quindi per favore, assicuratevi che ogni patch abbia un changelog completo.

In generale, la seconda parte e quelle successive di una patch "composta" dovrebbero essere inviate come risposta alla prima, cosicché vengano viste come un unico thread. Strumenti come git e quilt hanno comandi per inviare gruppi di patch con la struttura appropriata. Se avete una serie lunga e state usando git, per favore state alla larga dall'opzione --chain-reply-to per evitare di creare un annidamento eccessivo.