README.md 7.45 KB
Newer Older
lucha's avatar
lucha committed
1
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.
lucha's avatar
lucha committed
2

3
4
5
# Set-up preliminare

## Installare composer
lucha's avatar
lucha committed
6

lucha's avatar
lucha committed
7
Per interagire con la configurazione di
lucha's avatar
lucha committed
8

9
10
* Instalare composer e impostare il repository

11
(richiede una versione di PHP moderna)
12
13
14
15

``` shell
apt install composer
```
ale's avatar
ale committed
16

lucha's avatar
lucha committed
17
18
La versione 1.10.1 sembra funzionare con le nostre impostazioni, qualcuno ha avuto problemi con la 1.8. È uscita la 2.0 ma non abbiamo fatto test al riguardo.

19
20
21
Io ho dovuto installare alcune librerie php extra

``` shell
samba's avatar
samba committed
22
apt install php-xml php-zip php-curl
23
```
lucha's avatar
lucha committed
24
25
26
27
28
29
30
31
32

Se non avete la versione di composer giusta (per esempio, in Debian Buster non è
sufficientemente recente), si può usare Docker per eseguire la versione giusta, per esempio con:

```shell
docker run --rm --volume $PWD:/data --workdir /data composer:1.10 composer [....]
```
Se sequite questa strada, tutti i comandi descritti qui sotto vanno lanciati in questo modo (invece che chiamando composer direttamente).

lucha's avatar
lucha committed
33
## Set up dell'autenticazione
lucha's avatar
lucha committed
34

ale's avatar
ale committed
35
36
37
38
39
Siccome alcune dipendenze sono al momento in repository privati,
composer ha bisogno di autenticarsi con git.autistici.org. Per fare
ciò bisogna ottenere un *token di autenticazione* (da dentro Gitlab,
User Settings > Access Tokens, selezionare *read_api*), e poi dare il
comando:
40
41

```shell
ale's avatar
ale committed
42
composer config gitlab-token.git.autistici.org $PERSONAL_ACCESS_TOKEN
43
```
ale's avatar
ale committed
44
45
46
47
Questo comando creerà un file *auth.json* con il token: questo file
verrà ignorato da git perché non va assolutamente committato nel
repository.

lucha's avatar
lucha committed
48
# Come funziona composer
lucha's avatar
lucha committed
49

lucha's avatar
lucha committed
50
51
52
53
54
55
56
57
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
58
  * I plugins drop-in, tipo hyperdb/ludicrousdb
lucha's avatar
lucha committed
59
60
61
62
63
64
65
  * 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
66
67
composer update
```
lucha's avatar
lucha committed
68
69
70
71
72
73
74
75
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.
76

lucha's avatar
lucha committed
77
78
79
80
81
## Come aggiungere una nuova dipendenza
Con il comando
```shell
composer require nome/della-dipendenza
```
82

lucha's avatar
lucha committed
83
## Da dove prendiamo le dipendenze
84

lucha's avatar
lucha committed
85
Composer installerà le dipendenze da quattro fonti diverse (fondamentalmente):
86

lucha's avatar
lucha committed
87
88
89
- 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```
lucha's avatar
typo    
lucha committed
90
  * i plugin sono sotto ```wpackagist-plugin/nomeplugin```
lucha's avatar
lucha committed
91
92
93
- 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).
94
95


lucha's avatar
lucha committed
96
## La gestione delle patch
97

lucha's avatar
lucha committed
98
99
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```.
100

lucha's avatar
lucha committed
101
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```.
102

lucha's avatar
lucha committed
103
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:
lucha's avatar
lucha committed
104
```shell
lucha's avatar
lucha committed
105
composer update nothing
lucha's avatar
lucha committed
106
107
```

108
# Struttura delle directory generate
109

110
- una directory ```app/``` dove troveremo tutto il codice che dovrà andare dentro il container
lucha's avatar
lucha committed
111
- una directory ```vendor/``` dove verranno spacchettate alcune dipendenze di composer di cui non abbiamo bisogno in produzione per eseguire Noblogs
112

lucha's avatar
lucha committed
113
114
115
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.
116

117

lucha's avatar
lucha committed
118
119
120
## 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
lucha's avatar
lucha committed
121
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```. 
blallo's avatar
blallo committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

## Creare un container di sviluppo

Si può creare un container per lo sviluppo in locale con docker

```bash
docker build \
    --build-arg=uid=$(id -u) \
    --build-arg=gid=$(id -g) \
    -f Dockerfile.dev \
    -t registry.git.autistici.org/noblogs/noblogs-composer-dev \
    .
```

Per lo sviluppo poi

```
docker run \
    --rm \
    -v $PWD:$PWD \
    -w $PWD \
    -ti registry.git.autistici.org/noblogs/noblogs-composer-dev:latest 
```