This is an attempt to re-structure the ai/noblogs-wp> repository using Composer
This is the codebase of Noblogs (previously in ai/noblogs-wp> ) managed via Composer ([e.g](https://www.smashingmagazine.com/2019/03/composer-wordpress/)), a PHP dependency manager.
# Problemi configurazione attuale di ai/noblogs-wp>
# Installare composer
- 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](https://www.smashingmagazine.com/2019/03/composer-wordpress/)), un gestore di dipendenze per PHP.
## Come testare questo repository
Per interagire con la configurazione di
* Instalare composer e impostare il repository
...
...
@@ -26,118 +16,78 @@ Io ho dovuto installare alcune librerie php extra
``` shell
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/```.
# Come funziona composer
* Per aggiornare le dipendenze di noblogs, il comando da usare è
``` shell
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.
In particolare ci sono 2 file importanti:
-```composer.json``` è un file JSON che contiene la "ricetta" di come costruire il codice di Noblogs. Questo vuol dire che contiene informazioni sulle *dipendenze* di Noblogs, quali:
* 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
più le informazioni su dove installare tutte queste cose. Si può modificare sia a mano che usando composer.
-```composer.lock``` è la versione *"compilata"* dello stesso file, ovvero dopo che composer ha controllato che la ricetta in ```composer.json``` sia effettivamente installabile.
Una volta che modifichiamo ```composer.json``` (a mano o con altri metodi), per aggiornare ```composer.lock``` bisogna lanciare il comando
```shell
composer update
```
Questo comando aggiornerà anche tutte le dipendenze alla versione più recente disponibile, a meno che non abbiamo forzato una dipendenza ad una versione specifica.
Il codice verrà scompattato nella directory ```app/``` con dentro una copia del sorgente di Noblogs, e viene aggiornato il file ```composer.lock```. A quel punto possiamo committare le modifiche a ```composer.json``` e ```composer.lock```.
Per creare il repository docker per test e produzione invece lanceremo il comando
```shell
composer install
```
che legge solo il file ```composer.lock```. Per cui se aggiorniamo ```composer.json``` ma non lanciamo il comando ```composer update``` e committiamo i cambiamenti risultanti in ```composer.lock```, le modifiche non verranno mai eseguite nella fase di build delle immagini docker.
## 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
## Come aggiungere una nuova dipendenza
Con il comando
```shell
composer require nome/della-dipendenza
```
* 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
## Da dove prendiamo le dipendenze
## Codice nostro
Composer installerà le dipendenze da quattro fonti diverse (fondamentalmente):
Il codice che abbiamo scritto noi, per esempio [r2db](lucha/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](https://gitlab.com/gitlab-org/gitlab/-/issues/15886)) ci potrebbe essere in Gitlab una specie di registry tipo-docker, quindi questa cosa dovrebbe essere ancora più semplice
- Il repository di Composer https://packagist.org/
- Un repository che fa da mirror a Wordpress.org https://wpackagist.org/ Per cui per installare temi/plugin che sono disponibili su worpdress.org basta aggiungerli come dipendenze con la sequente convenzione
* i temi sono sotto ```wpackagist-theme/nometema```
* i plugin sono sotto ```wpackagist-plugin/nometema```
- Un repository per assett e librerie in javascript: https://asset-packagist.org/
- Il codice scritto da noi (temi e plugin) si trova nel gruppo @noblogs. Viene tutto rilasciato come pacchetti Composer sul Registry di GitLab. Se si vuole creare un nuovo pacchetto/dipendenza, basta seguire le istruzioni in 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).
## 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```.
## La gestione delle patch
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.
A volte vogliamo patchare codice presente su uno dei tre repository non gestiti da noi (dato che quello nel reposiroty gestito da noi possiamo direttamente modificarlo).
Questa cosa si gestisce con una serie di file di patch, in ```patches```.
Alla fine di questo mestiere, si dovrebbe avere una base di codice essenzialmente equivalente a quella che c'è nel branch ```noblogs```.
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 aggiunte manualmente in ```composer.patch.json```.
Per ri-applicare tutte the patches senza aggiornare le dipendenze (per fare prima), si può usare
Se si aggiunge una patch e si vuole che questa ultima venga inclusa in ```composer.lock``` ma senza aggiornare le altre dipendenze, si può usare il comando:
```shell
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 ```vendor/``` dove verranno spacchettate alcune dipendenze di composer di cui non abbiamo bisogno in produzione per eseguire Noblogs
- 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/```
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 non è un problema se ogni volta ri-creiamo la directory ```app/``` da zero.
In altre parole, se ne teniamo una copia in locale per comodità, questa verrà svuotata nel caso di un aggiornamento a wordpress-core.
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
``` shell
composer update
```
## Aggiungere componenti
Per aggiungere un nuovo tema/plugin dal repository wpackagist, si usa
``` shell
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
``` shell
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
``` shell
git diff >> patches/nomepatch.patch
```
ricordandosi che ogni file di patch può modificare solo un singolo tema/plugin.
# TODO
## Plugins mancanti
Plugin non ancora aggiunti: vedi #9
## Temi non trovati su wpackagist
Temi che attualmente sono nel repository di noblogs-wp ma non si trovano su wpackagist: vedi #1
il repository ```wpackagist``` categorizza tutti come ```wordpress-plugin```. Bisogna quindi elencarli manualmente nell'elenco dei ```drop-in``` (vedi il file ```composer.json```). Simile la situazione dei plugin dropin, tipo ```hyperdb``` e ```r2db```, dove dobbiamo specificare a mano cosa fa messo dove.b```.
