Sviluppo del software

Progetto e3g, Software gestionali per l'economia solidale

Appunti vari inerenti la stesura del codice di e3g.

Quando una sezione diventa abbastanza grande, dedicargli un'intera pagina collegata a questa con un link.


Contents

[edit]

TODO-list

  • Software TODO list: elenco dei singoli interventi da effettuare sul codice sorgente (modifiche, correzioni, nuove funzionalità, ecc.)


[edit]

Change-log

  • Il change-log è stato spostato direttamente nella root dei sorgenti.


[edit]

Documentazione del codice

Diversi progetti open-source utilizzano phpDocumentor (come lo stesso p4a, vedi http://p4a.sourceforge.net/code-reference); è un tool per auto-documentare sorgenti PHP e creare dinamicamente una documentazione professionale.

Come alternativa esiste PhpXref, the PH Cross Referencing Documentation.

Un elenco degli elementi riconosciuti da phpDocumentor e un esempio in PEAR.


[edit]

Protezione / Sicurezza

  • Ricordarsi di mettere sempre in ogni directory dei sorgenti un file vuoto denominato index.html (per evitare che collegandosi direttamente a quell'indirizzo si possa vedere l'intero elenco dei file contenuti in quella directory tramite un comune browser).


[edit]

Numero di versione

[edit]

Versione del programma

E' importante tenere una variabile globale per memorizzare il numero di versione del software, e visualizzarla alla base delle pagine; siccome ci sono mille modi per conteggiare build e release si possono usare le seguenti regole.

Il numero di versione è nella forma x.y.z (ad esempio 2.1.16) dove:

  • x rappresenta il numero principale della versione: viene incrementato per ogni rilascio del codice che contiene cambiamenti nell'architettura, riscrittura di intere sezioni e/o l'aggiunta di numerose funzionalita' significative
  • y rappresenta il numero secondario della versione, che viene incrementato per le aggiunte di alcune funzionalita' significative
  • z rappresenta gli aggiornamenti per funzionalita' minori o correzioni di errori

Il numero di versione si riferisce al software e3g in generale, quindi non ci saranno due numerazioni distinte per equogest e gestigas. La versione 0.1.0 sarà quella con cui inizieremo i test reali coi gas.

[edit]

Versione e aggiornamenti del database

Anche il database deve ovviamente possedere un numero di versione, da gestire nel seguente modo.

Si fa uso di un numero di versione del database memorizzato nei sorgenti (database atteso) ed un altro memorizzato in una tabella dati del db (versione reale del database). In un'apposita cartella ci sono i singoli file SQL di aggiornamento da una versione alla successiva, con un nome in codice che può essere generato dai sorgenti, i quali se in apertura si accorgono dell differenza di versione chiedono all'amministratore se eseguire l'upgrade; questi può ignorare (per vari motivi) e rimandare la cosa. Esempio di nome dei file SQL di aggiornamento: update_multi_0012.sql, update_multi_0013.sql, ecc.

Per la versione del database usiamo una semplice numerazione progressiva, a partire da zero, e con 4 cifre: 0000, 0001, 0002, e così via.

Considerare però che abbiamo in realtà due versione di database: quella delle tabelle condivise e quella della singola gestione.

Per quanto riguarda la gestione degli aggiornamenti del database, considerare quella utilizzata da PhPeace e descritta in questa pagina: http://dev.phpeace.org/trac/wiki/DatabaseUpdates così:

If you want to change the database schema, introducing new tables or columns, or changing the current ones, please follow this procedure
  • Write the necessary SQL statements, in the safest possible way (do not assume a specific database version or implementation)
  • Execute them locally in the database you're currently using for development
  • Execute the test scripts to check that they don't break the current functionalities
  • If you're happy with them, add them to the new update script for the next release, in pub/phpeace/update_{NEXT_BUILD_NUMBER}.php, so that the changes will be done to the existing installations; if you're not sure what the next build number is, check it in http://dev.phpeace.org/trac/browser/trunk/admin/phpeace/version.xml
  • Execute dev/scripts/phdb.sh to recreate dbschema.sql and init.sql based on your installation
  • Compare your local dbschema.sql and init.sql with the ones in the subversion repository, to check that the differences are what you expect to see
  • Commit the update script, install/dbschema.sql, install/init.sql


[edit]

Amministrazione database

Considerare l'uso di DBDesigner, un tool (con licenza GPL) per la progettazione visuale dei database; è stato scritto con Delphi per Windows, ma c'è anche una versione compilata per Linux, probabilmente creata con Kylix (Delphi per Linux).


[edit]

Diversi livelli di accesso

Sono possibili 5 tipologie di accesso (in ordine di poteri):

(codice - nome breve - nome lungo: descrizione)

  1. AS - super/global admin - Amministratore globale: amministra tutta l'installazione di e3g che può comprendere più gas
  2. A - admin - Amministratore: amministra il singolo gas
  3. R - referente - Referente: amministra qualche produttore all'interno di un singolo gas
  4. U - utente - Famiglia aderente: può effettuare gli ordini
  5. G - visitatore - Visitatore non registrato / ospite (Guest): può scorrere l'elenco dei produttori ed eventualmente i prodotti (con i prezzi se l'admin lo ha consentito)

