Convenzioni del changelog
Convenzioni del changelog
Sezione intitolata “Convenzioni del changelog”Questa pagina è il contratto seguito da ogni repository pubblico NextPDF quando registra una modifica e rilascia una versione. È un riferimento alle convenzioni; non dichiara alcun comportamento del pacchetto. Il testo specifico per pacchetto e versione si trova nel CHANGELOG.md di ciascun repository. Questa pagina definisce le regole comuni che rendono il riepilogo del changelog cross-repository coerente e privo di fughe di informazioni.
Conventional Commits 1.0.0
Sezione intitolata “Conventional Commits 1.0.0”L’oggetto di ogni commit segue la forma type(scope): description. Il type è uno tra:
| Tipo | Significato | Rivolto all’utente | Effetto sulla versione |
|---|---|---|---|
feat | Nuova funzionalità | sì | incremento minor |
fix | Correzione di un comportamento | sì | incremento patch |
perf | Miglioramento delle prestazioni senza alcuna modifica del comportamento | sì | incremento patch |
refactor | Ristrutturazione interna, senza modifiche osservabili | no | nessuno |
docs | Solo documentazione | no | nessuno |
test | Solo test | no | nessuno |
build / ci | Solo build o pipeline | no | nessuno |
chore | Manutenzione, dipendenze, strumenti | no | nessuno |
revert | Annulla un commit precedente | dipende | dipende |
Una modifica che rompe la compatibilità è contrassegnata da un ! dopo il tipo o lo scope (feat(api)!: …) oppure da un footer BREAKING CHANGE:. In entrambi i casi la versione viene incrementata come major secondo Semantic Versioning. Una correzione rilevante per la sicurezza viene registrata in modo da poterla filtrare nella colonna Security del riepilogo cross-repository.
Semantic Versioning 2.0.0
Sezione intitolata “Semantic Versioning 2.0.0”L’incremento di versione è meccanico. Una release che contiene almeno una modifica che rompe la compatibilità è una major. In caso contrario, una release che contiene almeno un feat è una minor. In assenza di questi casi, una release che contiene almeno un fix o perf è una patch. I pacchetti precedenti alla 1.0 possono incrementare la minor per una modifica che rompe la compatibilità secondo SemVer §4. Il commit conserva comunque il contrassegno di rottura della compatibilità affinché il riepilogo resti accurato.
Raggruppamento Keep a Changelog
Sezione intitolata “Raggruppamento Keep a Changelog”Il CHANGELOG.md di ciascun repository segue Keep a Changelog 1.1.0: le voci sono raggruppate per versione rilasciata sotto Added, Changed, Deprecated, Removed, Fixed e Security. Una sezione [Unreleased] può contenere note sul lavoro in corso nel repository, ma il riepilogo cross-repository conteggia solo le versioni rilasciate e con tag. Il lavoro non rilasciato non compare mai nell’indice pubblico.
Come viene derivato il riepilogo cross-repository (e mantenuto privo di fughe di informazioni)
Sezione intitolata “Come viene derivato il riepilogo cross-repository (e mantenuto privo di fughe di informazioni)”La tabella di riepilogo nell’indice del changelog viene prodotta leggendo in sola lettura la cronologia Conventional Commits di ciascun repository fino all’ultimo tag rilasciato e conteggiando le categorie. Le regole di derivazione sono volutamente restrittive, così che nessun dettaglio interno trapeli:
- Conteggi, non contenuti. Viene riportato solo il numero di commit per ogni tipo rivolto all’utente. Nessun oggetto, corpo, footer o hash del commit viene visualizzato.
- Solo i tipi rivolti all’utente.
docs,test,ci,choreerefactorsono esclusi — non modificano nulla di osservabile da chi consuma il pacchetto. - Solo rilasciati. Un commit viene conteggiato solo quando fa parte di una release con tag di un pacchetto pubblico.
- Nessun identificativo. I riferimenti interni a issue, ticket, cicli, wave o work-item che possono comparire nello scope di un commit privato non vengono mai esposti, perché il testo dello scope stesso non viene mai visualizzato — viene letto solo il tipo.
- Nessuna attribuzione di automazione. I trailer di attribuzione dei contributori generati dall’automazione non vengono letti né visualizzati.
Per questo motivo il changelog pubblico è un riepilogo per categoria con collegamenti al CHANGELOG.md di ciascun pacchetto, anziché un feed aggregato di commit. Per costruzione, il riepilogo è dimostrabilmente privo di fughe di informazioni interne. Il testo autorevole rimane nel pacchetto che ne è proprietario.