Sviluppo software

Questa è una bozza. Gli utenti registrati sono invitati a migliorare questa pagina in qualsiasi momento.

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.

techwikimedia.it

Preambolo

Wikimedia Italia è un capitolo ufficiale riconosciuto da Wikimedia Foundation e fra i suoi obiettivi c'è la promozione della conoscenza libera e il supporto 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, etc.

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

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 collaborativi 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

Inizio incarico

Per unirsi alla community di sviluppo Wikimedia, all'inizio dell'incarico ogni persona nel team di sviluppo verifica di riuscire a fare l'accesso in queste piattaforme:

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

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

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

4. Wikimedia GitLab: collaborazione sul codice (effettuare il primo accesso)

   Vengono richieste le credenziali Wikitech.

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 è responsabile dell'aggiornamento della propria pagina utente pubblica sulle piattaforme 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:

1. https://meta.wikimedia.org/

   Fare login. Visitare la propria pagina utente (solitamente citata in alto a destra).

   1. 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, ...)
   2. inserire informazioni di contatto preferite (esempio: "to contact me, use the talk page, use the button "Send e-mail", etc.)
   3. inserire un link alla propria utenza Wikimedia Phabricator

      Esempio: https://phabricator.wikimedia.org/p/dario.crespi.wmit/

   4. inserire un link alla propria utenza WikiTech

      Esempio link da inserire: https://wikitech.wikimedia.org/wiki/User:Iopensa

2. https://wikitech.wikimedia.org/

   Fare login. Visitare la propria pagina utente (solitamente citata in alto a destra).

   1. inserire un link alla propria pagina Meta-wiki

      Esempio link da inserire: https://meta.wikimedia.org/wiki/User:Dario_Crespi_(WMIT)

3. https://gitlab.wikimedia.org/

   Fare login. Selezionare la propria immagine profilo > Edit profile.

   1. inserire un link alla propria pagina Meta-wiki

      Esempio link da inserire: https://meta.wikimedia.org/wiki/User:Dario_Crespi_(WMIT)

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

Il team di sviluppo è il massimo esperto nel proprio progetto e per questo motivo si occupa anche della documentazione.

Lo scopo della documentazione è ridurre le probabilità che il progetto venga abbandonato per mancanza di conoscenze condivise.

La licenza della documentazione deve essere libera. In caso di dubbi consultare:

• Sostegno nell'uso di licenze libere#Licenze per liberare contenuti

Documentazione sistemistica

Fornire una 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à.

Informazioni da fornire (valutare applicabilità):

• dipendenze software (pacchetti da installare in una nuova Debian GNU/Linux minimale)
• istruzioni installazione (comando apt, etc.)
• istruzioni configurazione (quali sono i file di configurazione di sistema da modificare, etc.)
• percorsi dei file di log più rilevanti per investigare problematiche con l'applicativo
• demoni di sistema legati all'applicativo (e.g. apache2, mariadb, proprie unità Systemd personalizzate, etc.)
• utenti Unix in gioco (esempio: www-data, my-app, etc.)
• istruzioni di sicurezza
  • percorsi che non devono essere visibili dall'esterno (esempio: /var/www/tmp/) etc.
• istruzioni di hardening
  • percorsi che devono essere scrivibili da tali utenti (esempio: percorsi scrivibili da www-data: /var/www/myapp/cache, etc.)
  • percorsi che non devono essere scrivibili (esempio: questi file deve poterli modificare solo l'amministratore di sistema root, non l'utente www-data: /var/www/conf, etc.)
• note di aggiornamento
  • procedura di aggiornamento dell'applicativo
• istruzioni di backup
  • dove vengono salvati i file
  • procedura consigliata per effettuare un backup dei dati

Questa documentazione può essere semplicemente una sezione "Sysadmin documentation" nel README del repository.

Documentazione sviluppo software

Fornire una documentazione da consegnare alle persone nel team di sviluppo, in lingua inglese, con tono semplice e chiaro.

Lo scopo è favorire un passaggio di consegne ad altre persone nel team di sviluppo, e facilitare altre persone (spesso volontari e con poco tempo libero) nel capire la struttura del vostro progetto.

Informazioni minime da fornire:

• descrizione della struttura del progetto (obiettivo: aiutare ad orientarsi)
• come testare il codice in locale
• come configurare l'applicativo

Questa documentazione può essere semplicemente una sezione "Development documentation" nel README del repository.

Documentazione utente

Fornire una documentazione da consegnare agli utenti finali, scritta nella loro lingua principale (e.g. italiano) con tono semplice e chiaro.

L'obiettivo è aiutare gli utenti finali a padroneggiare le parti meno ovvie dell'applicativo.

Questa documentazione è meglio se sia pubblicata su un wiki. Ad esempio una sotto-pagina in https://meta.wikimedia.org/ poiché gli utenti finali non sono necessariamente utenti git. Chiedere qual è la pagina (o sotto-pagina) Meta-wiki da usare, alla persona a capo del progetto.

Questa documentazione può essere omessa se l'interfaccia utente è già sufficientemente auto-esplicativa, se è presente un wizard, ecc.

Inventario

L'inventario delle risorse utilizzate è importante. Le macchine virtuali non inventariate e apparentemente non legate a Wikimedia Italia possono essere eliminate dopo pochi mesi da Wikimedia Foundation.

• verificare che il server di lavoro sia menzionato nella pagina Server
• verificare che eventuali domini personalizzati siano menzionati in Siti

Altri dettagli sul flusso di vita di una macchina virtuale:

• m:wikitech:Help:Cloud VPS Instances#The Cloud VPS Instance lifecycle

Se non è chiaro come correggere l'inventario contatta la Commissione Tech.

Manutenzione

Operazioni a carico del team di sviluppo (fino al termine del proprio incarico):

• prima installazione dell'applicativo nel server Debian GNU/Linux stable fornito
• 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. aggiornando il proprio webserver come nginx o apache2, aggiornando MariaDB, ecc.)
  • verifica delle procedure di #Backup