Il super admin entra da un indirizzo diretto e dopo user/pass gli si presenta un elenco di gas/botteghe presenti nel db ed una serie di bottoni per compiere operazioni a livello globale, ad esempio per aggiornare il database, oltre che un link per connettersi ad un particolare soggetto in qualità di amministratore (singolo). Magari organizzare i link in forma tabellare: sulle righe l'elenco dei database (gas/botteghe) e sulle colonne le operazioni possibili.

Esempio di indirizzo che andrebbe bene: http://www.gestigas.org/demo/admin Tutti gli altri accessi - inferiori al global admin - hanno invece un indirizzo per accedere direttamente al loro gas

Esempi alternativi:


[edit]

Bozza riorganizzazione

Mail del 14/01 (da Marco ad Andrea)

L'idea proviene dall'esperienza di noti cms, come moodle, postnuke, joomla e altri.

Allora, noi abbiamo: super admin, admin, referente, famiglia, visitatore. Escludiamo per ora il visitatore che introdurremo solo in futuro.

Admin, referente e famiglia entrano da un certo indirizzo con i loro user/pass e gli si presenta una identica maschera che è quella della famiglia, semplice e con le opzioni minime per scorrere il listino e fare l'ordine. Possibilmente nella parte bassa di ogni finestra il sistema ricorda il nostro user e tra parentesi il nostro tipo di account. Es: "Sei collegato come marco (famiglia)" oppure "Sei collegato come luca (referente)".

Admin e referente però si vedono a fianco di questa scritta anche un link per accedere al pannello di amministrazione (es. "Sei collegato come mario (referente) - Amministra"); questi non è altro che una finestra completamente diversa da quella delle famiglie, e simile all'impostazione attuale, con menu in alto e qualche bottone a centro pagina per le operazioni più frequenti. Ovviamente il referente non vedrà alcune delle voci di menu ed alcuni dei bottoni sui quali non ha potere di agire (per es. l'anagrafica famiglie, ecc.).

Guardando i sorgenti ho visto che adesso hai programmato la cosa in modo diverso e cioè la finestra è la medesima e costruisci un menu diverso a seconda del tipo utente, ma credo che il sistema più sopra, oltre che soddisfare meglio gli utenti, sia alla lunga preferibile anche per noi programmatori. Adesso infatti se abbiamo necessità di aggiungere una voce che interessa chi effettua gli ordini, la dobbiamo mettere sia nel menu dell'amministratore che in quello di utenti e referenti. Nell'altro modo invece no, in quanto nella finestra di amministratori e referenti non ci sono voci di menu e bottoni per fare l'ordine.

E veniamo al super admin, quello globale che vede ed opera su tutte le installazioni. Dovrebbe probabilmente entrare da un diverso indirizzo, ma in ogni caso dopo l'autenticazione avrebbe l'elenco dei singoli database (come già accade adesso) con alcuni link o bottoni per compiere operazioni globali come aggiornamento del database e altro. A fianco di ognuno ci sarebbero poi i link per collegarsi al gas in due modi distinti: come famiglia, oppure come amministratore/referente ovvero il pannello di amministrazione.


[edit]

Sviluppo collaborativo

Per la condivisione dei sorgenti, utilizziamo il repository offerto da sourceforge.net, mentre come editor si usa di preferenza Eclipse SDK, un potente ambiente integrato per lo sviluppo (collaborativo) di software. Eclipse è dotato di funzionalità per connettersi automaticamente ad un sistema CVS come quello di Sourceforge. Al momento utilizziamo la Eclipse SDK versione 3.2.2.

E' consigliabile l'installazione dell'apposito plug-in PHP-Eclipse TruStudio PHP, in quanto Eclipse può lavorare su diversi linguaggi e questo plug-in aggiunge numerose funzionalità quando il linguaggio è PHP (evidenziazione sintassi, costruzione dell'albero delle funzioni, completamento della scrittura, ecc).


