Sviluppo/Partecipa

This page is a translated version of the page Development/GetInvolved and the translation is 100% complete.

TDF LibreOffice Document Liberation Project Blog comunitari Weblate Nextcloud Redmine Ask LibreOffice Donazione

Other languages:

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. Il progetto è aperto a programmatori di qualsiasi livello. 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. 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:

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, 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.

Connettersi ai canali di comunicazione del progetto

La mailing list è libreoffice@lists.freedesktop.org; alla quale vi raccomandiamo di iscrivervi. Potete seguire la lista anche online.

Per le chat in tempo reale viene utilizzato IRC sulla rete Libera Chat #libreoffice-dev ^IRC://

Compilare LibreOffice

Per poter effettivamente programmare dovrete avere una copia in locale di tutto il codice sorgente, che si trova su git. La clonazione del codice sorgente è spiegata negli articoli contenenti le istruzioni di compilazione per ciascun sistema operativo.

Windows

Coloro che programmano in Windows devono installare Cygwin ed altri programmi di utilità. Il modo più semplice per farlo è quello di usare LibreOffice Development Environment (LODE). Sono disponibili anche delle istruzioni dettagliate per la compilazione in Windows.

macOS

Si raccomanda di seguire le istruzioni usate dal LibreOffice Development Environment (LODE). Potete trovare ulteriori informazioni e dettagli su Xcode nell'articolo Compilare LibreOffice su macOS.

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. L'esecuzione di un make completo prima di make check non comporta un aumento dei tempi di compilazione e, nel caso di errori nei test, vi garantisce di ottenere una versione che può essere eseguita.

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 (da origin/master) per ogni bug sul quale lavorate, una volta che avrete effettuato il merge della patch potrete eliminare la branch.

git checkout -b test1 origin/master

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:

OpenGrok - usatelo per fare delle ricerche e per navigare all'interno del codice
Convertitore in python delle funzioni di test scritte in java
log dei commit su cgit
panoramica di LibreOffice su gerrit

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

Nel caso degli Easy Hack, aggiungete, come revisore della vostra patch, la persona che vi ha fornito i puntatori al codice. Ricevete un'email nel caso siano apportate delle modifiche alla vostra patch.

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 dovrete verificare
alle volte una patch può compromettere altre funzionalità e viene contrassegnata come “Cannot merge” (impossibile fare il merge)

Negli ultimi due casi dovete aggiornare la vostra patch.

Per maggiori informazioni sul processo di revisione delle patch, vedete MyLanguage/Development/gerrit/PatchReview.

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

Dichiarazione di licenza d'uso

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.

È importante assicurarsi che la mail consenta di collegare la dichiarazione ai contributi, perciò inviate la dichiarazione dalla stessa email che usate per i vostri commit.

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

Siete pregati di inviare la dichiarazione contestualmente al vostro primo caricamento di codice su gerrit. Se siete minorenni chiedete ai vostri genitori, o al vostro tutore legale,di inviate l'email (questo vale per tutte le persone con un tutore legale)!

Se il vostro contributo consiste in materiale grafico che verrà incluso nel software (come, ad esempio, le icone), aggiungete questa clausola alla vostra email relativa alla dichiarazione di licenza d'uso:

   Additionally, to the extent possible under law, I waive all
   copyright and related or neighboring rights to my past & future
   Artwork and Design contributions to the LibreOffice project, and
   similarly to The Document Foundation, placing such contributions
   under CC0: https://creativecommons.org/publicdomain/zero/1.0

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.

Percorso di crescita personale

Uno sviluppatore deve avere determinate capacità/esperienze per essere in grado di lavorare sul codice di LibreOffice. Questo è il percorso suggerito a chiunque voglia essere coinvolto nello sviluppo di LibreOffice:

Comprensione a livello intermedio di C++: la maggior parte del codice di LibreOffice è in C++, perciò è necessario che siate fluenti nel comprendere il C++ al fine di essere in grado di lavorare sul codice.
Comprensione di git e gerrit: git è il programma di controllo della versione usato da LibreOffice. Dovete comprendere git e gerrit per essere in grado di contribuire
Capacità di compilare LibreOffice: per essere in grado di modificare il codice, dovete avere la capacità di compilare LibreOffice dai sorgenti.
Valutazione di almeno 10 bug: gli sviluppatori devono comprendere Bugzilla ed il flusso di lavoro legato ai bug ed alle funzionalità. Questo è essenziale al fine di poter procedere.
Portate a termine almeno 5 EasyHacks con difficoltà principiante (C++): il primo passo verso le capacità di comprendere e modificare il codice.
Portate a termine almeno 5 EasyHacks di difficoltà media (C++): dopo aver concluso alcuni compiti più semplici, è importante che siate in grado di affrontare dei lavori più seri.
Portate a termine almeno 1 EasyHacks di difficoltà interessante
Correzione di almeno 5 regressioni: le regressioni di solito sono semplici da riprodurre e potete risolverle in tempi ragionevoli, perciò sono adatte ai nuovi arrivati
Raggiungimento di un certo numero di commit (~60)
Portate a termine almeno 1 CoreHack

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:

provate a cercare da soli la soluzione o un how-to. Molte volte anche chi vi aiuta dovrà effettuare le stesse ricerche;
se la vostra ricerca è stata fruttuosa, provate ad eseguire le istruzioni;
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, un'IDE 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.