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

Per quanto compete questo documento, sono necessarie due utenze separate. Una utenza per il tuo account globale e una per l'accesso all'ambiente di sviluppo:

Meta-wiki fornisce un account globale per accedere a strumenti collaborativi ad accesso pubblico, fra cui:

Wikipedia

Wikidata

Mediawiki

Wikimedia Phabricator (bug tracker)

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

Wikimedia GitLab (code hosting)

Wikimedia Cloud services (VPS su OpenStack)

Wikimedia Horizon (OpenStack panel)

Wikimedia Toolforge (hosting condiviso su Kubernetes)

Inizio incarico

Per ogni membro del team di sviluppo.

1. registrare account globale Wikimedia
   1. effettuare il primo accesso in Wikimedia Phabricator

      Usare il pulsante " Log in or Register MediaWiki" ed effettuare il login.

      Vengono richieste le credenziali globali Wikimedia

2. registra account riservato Wikitech
   1. effettuare il primo accesso in Wikimedia GitLab

      Vengono richieste le credenziali Wikitech

Documentazione del team

Ogni membro tiene 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.

Checklist:

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: "Since YYYY-MM-DD I'm paid to work on project ZZZZZ. My specific role is: ) in inglese
   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 progettuali

Questi sono i requisiti progettuali su cui deve basarsi il proprio applicativo:

Sistema operativo

Debian GNU/Linux stable.

Repository Debian

main

Il software sviluppato deve essere 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.

Alcuni esempi di software noti, con la pagina che descrive 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

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, 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 è 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.

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

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)

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)
3. comunica le eventuali informazioni personali che si ritiene debbano essere eliminate