JOOMLA & SUBVERSION. Marzo Autori. Giampaolo Losito. Antonio Di Girolamo. Joomla & Subversion by isapp.it 1

Transcript

1 JOOMLA & SUBVERSION by Marzo 2013 Autori Giampaolo Losito Antonio Di Girolamo 1

2 SOMMARIO Prefazione... 3 Requisiti... 3 Un Repository SVN dove appoggiare i vostri lavori... 3 Un client SVN... 3 Le principali funzioni di utilizzo di un client SVN... 4 Glossario dei termini... 4 Step by Spet... 4 Creazione della struttura (rami) sul Repository... 4 Strutturazione dei sorgenti Joomla!... 7 Strutturazione di un progetto già esistente... 7 Strutturazione di un nuovo progetto... 8 Import, passaggio dei sorgenti su SVN... 9 Check-out, ritira il progetto da SVN Aggiungere i sorgenti di Joomla! Installare e configurare Joomla! Joomla! Joomla! Check-in, gestire le modifiche al codice sorgente Esportare il progetto per la creazione del Package di installazione Perché creare Branch e Tag I Tags I Branches Riferimenti On-line

3 PREFAZIONE Joomla! è in continua evoluzione e presenta ad oggi più di una versione, ognuna con una propria logica di sviluppo. L utilizzo di un sistema di controllo delle versioni può risolve una buona parte dei problemi di sviluppo. Nell arco del tempo ci siamo imbattuti nella gestione delle nostre componenti ossia, aggiornamenti, modifiche o migrazioni sulle nuove versioni di Joomla! e l utilizzo di un sistema di controllo ci ha aiutato tantissimo in questo. Questa mini guida, cerca di descrivere come utilizzare un "sistema di controllo delle versioni", per la gestione del proprio codice, in particolare per Componenti, Plugin, Moduli e tutto quello che gira sul CMS Joomla! Il sistema di controllo delle versioni che prenderemo in considerazione è SubVersion, conosciuto anche come SVN (nome che utilizzeremo per brevità nel proseguo della guida) in funzione del nome del suo Client a riga di comando. La guida non spiega l installazione e l uso di SVN. Sulla rete trovate centinaia di siti che possono aiutarvi in questo (vedi Rifireimenti on-line), ma presenta un processo testato e funzionante, per poter continuare a sviluppare una vostra componente Joomla! in massima sicurezza e collaborazione tra team di sviluppo, con il supporto di un sistema SVN. REQUISITI Per la lettura di questa guida, pertanto, sono necessari alcuni requisiti. UN REPOSITORY SVN DOVE APPOGGIARE I VOSTRI LAVORI Potete utilizzare un vostro Server SVN o appoggiarvi su uno dei tanti portali dedicati alla gestione del codice ed agli sviluppatori (ad esempio joomlacode.org, sourceforge.net) che utilizzano SVN come sistema di controllo della versione o ad un servizio SVN esterno disponibili sulla rete. Attenzione però a scegliere il vostro provider esterno, tenete sempre presente che state mettendo del vostro codice in mano ad altri. UN CLIENT SVN Per questa guida è stato utilizzato " TortoiseSVN " per Windows, un client visuale per SVN potente e completamente gratuito. Questo può essere scaricato dal sito ufficiale: 3

