Sviluppo software

Da Wikimedia Italia.
Jump to navigation Jump to search

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(chiocciola)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 Logo optimized.svg

Wikimedia Community ("Meta-wiki") fornisce un account globale per accedere a strumenti collaborativi ad accesso pubblico, fra cui:

Wikipedia-logo-v2.svg Wikipedia
l'enciclopedia libera
Notification-icon-Wikidata-logo.svg Wikidata
il più grande database collaborativo di dati strutturati
MediaWiki-2020-icon.svg MediaWiki.org
sito di documentazione del software che mantiene online Wikipedia
Wikimedia Phabricator logo inv.svg Wikimedia Phabricator
bug tracker collaborativo
in breve l'account Wikimedia Community dà accesso a 850+ progetti in 220+ lingue
Wikitech-2020-icon.svg

Wikitech fornisce un account separato, per accedere a strumenti tecnici ad accesso riservato, fra cui:

GitLab icon.svg Wikimedia GitLab
code hosting con git
Wikimedia Cloud Services logo.svg Wikimedia Cloud services
server virtuali (VPS) su OpenStack (PaaS)
OpenStack® Logo 2016 icon square.svg Wikimedia Horizon
pannello OpenStack
Toolforge logo.svg 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 Logo optimized.svg Wikimedia community · login / registrazione

Nome utente suggerito: NomeCognome-WMIT

Wikimedia Phabricator logo inv.svg Wikimedia Phabricator · login

Usare il pulsante Log in MediaWiki e inserire le stesse credenziali Wikimedia Community Logo optimized.svg globali Wikimedia.

Puoi effettuare delle prove facendo una modifica in questo Task pubblico creato appositamente per permetterti di fare alcuni test:

Font Awesome 5 solid anchor.svg T335567

Le persone tecniche del team dovranno anche creare credenziali Wikitech-2020-icon.svg Wikitech per accedere ad esempio a GitLab icon.svg Wikimedia GitLab:

Per tutte le utenze avanzate:

Wikitech-2020-icon.svg Wikitech · login / registrazione

Nome utente suggerito: NomeCognome-WMIT
Nome utente shell suggerito: nomecognome-wmit

GitLab icon.svg Wikimedia GitLab · login

Inserire le stesse credenziali Wikitech-2020-icon.svg Wikitech.

A questo punto potrebbe essere necessario farsi approvare l'account di Wikimedia GitLab. Per farselo approvare velocemente, far compilare questo modulo:

Font Awesome 5 solid anchor.svg https://phabricator.wikimedia.org/project/profile/6554/

Per vedere se le tue credenziali funzionano, è tradizione mettere una Star a questo progetto:

GitLab icon.svg wikimedia-it/wmit-infrastructure

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
7.4
https://packages.debian.org/stable/php
Composer 2.5
2.0
https://packages.debian.org/stable/composer
MariaDB 10.11
10.5
https://packages.debian.org/stable/mariadb-server
NodeJS 18.13
12.22
https://packages.debian.org/stable/nodejs
npm 9.2
7.5
https://packages.debian.org/stable/npm
Python 3.11
3.9
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:

  1. Wikimedia Community Logo optimized.svg https://meta.wikimedia.org/
    Fare login. Visitare la propria pagina utente
    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 link da inserire: 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:DarioCrespi-WMIT
    5. (per chi sviluppa software) inserire un link a Wikimedia GitLab
      Esempio link da inserire: https://gitlab.wikimedia.org/ferdi2005
  2. Wikitech-2020-icon.svg 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)
  4. assicurarsi di avere una utenza in https://wiki.wikimedia.it/ (se non si ha una utenza in questo wiki, richiederla scrivendo ad info(chiocciola)wikimedia.it oppure Contatti)
    1. verificare che in questa categoria sia elencato il proprio progetto:
      Categoria:Servizi e rispettivi livelli di accesso
    2. visita questo link: Special:MyPage
      verificare che la propria pagina utente abbia qualche template di {{Accesso}} per descrivere i propri livelli di accesso (e in caso di dubbi: Contatti)

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]

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:

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

Domini

Se desideri registrare un nuovo dominio o modificarne uno già esistente, segui la procedura in:

Server DNS

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:

  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: tech(chiocciola)wikimedia.it
  3. eventualmente, comunica l'elenco delle informazioni personali che si ritiene debbano essere rimosse da Wikimedia Italia, contattando la segreteria (Contatti):
    To: segreteria(chiocciola)wikimedia.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:

tech(chiocciola)wikimedia.it

Note