Git e GitHub per lo sviluppo di plugin WordPress

Questo è il secondo articolo di una serie sui fondamenti dello sviluppo di plugin per WordPress. Vedremo come configurare strumenti e workflow – dal controllo di versione ai test automatizzati – per sviluppare plugin con sicurezza.

Che tu stia creando un piccolo plugin di utilità o un’estensione ricca di funzionalità, il controllo di versione non è facoltativo: è la tua rete di sicurezza. Git tiene traccia di ogni modifica, ti permette di sperimentare senza paura e rende possibile la collaborazione in futuro.

Alla fine di questo articolo avrai un repository GitHub pulito e ben strutturato, pronto per il lavoro che verrà.

Prerequisiti: Questo articolo presuppone che Git sia già installato sulla tua macchina. In caso contrario, segui prima la guida ufficiale all’installazione.

Inizializzare il repository del plugin

Ogni plugin inizia con una cartella e un file principale. Creiamoli:

mkdir my-awesome-plugin
cd my-awesome-plugin
git init

Ora crea il file principale del plugin, my-awesome-plugin.php. È il file che WordPress cerca quando carica il plugin:

<?php
/**
 * Plugin Name: My Awesome Plugin
 * Description: A short description of what this plugin does.
 * Version:     0.1.0
 * Author:      Your Name
 * License:     GPL-2.0-or-later
 */

declare(strict_types=1);

Quel commento di intestazione è obbligatorio, è ciò che dice a WordPress che questo file è un plugin. Fatto questo, crea il tuo primo commit:

git add .
git commit -m "Initial commit: plugin bootstrap file"

Il file .gitignore

Non tutto nella directory del plugin appartiene al controllo di versione. Un file .gitignore dice a Git quali file e cartelle ignorare.

Crea un .gitignore nella root del plugin:

# Dipendenze (gestite da Composer e npm)
/vendor/
/node_modules/

# File di ambiente
.env
.env.*

# File del sistema operativo
.DS_Store
Thumbs.db

# Cartelle IDE ed editor
/.idea/
/.vscode/
*.swp

Alcune cose da notare: la directory vendor/ conterrà le dipendenze di Composer – ne parleremo nel prossimo articolo. La cartella node_modules/ diventa rilevante se in seguito aggiungi strumenti di build per JavaScript. Le cartelle dell’IDE sono preferenze personali, non configurazione del progetto, quindi non appartengono al repository.

Suggerimento: GitHub mantiene una raccolta di template .gitignore che possono servire come punto di partenza per vari ambienti.

Strutturare il repository

Una struttura di cartelle chiara aiuta te (e chiunque legga il tuo codice) a trovare le cose rapidamente. Ecco un buon punto di partenza:

my-awesome-plugin/
├── src/              → File sorgente PHP
├── assets/           → CSS, JS, immagini
├── tests/            → File di test (li useremo più avanti)
├── my-awesome-plugin.php  → File principale del plugin
├── composer.json     → Gestione dipendenze (prossimo articolo)
├── .gitignore
└── README.md

La directory src/ è dove vivranno le tue classi PHP, caricate automaticamente tramite Composer. La cartella tests/ è vuota per ora, la metteremo in uso quando arriveremo a PHPUnit più avanti nella serie. La cartella assets/ è lì se ne hai bisogno; non tutti i plugin la richiedono.

Non pensarci troppo. Inizia in modo semplice. La struttura crescerà naturalmente insieme al tuo plugin.

Pubblicare su GitHub

Il tuo codice è tracciato in locale. Ora mettiamolo su GitHub, così sarà salvato, condivisibile e pronto per la collaborazione.

1. Crea un nuovo repository su GitHub. Dagli lo stesso nome dello slug del plugin. Non inizializzarlo con un README (hai già dei file in locale).
2. Collega il repository locale e fai il push:

git remote add origin git@github.com:your-username/my-awesome-plugin.git
git branch -M main
git push -u origin main

Pubblico o privato? Se stai sviluppando un plugin per la community WordPress, “pubblico” è la scelta giusta. Se è un progetto per un cliente o stai solo sperimentando, tienilo privato (potrai sempre cambiare in seguito).

Prenditi un momento per aggiungere un README.md con una breve descrizione del plugin. Su GitHub, questo file è la prima cosa che le persone vedono. Non deve essere elaborato, una o due frasi su cosa fa il plugin e come installarlo sono un buon inizio.

Le basi del branching

Anche se lavori da solo, i branch mantengono il tuo workflow ordinato. L’idea è semplice: main contiene sempre codice stabile e funzionante. Nuove funzionalità e sperimentazioni avvengono in branch separati.

Un workflow minimale si presenta così:

# Crea un branch per una nuova funzionalità
git checkout -b feature/add-settings-page

# Lavora, committa, ripeti
git add .
git commit -m "Add settings page skeleton"

# Quando la funzionalità è pronta, uniscila
git checkout main
git merge feature/add-settings-page

In alternativa, pusha il branch su GitHub e apri una Pull Request. Questo ti dà l’opportunità di rivedere le tue stesse modifiche prima di fare il merge (un’abitudine che ripaga velocemente). Più avanti in questa serie vedremo come usare le GitHub Actions per eseguire controlli automatici su ogni Pull Request.

Non c’è bisogno di modelli di branching elaborati come Git Flow in questa fase. Un semplice approccio main + feature branch è più che sufficiente per la maggior parte dei progetti plugin.

Prossimi passi

Ora hai un repository WordPress su GitHub con controllo di versione, una struttura pulita e impostazioni sensate. Questa è la base su cui costruiremo tutto il resto.

Nel prossimo articolo configureremo Composer (il gestore delle dipendenze PHP) per l’autoloading e i pacchetti di terze parti. Si integra perfettamente con la struttura del repository che abbiamo appena creato.

Prossimo articolo: Configurazione di Composer per lo sviluppo di plugin WordPress →