4 LE PRINCIPALI FUNZIONI DI UTILIZZO DI UN CLIENT SVN Cosa è un Trunk come effettuare un CheckOut e piccole altre cose, ma per questo, come già detto prima, potete trovare nella rete tantissimo materiale. Questo breve glossario descrive minimamente il significato di alcuni termini utilizzati all interno della guida GLOSSARIO DEI TERMINI Trunk: Ramo principale. Questo ramo del SVN contiene i sorgenti dell ultima versione funzionante. Branch: Ramo secondario. Questo ramo viene utilizzato per eventuali correzioni (Bugs) del codice rilasciato o per lo sviluppo di rami di progetto che producono evoluzioni alla versione presente nel Trunk. Tag: Ramo secondario: Questo ramo serve a conservare le versioni finite di un progetto. Merge: Utilizzato per unire il codice da un ramo secondario (branch) ad un ramo principale (trunk) o viceversa gestendone i conflitti. CheckIn: Rilascia (commit) i sorgenti sul repository. CheckOut: Ritira (update) i sorgenti dal repository. Import: importa (passa) i sorgenti locali sul reposito STEP BY SPET Da questo momento in poi, descriveremo in modo semplice tutti i passi necessari per poter gestire i vostri progetti per il CMS Joomla! mediante un sistema SVN. Creazione della struttura (rami) sul Repository Strutturazione dei sorgenti Joomla! Import, passaggio dei sorgenti su SVN Check-out, ritira il progetto dal sistema SVN Aggiungere i sorgenti di Joomla! Installare e configurare Joomla! Check-in, gestire le modifiche al codice sorgente Esportare il progetto per la creazione del Package di installazione CREAZIONE DELLA STRUTTURA (RAMI) SUL REPOSITORY Trovare una struttura delle cartelle e dei file pratica e funzionale che ci permettesse di catalogare i nostri sorgenti all interno di un sistema SVN, e 4

5 senza dover ogni volta cambiare tutto, è stato il primo problema da risolvere. Dopo innumerevoli tentativi (e fallimenti), siamo arrivati ad una soluzione che oggi applichiamo, con ottimi risultati, in tutti i nostri progetti. In pratica: Dopo aver installato TotoiseSVN, cliccando sul tasto destro del mouse all interno del desktop o in una cartella del filesystem, nel menù contestuale, apparirà l icona di TortoiseSVN. Selezionare: TortoiseSVN => Repo Browser Nella successiva schermata va inserito l URL del Repository SVN Quando il Repo Browser è aperto, 5

6 create una cartella (tasto destro nella schermata del repo-browser) con il nome del vostro progetto Esempio: MioNuovoProgetto TortoiseSVN richiederà l inserimento di un commento (ogni azione effettuata su SVN chiederà l inserimento di un commento). E buona pratica inserirne sempre uno. Se non si dispone di utenze separate per l account SVN (ovvero si dispone di un unico account per tutto il gruppo di sviluppo) si può inserire il proprio nome all inizio del commento, separato da due punti e poi la descrizione dell azione, questo permetterà in caso di verifiche su versioni precedenti di capire chi ha effettuato la modifica all interno del gruppo di lavoro. 6

7 Potrebbe essere anche utile descrivere il tipo di modifica che si è apportata al sorgente con alcune semplici notazioni (basta anche solo il simbolo) descritte di seguito: * (Fix di sicurezza) # (Bug Fix) $ (Fix o cambiamenti sui file di lingua) + (Aggiunta di una feature) ^ (Modifica) - (Cancellazione)! (Note) Ora dobbiamo creare delle cartelle che identificano le versioni di Joomla!. Questo vi permetterà di tenere il codice separato per singola versione di Joomla!, per permettervi in modo pratico e veloce, la gestire e mantenere del codice. Nella nuova cartella creata sul SVN MioNuovoProgetto, create delle cartelle riferite alle versioni di Joomla!, per le quali avete realizzato la vostra componente (Es. Joomla!15, Joomla!16-17, Joomla!25, Joomla!30, è possibile anche pensare in caso si abbiano progetti che lavorano su una sotto versione, ad esempio la , creare delle sotto cartelle alla versione Joomla!15) e per ognuna di queste vanno create le tre cartelle principali (rami) alla base della logica di processo della gestione delle versioni tramite SVN: branches, tags e trunk. STRUTTURAZIONE DEI SORGENTI JOOMLA! Anche in questa fase si è dovuti lavorare molto per definire la giusta struttura dei sorgenti. In pratica: STRUTTURAZIONE DI UN PROGETTO GIÀ ESISTENTE 7

