Documentazione breaking changes

[alessaro92]

Esiste già una discussione sul tema che ti interessa, o su un tema simile?

• Ho verificato e non esiste

Versione della libreria

2.11

Cosa

Manca una sezione specifica riguardante le breaking changes tra minor versions, o almeno non sono riuscito a trovarla.
Nel mio caso ho aggiornato da 2.x a 2.11 o successiva e sono incappato in questa breaking change che ho scoperto soltanto cercando lo specifico componente dopo essermi accorto era diverso rispetto a prima:
https://italia.github.io/bootstrap-italia/docs/organizzare-i-contenuti/liste/#con-testo-aggiuntivo-azioni-multiple-e-metadata

Sarebbe utile avere una pagina ad hoc per le breaking changes come c'è per la migrazione dalla versione 1.x

Perché

Utile per supportare al meglio gli sviluppatori durante gli aggiornamenti di versioni minor della libreria

Contesto

No response

Altro

No response

[zetareticoli]

Attualmente le breaking changes sono documentate nelle varie sotto sezioni specifiche e nel changelog (esempio).

Ti immaginavi una sezione equivalente del changelod di GitHub o una lista delle solite breaking raccolte per versione?

[alessaro92]

La mia idea era una sezione con la raccolta di breaking changes per versione ed eventuali riferimenti specifici, in modo da semplificare le migrazioni alle nuove versioni. Nell'esempio che ho riportato sopra https://italia.github.io/bootstrap-italia/docs/organizzare-i-contenuti/liste/#con-testo-aggiuntivo-azioni-multiple-e-metadata è indicata una breaking change a partire dalla versione 2.11 ma non è indicata come tale nel changelog di github

[Fupete]

Ciao @alessaro92, con @astagi e il team, proveremo ad approfondire come implementare automatismi per migliorare la definizione delle breaking changes nel changelog su GitHub delle versioni. E come migliorare la documentazione. Usiamo questa issue per tracciare i lavori.

[astagi]

@alessaro92 @Fupete @zetareticoli

❓ Ha senso secondo voi creare una pagina nella documentazione con tutte le breaking? In questo caso occorre creare uno script che raccolga le breaking dal changelog o dalla documentazione. Lascio aperta la discussione.

Per il momento agirei in questo modo:

• Tracciamo le breaking sul changelog di GitHub e il file CHANGELOG.md (almeno fino alla versione `2.9', non andrei oltre)
• Utilizziamo da ora in poi la feature dei Conventional commits sulle breaking (di seguito un esempio di un CHANGELOG di rilascio automaticamente creato con questa feature)

# [2.13.0](https://github.com/italia/bootstrap-italia/compare/v2.12.1...v2.13.0) (2025-01-15)


### Bug Fixes

* **a11y:** change steppers icons attributes ([2f78c2b](https://github.com/italia/bootstrap-italia/commit/2f78c2bd53d0e3ba0b68c252709a0b424088539a))
* badge position in toolbar ([d4593e5](https://github.com/italia/bootstrap-italia/commit/d4593e556fb0c448347a4c891a3a3221ace68c32))


### Features

* **types:** add video type ([4a5c555](https://github.com/italia/bootstrap-italia/commit/4a5c5556f2bba2f6b1f2977d1601ffaf967117c9))


### BREAKING CHANGES

* **a11y:** hide non-interactive Steppers icons from the accessibility API

[Fupete]

@astagi ok, fammi capire: quindi il dettaglio commit è sempre in Bug Fixes o Features, ma se è una breaking è nell'elenco sotto più dettagliato? Intanto: se è così per me sarebbe chiaro, e usare convenzioni standard mi trova ovviamente d'accordo ;-)

Il tema rimane per chi naviga la documentazione e un componente specifico. Sarebbe da avere in futuro un "changelog per componente" (direttamente a fine scheda componente per esempio e/o magari collassabile) che segnali eventuali breaking come proponeva @zetareticoli qualche giorno fa in meet.
In futuro si potrebbe pensare per la documentazione del design system (sul sito DI) in generale...

[alessaro92]

@astagi @Fupete @zetareticoli

Nell'esempio che ho riportato sopra https://italia.github.io/bootstrap-italia/docs/organizzare-i-contenuti/liste/#con-testo-aggiuntivo-azioni-multiple-e-metadata è indicata una breaking change a partire dalla versione 2.11 ma non è indicata come tale nel changelog di github

Interessante l'idea di recuperare le breaking changes dai messaggi dei commt tramite uno script, però, nel caso di questo componente, la breaking change non era indicata nel changelog della versione 2.11 qui su github.

A prescindere da come si voglia implementare, secondo me un elenco delle breaking changes per versione, non necessariamente raggruppato anche per componente, sarebbe utile ai dev in fase di aggiornamento della libreria.