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:
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
- e altri
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)
- e altri
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/ ).
Inizio incarico
Per unirsi alla comunità di sviluppo Wikimedia, all'inizio dell'incarico ogni persona nel team di sviluppo verifica di riuscire a fare l'accesso in questi siti:
Meta-wiki: account globale Wikimedia (registrare account)
- Questa registrazione ti fornisce credenziali valide per meta.wikimedia.org, mediawiki.org, wikipedia.org, phabricator.wikimedia.org e altri siti collaborativi per la community generalista.
- Wikimedia Phabricator: bug tracking (effettuare il primo accesso)
- Usare il pulsante a sinistra per effettuare il login (Log in or Register MediaWiki)
- Si verrà reindirizzati a mediawiki.org. A questo punto inserire le credenziali globali Wikimedia.
Wikitech: wiki tecnico riservato (registrare account)
- Questa registrazione separata fornisce l'accesso a wikitech.wikimedia.org, gitlab.wikimedia.org e altre risorse per la community tecnica.
- Wikimedia GitLab: collaborazione sul codice (effettuare il primo accesso)
- Vengono richieste le credenziali Wikitech.
- Vengono richieste le credenziali
Si ricorda che ogni account è strettamente personale e ogni singola persona è responsabile della robustezza delle proprie credenziali.
Documentazione del team
Fino a fine incarico ogni persona mantiene aggiornata la propria pagina utente pubblica sui wiki Wikimedia.
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 (solitamente citata in alto a destra).
- 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
- inserire un link alla propria utenza WikiTech
- Esempio link da inserire: https://wikitech.wikimedia.org/wiki/User:Iopensa
- 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 pagina sia elencato il proprio progetto:
- verificare che la propria pagina utente in https://wiki.wikimedia.it/ abbia i template {{Accesso}} per descrivere i propri livelli di accesso
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.
Alcuni esempi di software noti, con la pagina che descrive l'esatta versione da supportare:
- https://packages.debian.org/stable/php (7.4)
- https://packages.debian.org/stable/mariadb-server (10.5)
- https://packages.debian.org/stable/nodejs (12.22)
- https://packages.debian.org/stable/composer (2.0)
- https://packages.debian.org/stable/npm (7.5)
- https://packages.debian.org/stable/docker
Nota: l'indicazione fra parentesi potrebbe non essere aggiornata, fa fede la pagina su Debian.
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 stable bullseye (che altrimenti avrebbe PHP 7.4) si richiede di installare l'affidabile e compatibile repository https://sury.org/
- NodeJS: ...
- ...
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 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
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.[1]
- 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
- comunicazione delle attività svolte nel server admin log
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.
Suggerimento: se è comodo, può essere sufficiente implementare il backup on-site con una riga nel crontab, usando semplici tool come mysqldump e/o rsync ecc.
Destinazione consigliata per i file sotto backup:
/var/backups/wmi/$HOSTNAME/daily/files...
La directory non deve essere accessibile a utenti estranei all'applicativo.
Suggerimento: può essere sufficiente lanciare chown app:app, chmod o= /path
La commissione Tech è a disposizione per chiarimenti, premettendo che qui ci sono ulteriori informazioni:
Suggerimento: il tuo backup e il suo ripristino sono descritti in modo davvero semplice e chiaro nella #Documentazione sistemistica.
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
- ↑ (EN) m:wikitech:Help:Cloud VPS Instances#The Cloud VPS Instance lifecycle
- «Instances will be removed for projects that have been determined inactive.»