8 Se si sta già lavorando su un progetto Joomla! (componente, plugin, modulo etc.) e si dispone dei sorgenti, va creata una nuova cartella sulla propria macchina (in una qualsiasi parte del file system), con i sorgenti del progetto così strutturati: i file e le cartelle non devono essere strutturati come i pacchetti di installazione, ma come sono presenti su Joomla! dopo la loro installazione. tutti i file e le cartelle devono essere solo della vostra componente, compresi quelli delle lingue associati al progetto. non vanno inseriti i file del core di Joomla! a meno che questi non debbano essere integrati nel rilascio del pacchetto del nostro progetto. STRUTTURAZIONE DI UN NUOVO PROGETTO Se si sta partendo con un progetto nuovo, si possono creare le cartelle vuote necessarie al nuovo progetto. Esempio di struttura delle cartelle: /MioNuovoProgetto /administrator /components /com_mionuovoprogetto. /components /com_mionuovoprogetto /languages /it-it Di seguito un esempio di struttura, preso dal progetto JiFile. Ricordiamo nuovamente che tutti i file del vostro progetto (componente, plugin, modulo od altro) si devono trovare nelle rispettive cartelle così come sono presenti dopo la loro installazione in Joomla! 8

9 IMPORT, PASSAGGIO DEI SORGENTI SU SVN In questa fase vi spieghiamo come passare la struttura dei sorgenti, precedentemente creata sulla vostra macchina, sul Trunk (ramo principale), anche questo precedentemente creato sul SVN. In pratica: Selezioniamo la nuova cartella che contiene i file, e con il tasto destro del mouse scegliamo la funzione "Import" (Importa) di TortoiseSVN: Selezionare: TortoiseSVN => Importa 9

10 Scriviamo il percorso nel Trunk su cui vogliamo migrare i sorgenti, o più semplicemente selezioniamo il percorso del Trunk appena creato per il nuovo progetto mediante il pulsante (pulsante alla destra della casella di testo URL del repository ). 10

11 Inseriamo un commento e premiamo il tasto OK. Attendiamo che il processo di import sia terminato. Se non si sono ricevuti messaggi di errore, verrà presentata nella console il numero di versionamento del vostro progetto. La prima parte del nostro lavoro è terminata, siamo riusciti a passare, i sorgenti del progetto, sul Repository SVN. Da questo momento abbiamo il nostro sorgente versionato. CHECK-OUT, RITIRA IL PROGETTO DA SVN Ora sarà necessario effettuare il Check-Out (recupero) del progetto, versionato, in locale per poter cominciare a lavorare. In pratica: Ipotizzando di sviluppare in locale con un web server Apache, va create una cartella vuota sulla propria macchina nella webroot del vostro web server: Esempio: htdocs -> Joomla25-MioNuovoprogetto Cliccate son il tasto destro sulla nuova cartella ed effettuare il "Check-out" (Ritira) 11

12 Inseriamo il percorso del Trunk dove abbiamo appena passato i nostri sorgenti e lascaimo selezionata la Revisione di testa. Ora premiamo il tasto OK. Dopo il Check-out il contenuto della cartella creata si dovrebbe presentare in questo modo: 12

13 Si dovrebbe avere la stessa struttura e gli stessi file così come erano stati creati e passati sul repository negli step precedenti. Con l aggiunta di una cartella nascosta.svn (che non dovrete mai toccare) che serve al sistema SVN per la gestione del processo di versionamento. AGGIUNGERE I SORGENTI DI JOOMLA! Ora sarà necessario aggiungere ai vostri sorgenti, scaricati dal sistema SVN, i sorgenti di Joomla! 1. Scaricare la versione di Joomla! per cui si è creata la componente dal sito ufficiale, joomla.org 2. Scompattare il pacchetto di Joomla! in una cartella qualsiasi 3. Copiare tutti i file e incollarli nella nuova cartella creata nella webroot (nel nostro caso: Joomla25-MioNuovoprogetto) a) se si sta utilizzando una installazione completamente nuova di Joomla! e se la componente da voi creata è una componente che non appartiene o modifica file del Core Joomla! e quindi non cambia o modifica nessun file del Core, n caso di Windows, quando il sistema vi avvisa che ci sono già delle cartelle con lo stesso nome, cliccare su "Si tutte". 13

