Sviluppo software
Pagina rivolta alle persone incaricate da Wikimedia Italia per nuovi sviluppi software.
Nota: la persona responsabile del tuo progetto per Wikimedia Italia potrebbe aver comunicato variazioni, e fanno fede quelle variazioni, soprattutto se espresse nel tuo contratto di incarico.
Variazioni di sostanza a questo documento sono concordate con la commissione Tech.
- tech
wikimedia.it
Preambolo
Wikimedia Italia è un capitolo del movimento Wikimedia e fra i suoi obiettivi c'è la promozione della conoscenza libera e del software libero nonché il sostegno ai volontari. Notare che anche il responsabile del progetto potrebbe essere una persona volontaria. Questa è solitamente una condizione insolita, per cui ti rigraziamo per la tua proattività e spirito di collaborazione nel comunicare l'andamento del tuo lavoro, ecc.
Infrastruttura di Wikimedia Foundation
Potrebbe sorprendere che per i nuovi progetti non viene solitamente usata l'infrastruttura di Wikimedia Italia, o altri hosting condivisi o propri server o non usiamo GitHub. Scoraggiamo queste pratiche perché Wikimedia Foundation fornisce già un'infrastruttura libera, strutturata, moderna, per evitare frammentazione, costi, complessità, gatekeeping, nonché fornisce una gestione delle utenze più efficace e quindi una collaborazione più efficiente.
Ecco una panoramica dei due tipi di accessi separati e cosa forniscono:
Wikimedia Community ("Meta-wiki") fornisce un account globale per accedere a strumenti collaborativi ad accesso pubblico, fra cui:
Wikipedia
- l'enciclopedia libera
Wikidata
- il più grande database collaborativo di dati strutturati
MediaWiki.org
- sito di documentazione del software che mantiene online Wikipedia
Wikimedia Phabricator
- bug tracker collaborativo
- in breve l'account Wikimedia Community dà accesso a 850+ progetti in 220+ lingue
Wikitech fornisce un account separato, per accedere a strumenti tecnici ad accesso riservato, fra cui:
Wikimedia GitLab
- code hosting con git
Wikimedia Cloud services
- server virtuali (VPS) su OpenStack (PaaS)
Wikimedia Horizon
- pannello OpenStack
Wikimedia Toolforge
- hosting condiviso con Kubernetes (IaaS)
- in breve l'account Wikitech dà accesso a git e strumenti di hosting
Notare che tutte questi servizi sono ospitati su macchine fisicamente controllate da Wikimedia Foundation. Non sono di norma necessari servizi ospitati da terzi o SaaSS (per esempio quando si parla di "GitLab" si intende https://gitlab.wikimedia.org/ e non https://gitlab.com/ ).
Chi sviluppa software in questi ambienti accetta i seguenti termini e condizioni:
https://wikitech.wikimedia.org/wiki/Wikitech:Cloud_Services_Terms_of_use
Fra i vari punti, notare che adottare software proprietario o includere contenuti proprietari invalida questi termini. Altresì, non è possibile incorporare risorse di terze parti senza fornire una spiegazione.
Inizio incarico
Tempo necessario: 10 minuti.
All'inizio dell'incarico è necessario che ogni persona nel team sia abilitata a comunicare con il resto della community Wikimedia.
Ogni persona del team si registra in autonomia in Meta-wiki. Questo permette di fare varie cose, fra cui accedere al bug tracker Wikimedia Phabricator.
Per tutte le persone del team:
Wikimedia community · login / registrazione
- Nome utente suggerito:
NomeCognome-WMIT
- Usare il pulsante Log in MediaWiki e inserire le stesse credenziali globali Wikimedia.
Puoi effettuare delle prove facendo una modifica in questo Task pubblico creato appositamente per permetterti di fare alcuni test:
Le persone tecniche del team dovranno anche creare credenziali 
Wikitech per accedere ad esempio a Wikimedia GitLab:
Per tutte le utenze avanzate:
Wikitech · login / registrazione
- Nome utente suggerito:
NomeCognome-WMIT - Nome utente shell suggerito:
nomecognome-wmit
- Inserire le stesse credenziali Wikitech.
A questo punto potrebbe essere necessario farsi approvare l'account di Wikimedia GitLab. Per farselo approvare velocemente, far compilare questo modulo:
Per vedere se le tue credenziali funzionano, è tradizione mettere una Star a questo progetto:
Requisiti architettura software
Questi sono i requisiti pratici progettuali su cui basare il proprio applicativo:
- Sistema operativo sul server
- Debian GNU/Linux stable
- Repository Debian
- main
Il software sviluppato deve essere compatibile con il parco software presente in Debian GNU/Linux stable (attenzione: non sono software recenti) nel repository main (contenente solo software libero). Questo è un requisito tecnico e pratico, determinato dal fatto che questo sistema è l'unico fornito nella OpenStack e in Kubernetes di Wikimedia Foundation, e questa cosa non cambierà a breve.[1]
Alcuni esempi di software noti, con la pagina che descrive l'esatta versione da supportare:
| Software | Versione raccomandata | Fonte |
|---|---|---|
| PHP | 8.2 |
https://packages.debian.org/stable/php |
| Composer | 2.5 |
https://packages.debian.org/stable/composer |
| MariaDB | 10.11 |
https://packages.debian.org/stable/mariadb-server |
| NodeJS | 18.13 |
https://packages.debian.org/stable/nodejs |
| npm | 9.2 |
https://packages.debian.org/stable/npm |
| Python | 3.11 |
https://packages.debian.org/stable/python3 |
| Docker | 20.10 | https://packages.debian.org/stable/docker.io |
Nota: l'indicazione della versione è aggiornata con Debian 12 bookworm Debian 11 bullseye. Potrebbe non essere aggiornata quindi fa fede la fonte.
Se le versioni indicate sono obsolete per i tuoi bisogni, proporre una soluzione compatibile con Debian stable, da una fonte affidabile e che preveda rilasci di sicurezza.
Esempi pratici di richieste perfettamente legittime:
- PHP8+: per supportare PHP8.1 in Debian 11 oldstable bullseye (che altrimenti avrebbe PHP 7.4) si può adottare il repository https://sury.org/ che è affidabile e ufficialmente compatibile con Debian stable
- ...
Linee guida sviluppo software
Seguono alcune linee guida per lo sviluppo di software.
Minimizzare la raccolta dei dati
Seguendo il GDPR, è necessario minimizzare la raccolta dei dati personali.[2]
Esempi pratici:
- non usare Google Analytics (al massimo Matomo di Wikimedia Italia)
- non usare Google Fonts (scarica i font in locale - oppure, se si è già su Wikimedia Cloud usare https://fontcdn.toolforge.org/)
Ottimizzazione
Un buon software si prende cura delle risorse hardware a disposizione.
- Questa dichiarazione dice letteralmente la direzione da intraprendere. Nello specifico, intende di prendersi cura delle seguenti risorse, sia sui server di Wikimedia Italia che sui computer degli utenti:
- utilizzo della CPU
- allocazione della RAM
- occupazione dello spazio su disco
- cicli di scrittura su disco
- Anche perché, c'è un collegamento diretto fra utilizzo della CPU e consumi energetici. A volte un tool ha bisogno di effettuare lunghe operazioni in background per fornire dati aggiornati. A volte questi processi si possono ottimizzare facendo semplici test. In breve, non è solitamente necessario presupporre di avere un team dedicato alla profilazione energetica come in Firefox[3] per prendersi cura delle risorse.
- La direzione è opposta a quella di diversi altri software proprietari che non fanno particolare attenzione sul consumo di risorse, e in generale chiedono semplicemente di occupare più risorse (spesso, degli utenti finali).
L'ottimizzazione non dovrebbe impattare su leggibilità, accessibilità o apertura verso la collaborazione.
- Esempio: evitare di minificare il codice HTML di un sito
- Anche Wikipedia non minifica l'HTML di un sito. Questo rende più semplice l'analisi del documento e la collaborazione.
- Esempio: evitare di minificare il codice JavaScript di un sito
- Non ci sono più enormi vantaggi nel consegnare tutti i file JavaScript in un unico enorme file minificato. Questo è particolarmente vero con l'avvento di tecnologie come HTTP 2.0.
- La minificazione rallenta lo sviluppo software o comunque richiede più risorse energetiche per la produzione degli artefatti. Il rischio principale è che la minificazione ostacoli la collaborazione dei nuovi contributori che atterrano sul sito e vorrebbero aiutare a risolvere un problema, più di quanti vantaggi si possa portare.
- Nello specifico, la minificazione non è accettata in un prototipo. È accettabile in servizi in produzione e ad alto traffico, dopo aver dimostrato un vantaggio significativo.
- Esempio: non offuscare il codice sorgente
- L'offuscazione è una pratica non accettabile in un progetto legato a Wikimedia Italia, perché sabota la collaborazione. Questo vale soprattutto sul codice sorgente eseguito sul computer dell'utente finale.
Documentazione
Le persone nel team di sviluppo sono le massime esperte nel proprio progetto e per questo motivo abbiamo bisogno di voi per curare la documentazione della vostra creatura.
Lo scopo della documentazione non è scriverla bensì leggerla.
L'utilità è evitare che il progetto venga abbandonato o riscritto da capo per mancanza di conoscenze condivise. Potrebbe anche essere utile a sé stessi per ricordarsi certi passaggi dopo una serata sopra le righe.
La documentazione è rilasciata in licenza libera. Suggerimenti:
Documentazione del team
Tempo necessario: 20 minuti
Fino a fine incarico ogni persona mantiene aggiornata la propria pagina utente pubblica.
Questa operazione non serve a fine promozionale ma per aiutare gli altri a capire quali siano (stati) i propri ruoli, i propri incarichi pagati, e quali siano terminati. Non è importante il design ma la brevità e la chiarezza del testo.
Checklist da seguire quando inizia il proprio incarico o quando cambia il proprio ruolo:
- https://meta.wikimedia.org/
- Fare login. Visitare la propria pagina utente
- inserire informazioni sul proprio ruolo e sul proprio incarico in inglese (esempio: "In this period: ... I was paid paid to work on project ... for Wikimedia Italia and ... My specific role: developer, ...)
- inserire informazioni di contatto preferite (esempio: "to contact me, use the talk page, use the button "Send e-mail", etc.)
- inserire un link alla propria utenza Wikimedia Phabricator
- Esempio link da inserire: https://phabricator.wikimedia.org/p/dario.crespi.wmit/
- inserire un link alla propria utenza WikiTech
- Esempio link da inserire: https://wikitech.wikimedia.org/wiki/User:DarioCrespi-WMIT
- (per chi sviluppa software) inserire un link a Wikimedia GitLab
- Esempio link da inserire: https://gitlab.wikimedia.org/ferdi2005
- https://wikitech.wikimedia.org/
- Fare login. Visitare la propria pagina utente (solitamente citata in alto a destra).
- inserire un link alla propria pagina Meta-wiki
- Esempio link da inserire: https://meta.wikimedia.org/wiki/User:Dario_Crespi_(WMIT)
- https://gitlab.wikimedia.org/
- Fare login. Selezionare la propria immagine profilo > Edit profile.
- inserire un link alla propria pagina Meta-wiki
- Esempio link da inserire: https://meta.wikimedia.org/wiki/User:Dario_Crespi_(WMIT)
- assicurarsi di avere una utenza in https://wiki.wikimedia.it/ (se non si ha una utenza in questo wiki, richiederla scrivendo ad infowikimedia.it oppure Contatti)
- verificare che in questa categoria sia elencato il proprio progetto:
- visita questo link: Special:MyPage
Documentazione sistemistica
Fornire una breve documentazione da consegnare al sistemista GNU/Linux, in lingua inglese, con tono semplice e chiaro.
Lo scopo è aiutare una persona esterna a (ri-)creare velocemente un ambiente che ospiti l'applicativo in sicurezza e affidabilità e a mantenerlo aggiornato. Esempi di informazioni da chiarire:
- dipendenze software (pacchetti da installare in una nuova Debian GNU/Linux minimale)
- istruzioni installazione (quale comando apt, ecc.)
- istruzioni configurazione (quali file di configurazione di sistema vanno modificati, ecc.)
- percorsi dei file di log (quelli rilevanti per investigare problematiche dell'applicativo)
- utenti Unix in gioco (magari l'app usa utenti di sistema come www-data oppure ha utenti personalizzati)
- demoni di sistema legati all'applicativo (e.g. proprie unità systemd personalizzate, menzionare altri servizi in uso come mariadb, apache2, nginx, ecc.)
- porte in ascolto (TCP/UDP) e da quale componente dell'app
- istruzioni di sicurezza
- quali percorsi non devono essere esposti all'esterno (esempio: ./my-temp ecc.)
- istruzioni di hardening
- percorsi che devono essere scrivibili dall'app (e assegnati quindi ad un eventuale utente "my-app") durante il suo normale funzionamento (esempio: ./my-upload, ./my-tmp, ecc.)
- percorsi che non devono essere scrivibili dall'app (e assegnabili quindi a root) (esempio: tutti i file eseguibili, ./my-conf ecc.)
- note di aggiornamento
- procedura di aggiornamento dell'applicativo
- procedura di backup e restore
- dove sono sul filesystem i dati degli utenti da preservare (esempio: ./my-upload ecc.)
- quali database vanno preservati
- come attivare eventuali flag di manutenzione
Questa documentazione può essere semplicemente una sezione nel README del repository (esempio: "Sysadmin documentation").
Documentazione sviluppo software
Il codice sorgente andrebbe pubblicato fin dalla prima riga di codice, preferibilmente in Wikimedia GitLab.
Fornire una breve documentazione utile per comprendere la struttura del progetto. Scopo: aiutare altre persone ad avvicinarsi, orientarsi e contribuire, semplificando passaggi di consegne, ecc.
Dedicare almeno un paragrafo ad ognuno di questi punti:
- scopo del progetto / sfide incontrate
- struttura del progetto (per orientarsi nelle directory)
- come testare il codice in locale
- come configurare l'applicativo (testing / produzione)
- come esaminare eventuali log
- accortezze in produzione
Suggerimenti:
- lingua inglese (termini semplici, non troppo ricercati)
- utile anche per voi stessi
Questa documentazione può essere semplicemente una sezione "Development documentation" nel README del repository.
Documentazione utente
Fornire una documentazione indirizzata agli utenti finali (e.g. volontari delle comunità in lingua italiana), coprendo la loro lingua principale (e.g. italiano) con tono semplice e chiaro per padroneggiare le parti meno ovvie dell'applicativo.
Suggerimento: iniziare la bozza su Associazione:Nextcloud (workspace) che ha un editor visuale collaborativo, o su un Etherpad, senza curare troppo la formattazione. Evitare fin da subito strumenti proprietari.
Pubblicare la documentazione utente preferendo un wiki, ad esempio una sotto-pagina in https://meta.wikimedia.org/ poiché gli utenti probabilmente sanno usare più un wiki rispetto a git, e poi Meta-wiki supporta le traduzioni.
Questa documentazione può essere omessa se l'interfaccia utente è già sufficientemente auto-esplicativa, se è presente un wizard, ecc.
Inventario server
Documentare quali macchine virtuali si sta utilizzando. Le macchine non inventariate possono rischiare l'eliminazione da parte di Wikimedia Foundation anche dopo pochi mesi.[4]
- verificare che il server di lavoro sia menzionato nella pagina Server#Altri server in Wikimedia Cloud
- verificare che eventuali domini personalizzati siano menzionati in Siti
Manutenzione
Ecco alcune brevi e utili operazioni di manutenzione a carico del team di sviluppo fino al termine del proprio incarico:
- curare la prima post-installazione del server per ospitare il proprio applicativo
- effettuare manutenzione ordinaria
- aggiornamenti software del proprio applicativo
- aggiornamenti di sicurezza del proprio applicativo e delle proprie dipendenze software (e.g. per PHP usando Composer, ecc.)
- aggiornamenti di sicurezza delle proprie dipendenze software nel sistema operativo (e.g. apt update, apt upgrade)
- verifica del funzionamento delle proprie procedure di #Backup
Approfondimenti:
- m:wikitech:Cloud VPS Server Admin Log - lo strumento ufficiale per comunicare cosa è stato fatto durante un proprio intervento su un server
Se l'applicativo è già in produzione:
- pianificare e comunicare le finestre di intervento richieste per svolgere le attività di manutenzione che possono causare fermi macchina (gentile preavviso di 6 ore)
Comunicazione
Meglio discutere pubblicamente (ad esempio creando Task in Wikimedia Phabricator) invece che per email o chat private. Parlare pubblicamente valorizza il tuo lavoro e lo rende maggiormente comprensibile, attivando la partecipazione.
Programmazione:
- in git, fare commit con messaggi comprensibili in cui ci sia almeno scritto il perché o comunque il proprio obiettivo
Sistemistica:
- per Wikimedia Toolforge e Wikimedia Cloud VPS, entrare in IRC e lasciare una riga nel Server Admin Log sul relativo server
Per tutti:
Proponete incontri, anche online (anche solo su Jitsi Meeting), aperti alla community. Non tanto per presentare ciò che è stato fatto, ma anche per condividere qualche problema tecnico con altre persone e ricevere feedback potenzialmente preziosi per le prossime direzioni. Per info su come contattare i soci, vedi la pagina soci.
Potreste desiderare di coinvolgere anche i volontari in generale. In quel caso vedi pagine come wikipedia:it:Wikipedia:Bar.
Backup
All'inizio dell'incarico il team predispone un semplice piano di backup automatico, innanzitutto sullo stesso server in cui è localizzato il servizio (backup on-site).
Scopo del backup on-site: permettere agli sviluppatori di ripristinare i dati a prima di un (loro?) errore, in autonomia. Parametri minimi e consigliati:
- Dati da salvare: quelli minimi necessari per fare un ripristino del progetto
- Esempi da poter includere: database, configurazioni applicative private, upload degli utenti, log applicativi della giornata, ...
- Esempi da poter escludere: file del sistema operativo, file già pubblicati altrove (git), cache, log già vecchi, ...
- Frequenza: ogni notte
- Orario: la notte fra le 01:00 e le 04:00 Europe/Rome
- Data retention: 24 ore (una sola copia, ogni nuovo backup sovrascrive il più vecchio)
Una volta implementato, la verifica del corretto funzionamento del backup giornaliero prosegue per buon senso almeno fino al termine dell'incarico.
Pratiche sui Backup onsite
Può essere sufficiente iniziare ad implementare il backup onsite con una riga nella pianificazione di sistema (crontab, ecc.) e/o usando semplici strumenti (come mysqldump, rsync, ecc.).
Destinazione consigliata per i file sotto backup onsite:
/var/backups/wmi/$HOSTNAME/daily/
La directory non deve essere accessibile a utenti estranei all'applicativo. Per raggiungere questa restrizione può essere sufficiente lanciare chown app:app, chmod o= /path per assegnare i file alla tua utenza applicativa, e nasconderla ad altre utenze.
Generalmente conviene adottare questi sotto-percorsi già in uso altrove:
/var/backups/wmi/$HOSTNAME/daily/files/etc/var/www/index.html /var/backups/wmi/$HOSTNAME/daily/databases/limesurvey.sql.gz
In questo modo, in un percorso ci sono i backup dei file mantenendo il loro albero originale, e in un altro i database.
I backup onsite non hanno generalmente senso all'interno di un container Docker o unità virtuali guest simili. Detto ciò, vanno generalmente implementati sulla macchina host che esegue i vari container, affinché si abbia una copia dei loro volumi.
La commissione Tech è a disposizione per chiarimenti, premettendo che qui ci sono ulteriori informazioni:
La procedura di backup e di ripristino è da descrivere in modo semplice, breve e chiaro, nella #Documentazione sistemistica.
Domini e DNS
Per evitare attacchi di phishing, non vengono solitamente acquistati ulteriori domini rispetto a quelli già presenti nella pagina apposita:
Se desideri registrare un nuovo dominio o modificarne uno già esistente, segui la procedura in:
Codice di condotta
L'inizio dell'incarico definisce l'accettazione del codice di condotta.
Termini d'uso
L'inizio dell'incarico definisce l'accettazione dei termini d'uso per la gestione delle risorse hardware di Wikimedia Foundation.
https://foundation.wikimedia.org/wiki/Terms_of_Use/it
Licenza software
La licenza del software deve essere libera. In caso di dubbi consultare:
Termine incarico
Prima della conclusione o sospensione (presumibilmente) definitiva di un proprio incarico o della propria attività:
Il team propone delle date per una presentazione tecnica del progetto, aperta alla community, per favorire il passaggio di consegne. Presentando almeno i vari tipi di #Documentazione.
Prima della conclusione dell'incarico di un membro del team, tale persona:
- aggiorna la propria #Documentazione del team per riflettere le variazioni dei propri ruoli
- comunica gli account che saranno da disattivare, evidenziando eventuali ruoli amministrativi (ruoli con gestione di altri utenti) alla Commissione Tech:
- To: techwikimedia.it
- To: tech
- eventualmente, comunica l'elenco delle informazioni personali che si ritiene debbano essere rimosse da Wikimedia Italia, contattando la segreteria (Contatti):
- To: segreteriawikimedia.it
- To: segreteria
Contatti
Se un passaggio non è chiaro, proseguire nell'avanzamento lavori con i restanti punti.
Nel frattempo la Commissione Tech è a tua disposizione per chiarimenti o altro, via email:
- techwikimedia.it
Note
- ↑ https://wikitech.wikimedia.org/wiki/Help:Toolforge/Kubernetes
- ↑ https://edps.europa.eu/data-protection/data-protection/glossary/d_en
- ↑ https://firefox-source-docs.mozilla.org/performance/power_profiling_overview.html
- ↑ (EN) m:wikitech:Help:Cloud VPS Instances#The Cloud VPS Instance lifecycle
- «Instances will be removed for projects that have been determined inactive.»