This is an attempt to re-structure the ai/noblogs-wp> repository using Composer

Problemi configurazione attuale di ai/noblogs-wp>

• fare rebase upstream è oggettivamente macchinoso
• c'è una confusione semantica: i commit di noblogs potrebbero essere patch al codice, ma anche aggiunta/rimozione di plugin scritti da noi, etc.
• non ci sono controlli per evitare di fare un commit che annulla un commit precedente, complicando inutilmente la history
• non ci sono controlli per evitare di fare commit che modificano più temi/plugin/cose alla volta
• non è chiaro capire dalla history quando qualcuno ha aggiornato upstream

Proposta:

Usiamo Composer (e.g), un gestore di dipendenze per PHP.

Come testare questo repository

• Instalare composer e impostare il repository

(richiede una versione di PHP moderna)

apt install composer

Io ho dovuto installare alcune librerie php extra

apt install php-xml php-zip

Il codice scritto da noi (temi e plugin) si trova nel gruppo @noblogs. Viene tutto rilasciato come pacchetti Composer sul Registry di GitLab.

In questo repository ci sono solo le patch ed i file di configuarazione di composer (al momento, ~8Mb). Il codice vero e proprio di noblogs (l'equivalente di ai/noblogs-wp> per intenderci) abbiamo deciso che non verrà mantenuto in git, dato che viene generato da composer a partire da questo repository. Lanciando composer install dovrebbe venire tutto generato nella directory app/.

• Per aggiornare le dipendenze di noblogs, il comando da usare è

composer update

Cosa fa composer

Nel repository c'è un file JSON chiamato composer.json, che descrive le dipendenze di Noblogs, più da una certa configurazione alla struttura del suo repository. In questo senso le dipendenze possono essere

• La release di Wordpress core
• Temi e plugins (e i mu-plugins)
• I language pack
• I plugins drop-in, tipo hyperdb
• Codice che abbiamo scritto noi, r2db, etc.
• Le patch che abbiamo deciso di applicare ai sorgenti upstream

Codice nostro

Il codice che abbiamo scritto noi, per esempio r2db, dovrebbe essere separato da questo repository e messo nel suo proprio repository. Poi possiamo importare questi repository come dipendenze, dichiarando un repository ```vcs`` in composer.json. In futuro (in teoria la versione di Gitlab 13.1) ci potrebbe essere in Gitlab una specie di registry tipo-docker, quindi questa cosa dovrebbe essere ancora più semplice

Le nostre patch

Poi ci sono quelle che sono realmente le nostre patch al codice sorgente non-nostro. Quelle si gestiscono con una serie di file di patch, in patches. Vige la regola che una patch agisce solo su una dipendenza "unica", quindi non si possono cambiare tutti i footer di tutti i temi in una sola patch, per esempio. L'idea è avere unità di patch piccole e abbastanza semplici da leggere. Le patch vanno attivate in composer.patch.json.

In patches/ c'è una lista di patch generata da git format-patch, estraendo tutti i nostri commit di ai/noblogs-wp>. Ho escluso i commit che aggiungono/tolgono plugi, temi, lingue, etc. Bisogna fare un lavoro di revisione, capire quali vanno tenute e quali eliminate, e poi attivare quelle rimaste per la dipendenza corrispondente.

Alla fine di questo mestiere, si dovrebbe avere una base di codice essenzialmente equivalente a quella che c'è nel branch noblogs.

Per ri-applicare tutte the patches senza aggiornare le dipendenze (per fare prima), si può usare

composer update nothing

Struttura delle directory generate

Composer quando aggiorna un pacchetto, rimuove tutti i file che trova nella directory dove deve essere spacchettato, prima di mettere quelli nuovi (di modo che non rimangano file "vecchi"). Questo vuol dire che se si aggiorna wordpress-core dopo aver installato temi e pacchetti, questi ultimi vengono rimossi, a meno che non siano stati installati in una directory separata.

Mi sembra che di suo composer segua l'ordine dei requirement nel file json nell'ordine in cui sono scritti, per cui forse non è un problema. L'alternativa, sicuramente più "stabile", è separare le directory in questo modo:

• una directory app/ dove troveremo tutto il codice che dovrà andare dentro il container
• una directory vendor/ dove verranno spacchettate alcune dipendenze di cui però solo alcuni file vengono copiati, tramite il meccanismo dei drop-in, dentro app/. I drop-in non cancellano nessun file quindi non abbiamo problema a mandare più cose dentro la stessa destinazione.

A sua volta app/ è strutturata così:

• una directory app/wp-core dove viene spacchettato il codice di wordpress core
• una directory app/wp-root che sarà la root di wordpress dove mettere tutto il resto

In particolare dentro app/wp-root avremo

• una directory wp-content separata dove spacchettare temi, plugin, traduzioni
• una directory wp-includes separta dove mettere alcune librerie js
• ci sono inoltre dei file "spuri", principalmente di r2db e hyperdb, che vanno messi in giro. Questi al momento sono:
  • db.php e advanced-cache.php che vanno in app/wp-root/wp-content
  • db-config.php, r2db/, wp-nginx-map-json.php e wp-nginx-map.php che devono stare nella root di wordpress, quindi li mettiamo direttamente in app/wp-root/

Al momento di creare il container, ci dobbiamo ricordare che i contenuti di app/wp-core vanno copiati dentro app/wp-root, e che questa è l'unica directory che va tenuta dentro il container.

mu-plugins (must-use plugins) e dropin

Questo due tipi di plugin sono un po' buffi: i mu-plugins sono distribuiti come i plugin normali, e purtroppo il repository wpackagist categorizza tutti come wordpress-plugin. Ma in realtà bisogna solo spostare un file (il cui nome non è standardizzato) dentro la cartella app/wp-root/wp-content/mu-plugins. Quindi installiamo il sorgente in una directory apposta, chiamata vendor/. In composer.json dobbiamo sia specificare quali sono questi mu-plugins, e qual'è il file da spostare (con dropin-paths).

I dropin sono simili ma peggio, nel senso che la directory di arrivo è un po' a caso. Il caso specifico è hyperdb.

Come dovrebbe funzionare a regime

Una volta finita la attuale transizione, questo repository dovrebbe funzionare come segue. I contenuti della directory app devono essere generati da composer.

Aggiornamenti

Per aggiornare alla ultima versione di wordpress/plugin/temi, si usa il comando

composer update

Aggiungere componenti

Per aggiungere un nuovo tema/plugin dal repository wpackagist, si usa

composer require wpackagist-[theme|plugin]/[..]

Se invece vogliamo aggiungere un pacchetto scritto da noi, prima dobbiamo farlo diventare un pacchetto composer. Il repository sarebbe bello fosse dentro il gruppo @noblogs (ma forse funziona comunque). Bisogna creare un file composer.json dentro il repository del pacchetto in questione (date un occhio a quelli già presenti per una ispirazione), e poi aggiungere un file .gitlab-ci.yml sequendo queste istruzioni noblogs/composer-publish>. A questo punto ogni volta che pushiamo una nuova tag su gitlab verrà creata una nuova release. Se il repository che includiamo ha delle tag di versione del tipo vX.Y.Z (dove X, Y, Z sono numeri, per esempio "v1.2" o "v4.0.1"), allora composer sa cosa fare (prendere l'ultima versione disponibile di default).

A quel punto possiamo aggiungerlo come una dipendenza qualsiasi con

composer require noblogs/nomepacchetto

Creare patches

TODO: questo non è più vero, dato che app/ non è in git, quindi le patch vanno create usando diff direttamente. Andrebbero scritte delle instruzioni.

Le patch in patches/ si possono generate ed aggiornare usando git. Infatti, possiamo fare delle modifiche in app/ e transformarle in un file patch con

git diff >> patches/nomepatch.patch

ricordandosi che ogni file di patch può modificare solo un singolo tema/plugin.

TODO

• wp-cache.php: su noblogs abbiamo una versione leggermente modificata di wp-cache-config-sample.php presente in wp-super-cache. È una cosa che dobbiamo spostare fuori al livello del container docker, o va in qualche modo tenuta qui dentro?
• tutte le patches di wp-cache, che non ho ancora avuto il coraggio di metterci le mani

Plugins mancanti

Plugin non ancora aggiunti: vedi #9 (closed)

Temi non trovati su wpackagist

Temi che attualmente sono nel repository di noblogs-wp ma non si trovano su wpackagist: vedi #1 (closed)