Sviluppo/Partecipa

From The Document Foundation Wiki
Jump to: navigation, search
This page is a translated version of the page Development/GetInvolved and the translation is 90% complete.

Outdated translations are marked like this.
Other languages:
català • ‎dansk • ‎English • ‎español • ‎italiano • ‎日本語

I programmatori e gli utenti possono contribuire allo sviluppo di LibreOffice in molti modi e tutti sono benvenuti nel progetto.

Gli Utenti possono, per esempio, aiutate lo sviluppo del software provando le versioni beta del programma, segnalando e verificando i bug, scrivendo della documentazione, fornendo dei modelli, aggiornando i glossari e i dizionari, traducendo nella loro lingua, aggiungendo degli elementi grafici, facendo promozione per LibreOffice.

Questa pagina si focalizzerà sui programmatori. Tenete a mente che il progetto è aperto a programmatori di qualsiasi livello. Esiste uno "zoccolo duro" costituito da pochi programmatori (che sostanzialmente sono persone che sono attive da quando il progetto è iniziato), ma la maggior parte dei programmatori sono relativamente nuovi. LibreOffice è uno dei più grandi, longevi e conosciuti (come OpenOffice) dei pacchetti di software libero. Se siete degli studenti e state cercando un lavoro da programmatore, poter scrivere "Ho lavorato per LibreOffice" è un elemento di valore per il vostro CV.

Dopo esservi accordati, potete utilizzare i Development Mentoring Lead come vostro riferimento. I programmatori aiutano a migliorare il codice sorgente di LibreOffice. Ad una prima occhiata, l'enorme quantità di codice può intimorire, ma la documentazione sta migliorando e potrete ottenere aiuto dalla squadra formata dagli attuali programmatori. Questa pagina vi aiuterà ad inviare la vostra prima patch. Per farvi un'idea date uno sguardo alle pagine seguenti (ricordatevi che tutti gli Easy Hack contengono dei puntatori che rimandano al codice):

Guida passo a passo per i nuovi programmatori

È facile essere sopraffatti dalle dimensioni e dalla complessità di LibreOffice. Il codice è scritto in molti linguaggi e formati differenti — C, C++, Java, Bash, JavaScript, Python, Perl, SQL, Test, XML — ed è composto grossomodo da 102.000 file (escluse tutte le localizzazioni) con 36.000.000 di righe di testo (7.000.000 di righe di codice sorgente)

Nessuno è in grado di comprendere nei dettagli tutto il codice, ma ci sono molti programmatori storici, ognuno dei quali conosce fino nei particolari una determinata parte del codice. Questa guida passo a passo illustra un metodo semplice per passare da "vorrei contribuire" a far si che la vostra prima patch venga inserita nel codice del ramo master. Se avete bisogno di aiuto o di ulteriori informazioni, non esitare a contattare il servizio di Tutor per programmatori

Connettersi ai canali di comunicazione del progetto

Il canale di comunicazione principale è la mailing list libreoffice@lists.freedesktop.org; alla quale vi raccomandiamo di iscrivervi. Potete seguire la lista anche online alla pagina http://nabble.documentfoundation.org. Come usare la mailing list di sviluppo

Se avete bisogno di un risposta rapida a delle semplici domande, potete trovare molti dei programmatori sul canale IRC freenode #libreoffice-dev connect via webchat

Compilare LibreOffice

Per poter effettivamente programmare dovrete avere una copia in locale di tutto il codice sorgente, che si trova su git

Windows

Coloro che programmano in Windows devono installare Cygwin ed altri programmi di utilità. Il modo più semplice per farlo è quello di usare lode

macOS

macOS può essere configurato in diversi modi, man mano che acquisirete esperienza potreste volere delle configurazioni più complesse, ma per iniziare è consigliata la seguente Configurazione rapida

Linux

In Linux (nella maggior parte delle distribuzioni) potete effettuare le impostazioni necessarie usando il gestore dei pacchetti. Vi suggeriamo di seguire Compilare su Linux