[edit]

Installazione Eclipse SDK su Ubuntu Linux v. 7.04 (vale anche per 7.10)

Aggiornamento del 03/10/2008: utilizzando questa guida su un'installazione pulita di Ubuntu 7.10 si hanno dei problemi col plugin PhpEclipse; questo perchè nei repository Ubuntu c'è Eclipse 3.2 e con questa versione bisogna usare PhpEclipse non oltre la 1.1.8 solo che nel sito del pluging si trova ormai solo la 1.1.9 (incompatibile con Eclipse 3.2) oppure la 1.1.2 che viene indicata solo per Eclipse 3.3 o 3.4. Non resta che scaricare il pacchetto di Eclipse ed installarlo manualmente, e poi aggiungere il plugin come descritto qui di seguitoo (indicando però il ramo 1.2, vedere nel wiki di PhpEclipse). In particolare si è fatto riferimento a questi appunti con le seguenti differenze

  1. URL per PhpEclipse: http://update.phpeclipse.net/update/stable/1.2.x
  2. avvio di eclipse con: 
    gksu eclipse
    in quanto sono necessari i privilegi di amministratore.


[edit]

Installazione Java

Di default Eclipse usa Java di GNU anziché quello di Sun: questo lo rende molto lento, provoca dei frequenti crash ed impedisce il funzionamento del plug-in PhpEclipse. Per risolvere questo problema occorre installare Java di Sun e dire ad Eclipse di usare questo.

Installare il Java Runtime Environment (JRE o JVM, Java Virtual Machine) di Sun: 

sudo apt-get install sun-java6-jre sun-java6-plugin sun-java6-bin sun-java6-fonts

sun-java6-plugin in realtà server per il browser e non è strettamente indispensabile per Eclipse.

Rendere di default JRE di Sun: 

sudo update-alternatives --config java

scegliendo la riga con /usr/lib/jvm/java-6-sun/jre/bin/java (dovrebbe essere la terza).

Modificare il file di configurazione di Java: 

gksu gedit /etc/jvm

in questo modo: 

# This file defines the default system JVM search order. Each
# JVM should list their JAVA_HOME compatible directory in this file.
# The default system JVM is the first one available from top to
# bottom.

/usr/lib/jvm/java-6-sun
/usr/lib/jvm/java-gcj
/usr/lib/jvm/ia32-java-1.5.0-sun
/usr/lib/jvm/java-1.5.0-sun
/usr

in pratica si tratta di aggiungere la prima riga (/usr/lib/jvm/java-6-sun).


[edit]

Installazione di Eclipse

Installare Eclipse ed il supporto per le lingue con (da terminale): 

sudo apt-get install eclipse eclipse-nls

Ora bisogna dire ad Eclipse di usare la JVM corretta modificando il suo file di configurazione con: 

gksu gedit /etc/eclipse/java_home

in questo modo: 

# This file determines the search order the Eclipse Platform uses to find a
# compatible JAVA_HOME. This setting may be overridden on a per-user basis by
# altering the JAVA_HOME setting in ~/.eclipse/eclipserc.

/usr/lib/jvm/java-6-sun
/usr/lib/jvm/java-1.5.0-sun
/usr/lib/jvm/java-gcj
/usr/lib/kaffe/pthreads
/usr/lib/j2se/1.5
/usr/lib/j2se/1.4
/usr/lib/j2sdk1.5-ibm
/usr/lib/j2sdk1.4-ibm
/usr/lib/j2sdk1.5-sun
/usr/lib/j2sdk1.4-sun

in pratica si tratta di aggiungere la prima riga (/usr/lib/jvm/java-6-sun).

Fare particolare attenzione al contenuto di questo file (/etc/eclipse/java_home) dopo un eventuale aggiornamento di Ubuntu in quanto tipicamente viene ripristinato l'ordinamento di default; il sintomo è che dopo aver avviato Eclipse non si riesce più a vedere alcun sorgente.

A questo punto avviando Eclipse da terminale (basta scrivere eclipse e dare invio) è possibile leggere (nel terminale appunto) quale JRE è in esecuzione; nel mio caso: 

marco@vanessa:~$ eclipse
searching for compatible vm...
  testing /usr/lib/jvm/java-6-sun...found


[edit]
Installazione del plug-in PhpEclipse in Ubuntu Linux

