Passa al contenuto principale

Registro del Debito Tecnico

"Il debito nascosto corrompe la fiducia. Il debito dichiarato è ingegneria."

Questa pagina è l'elenco pubblico e deliberato delle capacità che Zenzic ha scelto di non rilasciare nella v0.7.0 "Quartz Maturity" — e il ragionamento ingegneristico che rende ogni rinvio una scelta progettuale consapevole, non una dimenticanza.

La posizione di Zenzic: un progetto che esegue il linting della documentazione altrui deve mantenere uno standard più elevato di onestà sulla propria evoluzione. Ogni voce qui sotto nomina ciò che manca, perché è stato rinviato e quale sprint si fa carico del seguito.

Voci Aperte (v0.7.0 → v0.8.0)​

Z108 STALE_ALLOWLIST_ENTRY​

Categoria: Igiene della configurazione Stato: Rinviato a v0.8.0 "Basalt" Tracciato: GitHub issue (milestone v0.8.0) Correlato: ADR 011: Cross-Instance Allowlist

Cosa è stato rinviato​

Un controllo che avvisa quando un prefisso dichiarato in [link_validation] absolute_path_allowlist non viene mai effettivamente referenziato da alcun link nel progetto — ovvero la voce di allowlist è diventata obsoleta e può essere rimossa in sicurezza.

Perché lo abbiamo rinviato​

Il controllo è concettualmente semplice ma architetturalmente costoso:

  1. Violazione del Pillar 3. Z907 e Z105 sono funzioni pure per-link / per-file — decidono indipendentemente in ogni worker pytest-xdist senza stato condiviso. Una determinazione di "usato / non usato" richiede l'aggregazione dei risultati su tutti i file scansionati in tutti i worker, con riconciliazione finale. Introdurre stato aggregato nel pass del validator forzerebbe un ridisegno del Pillar 3 in una release il cui obiettivo dichiarato è consolidamento, non refactor.
  2. Categoria sbagliata. Eseguire il lint del contenuto della documentazione e il lint della configurazione del linter stesso sono spazi problematici differenti. Mescolarli amplia la portata del validator e oscura quali rilevamenti riguardano contenuto utente vs. setup di progetto.
  3. Segnale YAGNI assente. Non esistono ancora segnalazioni reali di voci di allowlist obsolete. La v0.7.0 è la prima release che possiede la funzionalità in assoluto. Aggiungere un controllo di igiene per un problema mai osservato sarebbe prematuro.

Cosa faremo nella v0.8.0​

La sede naturale di questo controllo è un comando separato — nome proposto zenzic inspect config — che audita i file di configurazione end-to-end: voci di allowlist non referenziate, pattern excluded_dirs contraddittori, chiavi deprecate, ecc. Questo separa il lint dei contenuti (pass del validator) dall'audit della configurazione (pass dell'inspector) e mantiene puri entrambi i pass.

Mitigazione nella v0.7.0​

zenzic.toml è piccolo, versionato e revisionato in code-review ad ogni PR. Una voce di allowlist obsoleta è una preoccupazione di code-review nella v0.7.0, promossa a preoccupazione di tooling nella v0.8.0. La finestra di rischio è limitata: una voce obsoleta può al massimo silenziare un rilevamento Z105 legittimo per un prefisso che non necessita più di essere silenziato — non può creare falsi positivi, far trapelare dati o indebolire alcun controllo di sicurezza.

Voci Chiuse​

Questa sezione accumulerà voci man mano che gli elementi rinviati vengono rilasciati. Ogni voce chiusa nominerà la versione che l'ha risolta e collegherà la PR mergiata.

(nessuna ancora — la v0.7.0 è la prima release con un Registro del Debito Tecnico pubblico.)

Perché esiste questa pagina​

Il primo invariante di Zenzic è la Trasparenza. Un linter che nasconde le proprie carenze non è affidabile: ogni progetto che adotta Zenzic dovrebbe poter leggere questo registro e giudicare da sé se il lavoro rinviato è rilevante per il proprio caso d'uso.

Tre impegni governano questa pagina:

  1. Ogni rinvio viene nominato. Nessun backlog silenzioso. Se abbiamo scelto di non rilasciare una capacità discussa in modo significativo durante uno sprint, finisce qui.
  2. Ogni rinvio ha una ragione. "Abbiamo finito il tempo" è accettabile se vero; vaghi giri di parole no. La ragione deve essere sufficientemente specifica perché un futuro contributor possa decidere se il vincolo è ancora valido.
  3. Ogni rinvio ha un proprietario. Uno sprint target, una release target, oppure un esplicito "rinviato a tempo indeterminato" con relativa motivazione. Le voci del registro senza proprietario decadono in folklore.

Quando contribuisci un rinvio qui, non stai ammettendo una debolezza — stai proteggendo il prossimo contributor dal riscoprire lo stesso compromesso.