Predisporre le patch per inviarle

Una volta che avrete compilato con successo LibreOffice, sarete pronti per inviare le vostre patch. Per tenere traccia delle patch viene usato gerrit, perciò dovrete creare un account. Seguite questa guida all'impostazione di gerrit

Sostanzialmente ci sono due modi per inviare/lavorare con le patch. Coloro che hanno dimestichezza con Git review possono usarlo, anche se è raccomandato l'uso di uno strumento più semplice: logerrit.

Prestate attenzione quanto trasmettete delle modifiche a dei sottomoduli come help (e clonate solamente help) in quanto lo script logerrit non è disponibile e potreste non aver installato il collegamento con gerrit. Per le istruzioni necessarie all'impostazione, vedete Sottomoduli.

Scegliere il primo bug da risolvere

Congratulazioni, siete arrivati al punto in cui le cose si fanno interessanti.

Risolvere il primo bug comporta imparare l'uso di nuovi strumenti e nuovi metodi, peciò sono stati individuati alcuni bug semplici chiamati Easy_Hack. Per tenere traccia dei bug segnalati viene usato bugzilla sul quale dovete creare un account.

Gli Easy hack sono dei bug reali, ai quali i programmatori più esperti, anziché risolverli, hanno aggiunto dei collegamenti al relativo codice ed in qualche caso anche degli aiuti testuali, in modo da facilitarne la risoluzione. Selezionate un bug che vi interessa, nel vostro linguaggio di programmazione preferito (vedete sopra) EasyHack per linguaggio e livello di competenza; come vedete c'è un'ampia scelta. Si raccomanda di sceglierne uno dalla categoria "Livello di competenza: principiante" in modo da potervi concentrare su tutti i: "come faccio a ....".

Una volta che avrete selezionato un bug da risolvere, non dimenticate di assegnalo a voi stessi su bugzilla, in modo che gli altri possano vedere che ci state lavorando sopra. Se volete lavorare su di un bug di carattere generale (come convertire foo in xyz), allora non assegnatevelo, in quanto più persone possono lavorare su questi bug in parallelo. Gli EasyHack vengono monitorati in modo che, se non fate dei progressi entro un certo lasso di tempo, vi venga tolta la sua assegnazione.

Naturalmente ci sono ulteriori sfide da affrontare in seguito:

Risoluzione di un bug

