Sviluppo software

Questa pagina è una bozza.

Pagina rivolta alle persone incaricate da Wikimedia Italia per nuovi sviluppi software.

Nota: il responsabile del tuo progetto per Wikimedia Italia potrebbe aver comunicato eventuali variazioni a questo documento, e fanno fede quelle variazioni, soprattutto se espresse nel tuo contratto di incarico.

Variazioni non minori a questo documento sono concordate con la commissione Tech.

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 personali o aziendali. Scoraggiamo queste pratiche perché Wikimedia Foundation fornisce già un'infrastruttura sufficientemente strutturata e moderna per evitare frammentazione, costi, complessità, gatekeeping, nonché fornisce una gestione delle utenze più efficace e quindi una collaborazione più efficiente.

In breve l'infrastruttura di Wikimedia Foundation è basata su OpenStack e Kubernetes. Rispettivamente:

• per server virtuali si usa Wikimedia Cloud VPS (OpenStack)
• per hosting condivisi si usa Wikimedia Toolforge (Kubernetes)

Ulteriori informazioni:

https://wikitech.wikimedia.org/wiki/Main_Page

Termini d'uso

Per la gestione delle risorse hardware di Wikimedia Foundation si accettano i termini d'uso. La violazione può causare l'interruzione del servizio.

https://foundation.wikimedia.org/wiki/Terms_of_Use/it

Tempo di lettura: 15 minuti.

Procedura di inizio incarico

Per ogni persona del team di sviluppo che dovrà seguire la prima installazione e la manutenzione ordinaria dell'applicativo (almeno fino al termine del proprio incarico):

1. avere un account su Meta-wiki (per presentarsi alla community)

   Registrazione: m:Special:CreateAccount

   1. comunicare il proprio nickname
2. avere un account sviluppatore Wikimedia (per entrare nei server)

   Istruzioni: m:wikitech:Help:Create a Wikimedia developer account

3. avere un account in Wikimedia Phabricator (per poter comunicare il proprio lavoro)

   https://phabricator.wikimedia.org/

Ogni membro cura la propria #Documentazione del team.

Documentazione del team

Per ogni membro del team, per ogni loro account Wikimedia, fino al termine dell'incarico:

1. tenere aggiornata la propria pagina utente pubblica sui progetti Wikimedia

Checklist della propria pagina utente:

1. https://meta.wikimedia.org/
   1. presenza delle informazioni sul proprio ruolo e sul proprio incarico (sono pagato per occuparmi di ... nel periodo ...) in inglese
   2. menzione del proprio nickname Wikimedia Phabricator
   3. menzione del proprio nickname WikiTech
2. https://phabricator.wikimedia.org/
   1. presenza di un link alla propria pagina Meta-wiki
3. https://wikitech.wikimedia.org/
   1. presenza di un link alla propria pagina Meta-wiki
   2. menzione del proprio nickname Wikimedia GitLab
4. https://gitlab.wikimedia.org/
   1. presenza di un link alla propria pagina Meta-wiki

Requisiti progettuali

Sistema operativo

Debian GNU/Linux stable.

Repository Debian

main

Il software sviluppato deve essere il più possibile compatibile con il parco software già presente in Debian GNU/Linux stable 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. Grazie per la collaborazione.

Qui puoi verificare qual è l'esatta versione da dover supportare:

• https://packages.debian.org/stable/php
• https://packages.debian.org/stable/composer
• https://packages.debian.org/stable/mariadb-server
• https://packages.debian.org/stable/nodejs
• https://packages.debian.org/stable/npm
• https://packages.debian.org/stable/docker

Documentazione sistemistica

Si richiede di fornire una documentazione da consegnare al sistemista GNU/Linux, in lingua inglese, con tono semplice e chiaro.

L'obiettivo è di aiutare una persona potenzialmente esterna a (ri-)creare velocemente un ambiente che ospiti l'applicativo in sicurezza e affidabilità.

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

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

Documentazione sviluppo software

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

L'obiettivo è 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.

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

Informazioni minime da fornire:

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

Documentazione utente

Redarre una documentazione da consegnare agli utenti finali, in lingua italiana o inglese (da chiarire con il responsabile progetto), con tono semplice e chiaro.

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

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

Questa documentazione può essere omessa se l'interfaccia utente è già sufficientemente auto-esplicativa (ad esempio se è presente un wizard, etc.).

Manutenzione ordinaria

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. aggiornando dipendenze PHP)
  • aggiornamenti di sicurezza delle proprie dipendenze software nel sistema operativo (e.g. aggiornando il proprio webserver, server database, etc.)
  • verifica delle procedure di backup sul posto
• comunicazione delle finestre di intervento richieste per la manutenzione ordinaria

Backup

Fino al termine dell'incarico:

• prendersi cura d almeno una singola copia giornaliera dei dati (coerente alla propria documentazione sistemistica di backup)

Licenza

È già scritto nei termini d'uso: non è possibile caricare sui server Wikimedia del materiale non rilasciato dal suo autore con una licenza libera.

Per il proprio nuovo codice, si richiede di adottare una licenza libera ufficialmente approvata dalla Free Software Foundation.

Ad esempio:

• GNU General Public License v3+ (adatta per software generico)
• GNU Affero General Public License v3+ (particolarmente adatta per software lato-server)

Caricare il rispettivo file di licenza nel repository (esempio: LICENSE.md).

Termine incarico

Prima della conclusione dell'incarico o dell'attività del team:

1. il team propone delle date per una presentazione tecnica del progetto, aperta alla community, per favorire il passaggio di consegne. Presentando almeno:
   1. #Documentazione sviluppo software
   2. #Documentazione sistemistica
   3. #Documentazione utente

Prima della conclusione dell'incarico di ogni membro del team:

1. aggiornare la #Documentazione del team (la descrizione delle proprie utenze) per riflettere le variazioni dei propri ruoli

Grazie di cuore!