Skip to content
Snippets Groups Projects
README.md 9.91 KiB
Newer Older
  • Learn to ignore specific revisions
  • This is an attempt to re-structure the ai/noblogs-wp> repository using Composer
    
    lucha's avatar
    lucha committed
    
    
    # Problemi configurazione attuale di ai/noblogs-wp>
    
    lucha's avatar
    lucha committed
    
    
    - 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```
    
    Usiamo Composer  ([e.g](https://www.smashingmagazine.com/2019/03/composer-wordpress/)), un gestore di dipendenze per PHP.
    
    lucha's avatar
    lucha committed
    
    
    ## Come testare questo repository
    
    lucha's avatar
    lucha committed
    
    
    * Instalare composer e impostare il repository
    
    
    (richiede una versione di PHP moderna)
    
    
    ``` shell
    apt install composer
    ```
    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/```.
    
    * 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 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. 
    
    # 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
    
    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.
    
    lucha's avatar
    lucha committed
    
    # 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
    
    * I commit e01b38062c619d3c95d88486e27ee383d42e7002, 
    6cecf525477f01faa458b7925ead388f7415d030 e 70c22128a3f9fea7793c4dac189280d652fd54f1 creano dei temi "-child" invece che patchare i temi originali. Volendo potremmo tenere i temi child in repo separati ed installarli come dipendenze, invece che mantenerli come file di patch? (temo che ogni tema dovrebbe avere un suo repository git separato, ma forse questo non è del tutto male?)
    
    
    ## 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