• comunicazione delle finestre di intervento richieste per la manutenzione (con sufficiente preavviso)
• registro sommario delle attività svolte (e.g. in data odierna eseguito apt upgrade, aggiornato l'app dal codice sorgente, ecc.)

Backup

All'inizio dell'incarico il team predispone un piano di backup, innanzitutto copiando i dati sul server stesso su cui è erogato il servizio (backup on-site).

Questa prima copia serve solo per correggere errori accidentali. Parametri:

• Frequenza minima (e consigliata): ogni 24 ore
• Orario consigliato: fra le 01:00 e le 04:00 Europe/Rome
• Data retention minima (e consigliata): 1 giorno
• Dati da salvare: quelli minimi necessari per fare una recovery del progetto (coerentemente alla #Documentazione sistemistica)

Una volta che questa prima copia è garantita automaticamente, comunicarlo alla Commissione Tech affinché si possano prelevare automaticamente quei backup e depositarli anche sul server esterno di backup (off-site) il quale li manterrà per più giorni. Dettagli:

• Server/Backup onsite

Fino al termine dell'incarico:

• verificare il corretto funzionamento del sistema di backup onsite

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:

• Sostegno nell'uso di licenze libere#Licenze per liberare software

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:

1. aggiorna la propria #Documentazione del team per riflettere le variazioni dei propri ruoli
2. comunica gli account che saranno da disattivare, evidenziando eventuali ruoli amministrativi (ruoli con gestione di altri utenti) alla Commissione Tech:

   To: techwikimedia.it

3. eventualmente, comunica l'elenco delle informazioni personali che si ritiene debbano essere rimosse da Wikimedia Italia, contattando la segreteria (Contatti):

   To: segreteriawikimedia.it

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