Premesso che Eclipse integra al suo interno un sistema di gestione degli aggiornamenti, utile a ricevere le nuove versioni dei componenti e dei plug-in installati, per installare PhpEclipse è necessario avviare il programma con privilegi di root. Da terminale: 

gksu eclipse
  • avviare l'update manager (Help | Software Updates | Find and Install...)
  • tra le due opzioni:
"Search for updates of the currently installed features"
per controllare la presenza di aggiornamenti per i componenti di programma e plug-in aggiuntivi installati
"Search for new features to install"
per avere la lista dei plug-in disponibili per l'installazione corrente

sceglere quest'ultima, poi

  • premere "New Remote Site..."
  • scrivere un nome a piacere (esempio: PHPeclipse 1.1.x) più l'indirizzo "http://update.phpeclipse.net/update/stable/1.1.x" (ciò vale per Eclipse fino a 3.2, altrimenti ci sono versioni più avanzate, vedere nel wiki di PHPeclipse)
  • fare clic su "Finish"
  • dall'elenco di componenti che appare, selezionare PhpEclipse e seguire le semplici istruzioni per concludere l'installazione.

Vedere anche le indicazioni nel wiki di PhpEclipse.

[edit]

Installazione di Eclipse su Windows

Dopo il download, basta scompattare l'archivio ed estrarre i file in una cartella a piacere; può essere necessario installare anche JRE (Java Runtime Environment). Il procedimento è analogo anche per i plug-in (scompattare in una sottodirectory di Eclipse (C:\Programmi\Eclipse\...). Abilitare i plug-in tramite la finestra "About | Software updates | Manage configuration".

[edit]

Configurazione ambiente di sviluppo

A questo punto occorre crearsi un workspace che possiamo associare ad una directory a piacere e che sarà il contenitore dei nostri progetti; supponiamo (in Windows) che sia D:\EclipseWS oppure (in Linux) /home/eclipse_ws.

"File | New | Project" e scegliere il wizard "CVS | Checkout Projects from CVS"; nella finestra successiva vengono richiesti i parametri:

  • Location host: equogest.cvs.sourceforge.net
  • Repository path: /cvsroot/equogest
  • User e password: quelli del nostro account su Sourceforge
  • Connection type: extssh
  • Porta: 22

In caso di necessità controllare la guida su Sourceforge.

Scegliere di salvare la password e poi Next; nella finestra successiva specificare il modulo "equoweb/equogest_p4a", oppure selezionarlo tra quelli esistenti sotto; confermare, attendere il checking out ed il gioco è fatto: avremo una copia dei sorgenti sul nostro PC sui quali studiare e poter lavorare.


[edit]

CVS

Qualche riferimento sul CVS:

[edit]

Standard di programmazione

Per semplificare la collaborazione di più persone sullo stesso codice è importante usare lo stesso standard di programmazione. Come standard di programmazione si consiglia di usare quello di Pear (meglio stamparle per averle sempre sottocchio).

http://pear.php.net/manual/en/standards.php

Vedi anche: http://gazie.sourceforge.net/coding.php

[edit]

Sviluppatori Open-Source

Documento di riferimento con le migliori pratiche per sviluppatori open-source:

http://www.catb.org/~esr/writings/taoup/html/ch19s02.html

[edit]

Rilascio nuova versione

Pro-memoria delle fasi da compiere per rilasciare una nuova versione del progetto:

  1. Modificare nel config_const.php il numero di versione dei sorgenti in rilascio
  2. Installarsi l'ultima versione stabile di p4a e verificarne la compatibilità con i sorgenti provando tutto il "giro" di un ordine; eventualmente caricare entrambi (p4a ed e3g aggiornati) sul server di test per un'ulteriore verifica e a questo scopo seguire la spiegazione più sotto per l'esportazione da Eclipse dei file del rilascio
  3. Modificare il manuale d'installazione (nel wiki) aggiornando il numero di versione di p4a con il quale è garantita la compatibilità; generare la versione PDF del manuale e sistemarla nel CVS
  4. Controllare ed eventualmente aggiornare i manuali d'uso di Equogest e GestiGAS; generare le versioni PDF e sistemarle nel CVS
  5. Fare il commit generale di queste ultime modifiche
  6. Marcare il rilascio nel CVS tramite tag (per poterlo recuperare nel caso di bugfix): in Eclipse fare "Team | Codifica come versione..." sulla root del progetto ed assegnare il tag composto da numero di versione seguito dalla data di rilascio, per esempio, "Versione_0-14-0_2007-12-23"
  7. Generare i file da rilasciare mediante il comando "File | Export..." in Eclipse; nelle finestre di dialogo escludere i vari file di supporto (.cvsignore, .project, config.php) e le varie directory di supporto (.settings, cache, p4a_tmp); selezionare una directory di destinazione (esempio: ~/temp/e3g_0.14.0/) e premere "Fine"
  8. Creare un archivio compresso dei file, di tipo zip (più conosciuto del tar.gz), contenente tutti i file compresa la directory superiore (col numero di versione) e denominarlo "ProgettoE3G_x.y.z_beta.zip"; ricordarsi di verificare l'integrità dell'archivio
  9. Caricamento dell'archivio in sourceforge.net: si carica tramite SFTP, ovvero, da linea di comando: 
