README.md

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](https://www.smashingmagazine.com/2019/03/composer-wordpress/)), un gestore di dipendenze per PHP.

## Come testare questo repository

* Instalare composer e impostare il repository

(richiede una versione di PHP moderna, io su Ubuntu sto usando la 7.2)

``` shell
apt install composer
```
Io ho dovuto installare alcune librerie php extra

``` shell
apt install php7.2-xml php7.2zip
```
Il codice scritto da noi (temi e plugin) si trova nel gruppo @noblogs. Viene tutto rilasciato come pacchetti Composer sul Registry di GitLab.
Per poter accederci, bisogna configurare un (https://git.autistici.org/help/user/profile/personal_access_tokens.md)[personal access token] con i permessi di ```api```.
Una volta fatto, bisogna lanciare
``` shell
composer config http-basic.gitlab.com ___token___ <ACCESS_TOKEN>
```
dove ```<ACCESS_TOKEN>``` è il nostro token personale. A quel punto composer crea un file ```auth.json``` nel repo, che è vostro personale e non va mai committato (è già in ```.gitignore```).

* Per aggiornare le dipendenze di noblogs, il comando da usare è 
``` shell
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

## 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 ```wp-content/mu-plugins```. Quindi installiamo il sorgente fuori dalla directory che esporteremo (ovvero ```web```), in una directory apposta, chiamata ```wp-plugins-src```. 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```. Siccome il meccanismo è simile, li gestisco allo stesso modo dei mu-plugins.

## Codice nostro

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

## 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
```shell
composer update nothing
```

# Struttura delle directory di Wordpress

Composer non è contento di spacchettare due dipendenze nella stessa directory. Quindi separa wordpress-core in ```app/wp```, mentre c'è un ```app/wp-content``` dove vengono spachettati i vari temi/plugins/etc. Bisognerà fare dei magheggi per riscrivere le URL. [Vedi qui](https://www.smashingmagazine.com/2019/03/composer-wordpress/) e [qui](https://roots.io/docs/bedrock/master/server-configuration/#apache-configuration-for-bedrock).

# Come dovrebbe funzionare a regime

Una volta finita la attuale transizione, questo repository dovrebbe funzionare come segue. I contenuti della directory ```app``` (e anche ```mu-plugins-src```) devono essere generati da ```composer```.  Quindi eventuali modifiche non vanno committate. 

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

* ```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
* ```.htaccess```: anche lui, sta qui o sta in noblogs-docker?
* Cosa fanno i commit e01b38062c619d3c95d88486e27ee383d42e7002, 
6cecf525477f01faa458b7925ead388f7415d030 e 70c22128a3f9fea7793c4dac189280d652fd54f1 esattamente?
 


## Plugins mancanti

Plugin non ancora aggiunti:

- nospam (nostro)
- wordpress-ai-privacy-plugin
- wp-recaptcha-bp (da rimuovere assieme a buddypress?)
- eu-compliance (non trovato)
- wp-footnotes (plugin abbandonato)

## Temi non trovati su wpackagist

Temi che attualmente sono nel repository di noblogs-wp ma non si trovano su wpackagist

- ai-buddytheme (ovviamente)
- boumatic
- bp-default
- clean-home
- copyblogger
- critical
- desk-mess
- flipflop
- fusion (forse fusion-base e fusion-blog?)
- grid_focus
- hybrid-news
- leviathan
- life-collage
- modernity
- monochrome-pro
- monotone
- neoclassical
- noblogs-home (ovviamente)
- old-school
- pixeled
- ```seo_october_special```
- structure (forse structure-lite?)
- twentynineteen-child
- twentytwenty-child
- uchilla1.0
- vigilance
- web2zen
- zenlite-black-mandarin