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.

techwikimedia.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:

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

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à 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 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 server

Le macchine virtuali non inventariate possono rischiare l'eliminazione da parte di Wikimedia Foundation anche dopo pochi mesi.

• 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

Operazioni 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
• comunicare le finestre di intervento richieste per la manutenzione (preavviso 6 ore)
• curare il "SAL" (breve registro attività pubblico)

  m:wikitech:Cloud VPS Server Admin Log

Comunicazione

• comunicazione delle attività svolte nel server admin log

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