$ sftp nome_utente@frs.sourceforge.net

specificare la password, poi 

sftp> cd uploads
sftp> lcd /PATH/TO/FILES

(lcd serve per spostarsi in locale nella directory dove c'è il file da caricare, quindi ad esempio sftp> lcd ~/Desktop; usare lpwd per visualizzare la directory attuale) 

sftp> put ProgettoE3G_x.y.z_beta.zip
sftp> exit

Pubblicazione in sourceforge.net:

  1. Fare login e scegliere "Admin | File releases"
  2. Fare clic su "Add Release" per il package esistente "Equogest + GestiGAS"
  3. Impostare il New release name (sul modello x.y.z_beta) e fare clic su "Create This Release"
  4. Impostare Release Date, Release Name (sul modello x.y.z_beta, ci dovrebbe già essere), mettere Status su "Active" e premere un po' più sotto "Submit/Refresh"
  5. Nello "Step 2" contrassegnare il proprio file tra tutti quelli caricati di recente (di tutti gli utenti di sourceforge!) e fare clic su "Add Files and/or Refresh View"
  6. Nello "Step 3" scegliere come Processor la voce "Platform indipendent", come File type la voce "zip", poi clic su "Update/Refresh"

Da questo momento il file è disponibile e può essere scaricato.

  1. Fare una prova di download da sourceforge e controllare l'integrità dell'archivio
  2. Rendere disponibile come link nella sezione Download del sito del progetto il pacchetto creato (creare una nuova voce e lasciare quella precedente)
  3. Fare una prova di download dal sito del progetto e controllare l'integrità dell'archivio
  4. Preparare una notizia del rilascio' con le principali novità principali dedotte dal changelog; preparare anche il testo per la newsletter di contenuto simile alla notizia
  5. Pubblicazione notizia nel [http:// www.progettoe3g.org sito del progetto]
  6. Invio della newsletter da http://liste.lillinet.org/viewforum.php?l=36
[edit]

Progetti esempio

Segnaliamo di seguito alcuni progetti in qualche modo simili al nostro, dai quali possiamo trarre qualche utile indicazione rispetto alla loro organizzazione di sviluppo del codice, di coordinamento nel team, e così via.

[edit]

Phasis

http://www.phasis.it

Phasis è un gestionale Open Source indirizzato alla piccola e media impresa Italiana rilasciato secondo la licenza GNU/GPL. E' interessante in particolare il sistema che usano per lo sviluppo collaborativo: [Trac].

[edit]

PhPeace

http://www.phpeace.org/

PhPeace e' un progetto software nato per la gestione del sito di PeaceLink. Non ha niente a che vedere con i gestionali: tecnicamente e' un CMS (Content Management System), sviluppato in PHP su sistema operativo GNU/Linux, progettato e realizzato da Francesco Iannuzzelli (francesco@peacelink.org) con il supporto della redazione di PeaceLink. E' da tenere come riferimento per alcuni aspetti organizzativi dello sviluppo, per gli strumenti usati, ecc.

[edit]

GAZIE

http://gazie.sourceforge.net/

GAZIE è un programma eseguibile su Web server con il supporto PHP e DBMS Mysql per la gestione delle vendite e della contabilità di piccole e medie aziende.

[edit]

YUZA Open ERP

http://www.yuza.it/

Yuza Open Erp è un software gestionale open source italiano scritto interamente in c# per computer con sistema operativo Microsoft Windows. Licenza GNU/GPL.


[edit]

Migrazione a P4A versione 3

Vedere pagina dedicata: Migrazione a P4A versione 3

[edit]

Sezioni possibili da aggiungere

  • Indicazioni per la creazione di un virtualhost
  • Installazione di p4a
Ricavato da "http://wiki.progettoe3g.org/index.php/Sviluppo_del_software"
Personal tools
link al sito del '''Progetto e3g'''