Ambiente, versione, dati di partenza

In parole semplici

Un bug raccontato senza ambiente è un fantasma. Stesso codice, stesso click, due esiti diversi: la differenza vive in ciò che non hai annotato. Questa lezione ti dà la lista delle cose che vanno scritte sempre, anche quando sembrano ovvie.

Parole nuove

• ambiente: combinazione di sistema operativo, runtime, dipendenze e configurazioni.
• versione: identificativo univoco del codice (numero release, commit SHA, tag).
• dati di partenza: contenuto del database, file, cache, session storage al momento dell’errore.
• scheda ambiente: documento sintetico con tutte le informazioni di contesto.

Cosa impari

• Sapere cosa annotare anche quando hai fretta.
• Confrontare due postazioni con esito diverso e ridurre la differenza al minimo significativo.
• Riconoscere quando l’ambiente è la causa, non lo sfondo.

La scheda ambiente minima

SISTEMA OPERATIVO:
- nome e versione (es. macOS 14.4, Windows 11 23H2, Ubuntu 22.04)

BROWSER (se applicabile):
- nome, versione (es. Chrome 124.0.6367.78)
- estensioni attive che potrebbero interferire

RUNTIME (Node, Python, JVM, ...):
- nome e versione esatta

APPLICAZIONE:
- versione release (es. 2.3.1)
- commit SHA (es. a1b2c3d)
- branch attivo (es. main, develop)

DIPENDENZE:
- contenuto rilevante di package.json/lock, requirements.txt, ...

CONFIGURAZIONE:
- variabili d'ambiente significative (senza segreti)
- feature flag attivi
- locale (it-IT, en-US), fuso orario

DATI DI PARTENZA:
- account/utente (ruolo, non email reale)
- record significativi (id, stato)
- cache, storage, cookie pertinenti

RETE:
- VPN? proxy? throttling?

Sembra tanto. Una volta scritto, lo si copia.

Differenze “utili” e differenze rumorose

Quando confronti due postazioni con esito diverso, distingui:

• Differenze utili: cambiano l’esito. Esempio: una con browser v124, l’altra v118; una con feature flag ON, l’altra OFF.
• Differenze rumorose: non cambiano l’esito ma riempiono il documento. Esempio: una ha Spotify aperto e l’altra no.

Domanda di controllo: “se cambio questa, il bug si comporta diversamente?”. Se no, è rumore.

Esempio reale di confronto

Postazione A (bug si vede):

macOS 14.4, Safari 17.4
Node 20.11.0
app 2.3.1 (commit a1b2c3)
locale it-IT, fuso Europe/Rome
account ruolo "manager"

Postazione B (bug NON si vede):

macOS 14.4, Safari 17.4
Node 20.11.0
app 2.3.1 (commit a1b2c3)
locale en-US, fuso America/New_York
account ruolo "manager"

Unica differenza: locale + fuso orario. Ipotesi naturale: il bug dipende dal locale o dal fuso. Ora puoi verificarla cambiando una variabile alla volta.

Cosa NON va nella scheda ambiente

• Password, token, dati personali. Mai. Nemmeno “solo per noi”.
• Screenshot con dati reali di clienti. Sostituisci con dati di test.
• Configurazioni che non c’entrano. La cronologia del browser non serve.

Esercizio guidato

1. Apri DevTools del tuo browser → tab Console.
2. Esegui:

console.log({
  ua: navigator.userAgent,
  lang: navigator.language,
  tz: Intl.DateTimeFormat().resolvedOptions().timeZone,
});

3. Da terminale:

node --version
git rev-parse --short HEAD

4. Componi una scheda ambiente completa per la tua postazione attuale e salvala in laboratorio-debug/01-riprodurre/postazione-A.md.

5. Chiedi a un compagno (o esegui sullo stesso PC con browser diverso) la stessa cosa: salva come postazione-B.md. Annota le differenze utili e quelle rumorose.

Il principio sottostante

Quando due postazioni si comportano in modo diverso, la causa vive nella loro differenza minima. Riducila finché non resta una sola variabile.

Errori frequenti del principiante

• “Tanto l’ambiente è lo stesso”. Quasi mai. Versioni, locale, fuso, flag e cache divergono in silenzio.
• Copiare lo user agent senza leggerlo. Lo user agent dice il browser, ma anche il sistema operativo e a volte la versione minore.
• Includere segreti. Se finisce in una issue pubblica, lo legge tutto internet.
• Trattare l’ambiente come “sfondo”. A volte è il protagonista del bug.