14 b) in caso la vostra componente vada a modificare alcuni file del Core Joomla! allora dovrete procedere diversamente. - Cancellate dalla versione scaricata e unzippata di joomla i sorgenti che avete modificato e utilizzate del Core Joomla! - Ora potete procede come il punto a). Al termine della copia dei file la vostra cartella si presenterà così: Come si nota dall immagine, i file/cartelle presenti sul vostro Repository SVN sono contrassegnati con una icona verde con il segno di spunta. Tutti gli altri file (quelli di Joomla!) sono contrassegnati da un punto interrogativo. 14

15 INSTALLARE E CONFIGURARE JOOMLA! Ora è necessario installare e configurare correttamente Joomla! per poter cominciare a lavorare con il vostro progetto. In pratica: 1. Andare sul browser, digitare l'url alla nuova directory e procedere all'installazione di Joomla! (Es Configurate a mano le varie parti mancanti, che non fanno parte del codice, come ad esempio la parte del DataBase per fare funzionare la vostra Componente. Di seguito sono riportati alcuni esempi presi da JiFile, ma è importante ricordare che ogni componente, plugin o modulo potrebbe richiedere maggiori informazioni da inserire, ad esempio tabelle personalizzate od altro. Per comodità converrebbe creare un vostro file.sql contenente tutte le informazioni per eventuali creazioni di breanch. Il valore, #prefix#, va sostituito con il nome del prefisso delle tabelle per il vostro DataBase, impostato durante l installazione precedentemente effetuata. 15

16 Se viene generato un errore, sicuramente è un problema di univocità della chiave primaria delle tabelle che andiamo a configurare cambiare il primo valore per modificare il numero univoco che identifica il componente (l ID) o eliminate l inserimento del ID in caso di campo autoincrement. JOOMLA!15 Componenti: Creare un rercord nella #prefix#_components Esempio: INSERT INTO `#_components` (`id`, `name`, `link`, `menuid`, `parent`, `admin_menu_link`, `admin_menu_alt`, `option`, `ordering`, `admin_menu_img`, `iscore`, `params`, `enabled`) VALUES (42, 'JiFile', 'option=com_jifile', 0, 0, 'option=com_jifile', 'JiFile', 'com_jifile', 0, 'components/com_jifile/images/logo16v2.png', 0, '', 1); Plugin Creare un rercord nella #prefix#_plugins INSERT INTO `#_plugins` (`id`, `name`, `element`, `folder`, `access`, `ordering`, `published`, `iscore`, `client_id`, `checked_out`, `checked_out_time`, `params`) VALUES (42, 'Search - JiFile', 'jifile', 'search', 0, 1, 1, 0, 0, 0, ' :00:00', 'search_limit=50'); JOOMLA!25 Creare un record nella #prefix#_extensions Esempio: INSERT INTO `#_extensions` (`extension_id`, `name`, `type`, `element`, `folder`, `client_id`, `enabled`, `access`, `protected`, `manifest_cache`, `params`, `custom_data`, `system_data`, `checked_out`, `checked_out_time`, `ordering`, `state`) VALUES Componenti (10000, 'jifile', 'component', 'com_jifile', '', 1, 1, 1, 0, '{"legacy":false,"name":"jifile","type":"component","creationdate":" ","author":"antonio Di Girolamo and Giampaolo Losito","copyright":"Copyright (C) 2011 isapp.it. All rights reserved","author ":"info@isapp.it","authorurl":" escription":"indexing files(pdf, DOC, HTML, etc) with ifile library.<br\\/><a target=\\"_blank\\" href=\\" '{"base_path":"myfile\\/","index_path":"ifile_index_upperlower2\\/","ignorefile":".cvs, Thumbs.db"}', '', '', 0, ' :00:00', 0, 0), 16

17 Plugin (10001, 'Search - JiFile', 'plugin', 'jifile', 'search', 0, 1, 1, 0, '{"legacy":false,"name":"search - JiFile","type":"plugin","creationDate":" ","author":"Antonio Di Girolamo and Giampaolo Losito","copyright":"Copyright (C) 2011 isapp.it. All rights reserved","author ":"info@isapp.it","authorurl":" escription":"enables_earching_of_files_content","group":""}', '{"search_limit":"50"}', '', '', 0, ' :00:00', 0, 0), Package (10002, 'jifile', 'package', 'pkg_jifile', '', 0, 1, 1, 0, '{"legacy":false,"name":"jifile Package","type":"package","creationDate":" ","author":"Antonio Di Girolamo and Giampaolo Losito","copyright":"","author ":"info@isapp.it","authorUrl":" n":"1.0.6","description":"indexing files(pdf, DOC, HTML, etc) with ifile library.<br\\/>\\n <h1><a href=\\"index.php?option=com_plugins&view=plugins&filter_search=jifile&filter_folder=search\\">e nable the search plugin JiFile! CLICK HERE<\\/a><\\/h1><br \\/>\\n <a target=\\"_blank\\" href=\\" '{}', '', '', 0, ' :00:00', 0, 0); Menù Se la vostra componente lavora anche a livello di backend, va configurata anche la voce di menù: Creare un record nella #prefix#_menu Esempio: INSERT INTO `#_menu` (`id`, `menutype`, `title`, `alias`, `note`, `path`, `link`, `type`, `published`, `parent_id`, `level`, `component_id`, `ordering`, `checked_out`, `checked_out_time`, `browsernav`, `access`, `img`, `template_style_id`, `params`, `lft`, `rgt`, `home`, `language`, `client_id`) VALUES (489, 'main', 'JiFile', 'jifile', '', 'jifile', 'index.php?option=com_jifile', 'component', 0, 1, 1, 10000, 0, 0, ' :00:00', 0, 1, 'components/com_jifile/images/logo16v2.png', 0, '', 311, 312, 0, '', 1); CHECK-IN, GESTIRE LE MODIFICHE AL CODICE SORGENTE Ogni volta che modificate uno o più fili del vostro progetto va ricordato che devono essere committati solo ed esclusivamente i file modificati. Questo per impedire che file che non appartengono al vostro progetto vadano a finire nel repository. Questo è importante per le fasi successive di creazione del package di rilascio per l installazione. Di fatto modificando il file della lingua se committiamo altri file oltre a quello contrassegnato con l icona rossa e il punto esclamativo, passeremo sul repository anche file che non appartengono al progetto. In pratica: 17

18 Clicchiamo con il tasto destro del mouse sul file e selezioniamo la funzionalità di commit (Check-in): Selezionare: TortoiseSVN => SVN Invia A questo punto vi verrà chiesto di inserire un commento. Premendo invio il file viene inviato al repository. Attenzione: Se state lavorando con un gruppo di sviluppo, prima di effettuare un commit (invio) dovete sempre effettuare un update (aggiorna) per verificare se i file che state committando non sono stati modificati da altri e quindi gestire i conflitti. 18

19 ESPORTARE IL PROGETTO PER LA CREAZIONE DEL PACKAGE DI INSTALLAZIONE Siamo arrivati alla parte finale, quella più bella, rilasciare il nostro progetto sulla JED. In pratica: Per poter esportare il progetto dovremmo creare una nuova cartella, ad esempio, packages. A questo punto cliccando con il tasto destro sulla cartella principale del nostro progetto (nel nostro esempio: MioNuvoProgetto), selezioniamo: TortoiseSVN => Esporta Selezioniamo dalla finestra la nuova cartella packages che abbiamo creato e premiamo OK. 19

20 Ricordate che il sistema SVN esporterà solo i file del progetto che avete creato e committato nella nuova cartella. Se avete utilizzato il sistema in modo corretto, non dovreste trovare altri file del Core di Joomla! o di altre componenti, se questi non fanno parte del vostro progetto. La nuova cartella ora conterrà i file pronti per la creazione del vostro pacchetto di installazione per Joomla!. 20

21 A questo punto non vi resta che spostare i file e congifurare il manifest (file XML) di installazione del vostro pacchetto ed il gioco è fatto. Ora siete pronti per rilasciare il vostro lavoro sulla JED. PERCHÉ CREARE BRANCH E TAG L uso dei Tags e dei Branches è potentissimo ed utilissimo se ben capito e gestito. I TAGS 21

22 I Tags non sono altro che la fotografia del progetto in un determinato istante, è come taggare una foto. Ovvero se abbiamo terminato la versione 1.0 e verificato che questa funzioni, dopo il rilascio, si crea un TAG del Trunk del codice sorgente della versione 1.0. Molto spesso ci è stato chiesto a cosa servono questi Tag. Ve lo spieghiamo con un semplice esempio. Risoluzione di Bugs di una versione rilasciata: Supponete di aver rilasciato la nuova versione 1.0 della vostra componente. Alcuni giorno dopo si è passati alla lavorazione della versione 1.1 che comprende un piccolo stravolgimento del codice così come era stato pensato nella 1.0. Per comodità si è pensato di lavorare direttamente sul Trunk. A questo punto si è scoperto un BUG nella versione 1.0. Qui entra in gioco il TAG. Se abbiamo creato un TAG della versione 1.0, da questo si crea un nuovo Breanch (vedi sotto) e si lavora alla risoluzione del problema. In questo modo è possibile poi rilasciare la versione che va a risolvere il BUG riscontrato senza dover mettere mano alla versione 1.1 (e quindi sul Trunk) su cui si è iniziata una nuova implementazione e dove oramai una buona parte del codice sorgente è stato modificato. Risolto il BUG a questo punto, è possibile sia effettuare il merge con il sorgente del TAG 1.0 e rinominare il ramo in 1.0.1, oppure creare un nuovo TAG con la versione Va ricordato pure che se il BUG è presente anche nella versione del sorgente presente sul Trunk queste devono essere riportate anche su questo. I BRANCHES I branches, sono dei rami separati del ramo padre (Trunk) per la gestione di eventuali BUGS riscontrati in una versione (vedi sopra come si è gestito un branches per il BUG della versione 1.0) oppure per l inizio di una nuova feature o versione del vostro progetto. Come sempre vi spieghiamo con un esempio la potenzialità dei Branches. Creazione di una nuova versione: Tornando all esempio di prima, supponiamo che si sia rilasciata la nuova versione 1.0 della vostra componente. Tutti i sorgenti della componente sono presenti nel Trunk (ramo principale che contiene la versione ultima del sorgente). Ora dovete implementare due nuove feature in parallelo, gestite da gruppi (o persone) diverse, e che potrebbero impattare sul codice già esistente e quindi avere conflitti. A questo punto sarebbe opportuno realizzare 2 Branche, uno per ogni feature in modo che ogni gruppo potrebbe effettuare un check-out del proprio branche e lavorare alla feature. Quando uno dei due gruppi ha terminato, effettua un Merge con il Trunk per aggiornarlo e lo stesso farebbe anche il secondo gruppo andando sempre a gestire i conflitti 22

23 (TortoiseSVN ha un ottimo strumento per la gestione dei conflitti) sui file comuni che entrambi i gruppi hanno modificato. Sistemati i conflitti si avrebbero le nuove feature entrambe presenti nel trunk e da qui sarà possibile realizzare il pacchetto di rilascio per la nuova versione 1.1. RIFERIMENTI ON-LINE