Alcuni suggerimenti pratici, basati sull'esperienza, che si consiglia di seguire:

  • non modificate mai la vostra copia del ramo master - create invece una branch.
  • tenete una branch separata per ciascun bug e non eliminate la branch fino a quando non avete eseguito il merge del bug-fix.
  • seguito lo Stile di programmazione (come ad esempio le convenzioni per l'assegnazione dei nomi alle variabili, ecc.).
  • se create dei nuovi file, siete pregati di usare questa Licenza nell'intestazione.
  • per il momento evitate pesanti riformattazioni del codice (fatta eccezione per i compiti elencati in seguito) - si sta valutando di adottare, nel medio-lungo termine, delle modalità automatiche/magiche per farlo.
  • aggiornate il master prima di iniziare a lavorare su di un nuovo bug (e, prima di fare qualsiasi modifica, eseguite make check per accertarvi che si compili senza problemi).
  • non inviate delle patch che dipendono l'una dall'altra, a meno che non vi sia richiesto. Farlo renderebbe impossibile il merge della patch.
  • se la patch non è pronta per il merge, assegnatele il valore -2, in questo modo i revisori sapranno che si tratta di un lavoro in corso.
  • la pazienza è importante, la revisione richiede tempo e siamo tutti volontari, perciò aspettatevi che ci voglia qualche giorno.

Flusso di lavoro consigliato

1. Aggiornare il master

Assicuratevi che il vostro master sia aggiornato e che funzioni. Se il master è troppo vecchio, rischiate di non poter poi fare il merge della vostra patch.

Come regola generale, usate i comandi sottostanti quando:

  • il vostro master è più vecchio di una settimana;
  • il vostro nuovo bug-fix dipende da un lavoro di cui è appena stato eseguito il merge.
./g pull -r
make
make check

!! la versione di make deve essere la 3.8.1 o una più recente.

Usate il parametro -r, che è molto più efficace di un semplice pull. Il master è spesso corrotto, ma di solito per brevi periodi (normalmente i contributori lo riparano in fretta dopo aver eseguito un commit sbagliato).

Quando make termina la sua esecuzione, saprete di avere un master funzionante, perciò se make si interrompe mentre sta compilando la vostra patch, è dovuto ad un problema nel vostro codice. make check esegue tutti i test necessari e vi garantisce di avere una versione funzionante di LibreOffice.

2. Lavorare in una branch

In un secondo momento potrebbe esservi richiesto di modificare la vostra patch e, se l'avete creata ed avete lavorato in una branch separata, questo risulterà molto semplice. Usate una nuova branch (dal master) per ogni bug sul quale lavorate, una volta che avrete effettuato il merge della patch potrete eliminare la branch.

git checkout -b test1

Sostituite test1 con il nome che preferite.

3. Risolvere il bug

Identificate il problema, correggete il codice, generate e provate una versione. Ricordatevi di fornire, se possibile, una funzione di test che verifichi se il problema è risolto.

Esistono diversi strumenti utili che vi possono aiutare:

Ricordatevi di eseguire regolarmente git commit -a. Nel caso doveste accorgervi di aver seguito una strada sbagliata, questo vi permetterà di abbandonare con facilità parte di quanto da voi sviluppato.

4. Inviare la patch

Si raccomanda che i messaggi di commit siano simili al seguente:

   tdf#12345 <short developer description of change, not just the bug title>
   <empty line>
   <description of what the patch does, the more words the better others understand it later>
  • se è presente una segnalazione di bug relativa al commit è obbligatorio iniziare la prima riga inserendo un riferimento al bug come tdf#12345 (maggiori dettagli in seguito)
  • usate il resto della prima riga come breve sommario delle vostre modifiche. La lunghezza massima di questa riga è di 72 caratteri.
  • usate i verbi al presente, raccontate cosa fanno le modifiche, siate concisi, evitate di sprecare spazio con "decorazioni" come trattini e parentesi.
  • se volete inserire più testo di quello che può stare sulla prima riga, è obbligatorio lasciare vuota la seconda riga
  • partendo dalla terza riga spiegate cosa fa la patch e perché lo fa e, se non risulta ovvio, anche come. Queste righe dovrebbero essere lunghe al massimo 80 caratteri; se i vostri commenti sono più lunghi, spezzateli su più righe. Qui potete descrivere anche in che modo il codice funzionava in modo errato prima delle modifiche.

Se la vostra patch corregge un bug già segnalato su Bugzilla, potete usufruire delle notifica automatica dei bug che viene attivata dai messaggi di commit: Se la prima riga di un messaggio di commit contiene un riferimento ad un bug nella forma tdf#12345, allora il commento corrispondente viene aggiunto automaticamente alla segnalazione del bug, nel momento in cui la modifica viene inviata al repository. Per maggiori dettagli consultate il thread relativo agli annunci su mail-archive.com oppure su fdo-listarchive.

Verificate che le vostra modifiche non creino malfunzionamenti nei test automatici:

make check

A questo punto potete caricare la patch su gerrit (vedete Preparare le patch per l'invio):

./logerrit submit master

Revisione delle patch

Normalmente, la vostra patch verrà revisionata entro 1 o 2 giorni. Potete seguire lo stato di avanzamento su gerrit e ricevete un'email nel caso ci siano delle modifiche. (Non preoccupatevi troppo se Jenkins riferisce che è fallita la compilazione automatica solamente della versione in Windows.)

In generale nella revisione possono succedere 3 cose:

  • il revisore ha verificato e provato la patch con successo, quindi ha effettuato il suo merge nel master (congratulazioni)
  • il revisore ha fatto dei commenti che dovete verificare
  • alle volte una patch può compromettere altre funzionalità e viene contrassegnata come “Cannot merge” (impossibile fare il merge)

Negli ultimi 2 casi dovete aggiornare la vostra patch.

Uso del Codice-Revisione e Verificato

Se osservate la vostra patch su Gerrit vedrete due codici di stato:

  • Codice-Revisione
  • Verificato

I revisori, il sistema CI (jenkins) ed eventualmente voi stessi useranno questi due campi per classificare la patch.

Codice-Revisione

gli può essere attribuito il valore -2, -1, 0, +1, +2

-2 viene usato dall'autore per segnalare il "lavoro in corso". Il -2 previene che venga eseguito il merge della patch e solamente la persona che ha impostato il -2 canpuò rimuoverlo.

Se state lavorando su di una grossa patch, è apprezzato il caricamento di una patch, contrassegnata con -2, al fine di verificare se viene compilata con successo su tutte le piattaforme

-1 viene usato dai revisori nel caso in cui ci siano delle modifiche da fare alla patch

0 viene usato per segnalare dei commenti che non hanno effetto sull'effettuazione o meno del merge della patch.

+1 viene usato dai revisori per segnalare che la patch va bene, ma che sarebbe opportuno avere anche una seconda opinione

+2 viene usato dall'autore per segnalare che non è necessaria alcuna revisione (questo può essere fatto solamente dai programmatori esperti e dovrebbe essere usato con cautela). La persona che effettuerà il merge della patch, imposterà il +2 un attimo prima del merge, in quanto questo può essere eseguito solo per gli elementi con +2. La possibilità di impostare il +2 dipende dai diritti di push di cui gode il revisore. Questi diritti vengono attribuiti individualmente.

Da notare che NON verrà effettuato il merge di una patch fino a quando ci saranno dei -1 o -2 senza risposta.

Verificato

gli può essere attribuito il valore -1, 0 o +1

-1 viene usato dal sistema di CI quando la compilazione non va a buon fine (da notare che questo non è sempre dovuto ad un problema della patch, ma può essere dovuto ad un master corrotto).

-1 viene usato dal revisore quando non riesce ad ottenere il risultato desiderato.

0 viene usato per segnalare dei commenti che non hanno effetto sull'effettuazione o meno del merge della patch.

+1 viene usato dal sistema di CI quando la compilazione avviene con successo

+1 viene usato dal revisore quando ha verificato l'ottenimento del risultato desiderato.

Da notare che NON verrà effettuato il merge di patch fino a che il sistema di CI non visualizzi una compilazione effettuata con successo.

Aggiornare una patch

Scaricate la branch,

git checkout test1

apportate le modifiche necessarie e provate il loro funzionamento. È buona norma commentare le linee di codice che non volete modificare o per le quali non siete d'accordo con chi ha effettuato il commit, questo si fa direttamente in gerrit.

Quando siete proti per effettuare il nuovo commit è importante usare il parametro --amend

git commit --amend -a

Important non usate il parametro -m in quanto questo rimuoverebbe da gerrit l'id della patch. Lasciate che git apra l'editor che vi permetterà di modificare il messaggio di commit (o lasciatelo com'è). Se lo modificate prestate attenzione a non eliminare o modificare l'ultima riga che contiene l'id della patch.

Questo vi assicurerò di aggiornare la patch, anzichè generarne una nuova (con una nuova Change-Id:).

Caricate la nuova patch su gerrit

./logerrit submit master

L'intenzione è quella di far si che il codice sorgente rimanga libero, in modo che chiunque possa utilizzarlo, perciò è importante che inviate per email (siete pregati di usare come Oggetto: <vostro nome> license statement) una dichiarazione di licenza d'uso all'indirizzo libreoffice@lists.freedesktop.org, con il seguente testo:

   All of my past & future contributions to LibreOffice may be
   licensed under the MPLv2/LGPLv3+ dual license.

Delle lievi variazioni per adattarlo al vostro gusto personale vanno bene, purché l'intento sia chiaro. In risposta riceverete un messaggio di benvenuto. Un elenco degli sviluppatori viene mantenuto sul wiki.

Siete pregati di inviare la dichiarazione contestualmente al vostro primo caricamento di codice su gerrit (e non prima) ed assicuratevi di aver ottenuto dai vostri genitori il permesso per farlo!

Congratulazioni

Avete effettuato con successo una modifica ad uno dei più popolari programmi open source del mondo.

Continuate a produrre patch e in breve potrete effettuare anche voi dei commit.

Galateo per i principianti

Gli sviluppatori esperti vi aiuteranno a trovare le soluzioni ai vostri problemi, ma ci sono delle aspettative e dei limiti. Fare da guida in remoto e risolvere i problemi comporta un carico cognitivo maggiore rispetto a quello necessario quando si è fisicamente presenti. Se dimostrate di avere una buona preparazione le persone saranno più motivate nell'aiutarvi.

Regole guida generali:

  • se usate la chat, descrivete immediatamente il vostro problema e rimanete nel canale almeno per un ora;
  • per condividere sulla chat un testo con molte linee, usate un servizio di incollaggio come quello menzionato nell'oggetto del canale;
  • se avete dei problemi di connessione in rete, la mailing list funziona meglio della chat;
  • se state lavorando su di un compito complesso che richiede più passaggi, è una buona idea quella di scrivere delle note personali. Queste potranno tornare utili quando qualcuno vi chiederà cosa avete fatto;
  • dopo aver ricevuto una risposta, date un segno di riscontro. Se scomparite senza lasciare una traccia chi vi ha aiutato potrebbe sentirsi frustrato.

Se dovesse capitarvi un problema con git, l'invio delle patch o l'impostazione dell'ambiente di sviluppo, la cosa migliore da fare è: seguire questi passaggi:

  1. provate a cercare da soli la soluzione o un how-to. Molte volte anche chi vi aiuta dovrà effettuare le stesse ricerche;
  2. se la vostra ricerca è stata fruttuosa, provate ad eseguire le istruzioni;
  3. se non avete reperito alcuna istruzione o vi siete bloccati nel porle in essere, chiedete aiuto.

In questi casi, in genere, gli altri sono felici di provare ed aiutarvi a risolvere per interno il vostro problema.

Se state risolvendo un easy hack è bene che teniate a mente questi elementi e suggerimenti:

  • non esiste un unico documento che spieghi il codice. Il materiale formativo è disperso nelle slide delle presentazioni illustrate a delle conferenze, nei post dei blog e nelle pagine del wiki;
  • la frequenza con cui vengono inseriti dei commenti nel codice è inferiore a quanto sarebbe auspicabile (in questo potete essere d'aiuto!), peciò dovete essere preparati a dover leggere direttamente il codice;
  • per trovare le definizioni delle funzioni e delle classi in cui vi imbattete, usate git grep e OpenGrok.
  • cercate argomenti simili nella cronologia dei commit, anche in altre sezioni del codice. Il comando Annotate di OpenGrok può risultare illuminante in questo tipo di indagini;
  • Eseguite un debugger mentre utilizzate LibreOffice in modo da scoprire cosa accade dietro le quinte;
  • sfogliate i file readme.

Se chiedete a qualcuno come implementare qualcosa, probabilmente vi troverete di fronte al silenzio. Si presume che gli Easy hack siano un'esperienza di formazione e coloro che fungono da mentor non vorranno rovinarvela. Se proponete un'implementazione questa sarà commentata nel sistema di revisione.