From 62b4bc19adca953a43532f8a691b3e63156c886c Mon Sep 17 00:00:00 2001
From: lucha <lucha@paranoici.org>
Date: Sat, 23 May 2020 17:53:01 -0700
Subject: [PATCH] added (italian) explanation of repository and its use

---
 README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 60 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 9a14d891..2c294ae8 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,66 @@
-This is an attempt to re-structure the ai/noblogs-wp> repository using Composer ([e.g](https://www.smashingmagazine.com/2019/03/composer-wordpress/))
+This is an attempt to re-structure the ai/noblogs-wp> repository using Composer
 
-Some rough ideas on how the situation could be improved:
+# Problemi configurazione attuale di ai/noblogs-wp>
 
-- the ```upstream``` branch should disappear. We should not have to care ourselves on keeping a sync of Wordpress source code
-- we should really just keep the patches and our contributions
-- we need to be able to build a docker container in the end
-- How do we generate the patches? We need to keep the source code of wordpress in the git repo after all, to be able to use git diff.
+- 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```
 
-## About mu-plugins and drop-in plugins
+# Proposta:
 
-Drop-in plugins, such as ```Hyperdb```, do not have to be installed in the plugins directory, but we have instead to place files directly into wp-content.
-Similarly, mu-plugins are distributed as regular plugins (```wpackagist``` does not have a nice way to select stuff as mu-plugins), but they cannot be dropped in the mu-plugins directory: instead, a single file from their source has to be moved there.
+Usiamo Composer  ([e.g](https://www.smashingmagazine.com/2019/03/composer-wordpress/)), un gestore di dipendenze per PHP.
 
-In order to solve this two problems, we install these plugins outside of the ```app``` sub-directory (since we do not need to distribute them in production), and we manually specify which file we need to move where, using ```dropin-paths```.
+## Come testare questo repository
 
-## Gitlab as Composer registry/repository
-It might happen [soon](https://gitlab.com/gitlab-org/gitlab/-/issues/15886), in Gitlab version 13.1.
+* Instalare composer (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
+```
+* 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```.
+
+# 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).
-- 
GitLab