SemVer: Major, Minor of Patch?

We maken bij semver onderscheid tussen drie verschillende niveau's van changes:

• Major versie ophogingen zijn voor API veranderingen die incompatibel (breaking) zijn.
• Minor versie ophogingen voegen functionaliteit toe die backwards-compatibele zijn.
• Patch versie ophogingen zijn bug fixes die backwards-compatibele zijn.

Het ophogen van een major versie nummer als een vorm van marketing bijvoorbeeld om iets te verkopen is niet de bedoeling. Major versies zijn ook geen versies die maar eenmaal per jaar plaatsvinden.

Het maakt niet uit hoe klein een breaking change is. Elke breaking change betekent een major versie bump.

We willen dat versie nummers vertrouwd kunnen worden en het is belangrijk om dat vertrouwen niet te beschamen.

Breaking changes in design tokens

1. Je hebt een design token verwijderd.
2. Je hebt een design token van naam veranderd. Dit is hetzelfde als het verwijderen van een design token gevolgd door het toevoegen van een nieuw design token. Dat maakt het een breaking change.
3. Je hebt een spelfout in een design token gecorrigeerd. Dit lijkt omdat het zo'n kleine wijziging is misschien een patch versie ophoging. Ook dit is hetzelfde als het verwijderen van een design token gevolgd door het toevoegen van een nieuw design token. Dat maakt ook dit een breaking change.

Minor changes in design tokens

1. Je hebt een design token toegevoegd. Voor gebruikers van het package met dit nieuwe design token is dit backwards-compatibel.

Patch changes in design tokens

1. Je hebt de waarde van een design token aangepast. Bijvoorbeeld de kleurwaarde van een design token is aangepast waardoor het contrast met een ander design token waarmee dit design token gecombineerd wordt wel voldoet aan een bepaalde drempel.
2. Je hebt een spelfout in de beschrijving van een design token aangepast. In Tokens Studio kun je beschrijvingen aan design tokens toevoegen. Het corrigeren van een spelfout in de beschrijving van een design token heeft geen gevolgen voor de afnemers. Deze veranderingen lijken het meest op een bug fix, maar zullen in de praktijk waarschijnlijk weinig voorkomen.

Breaking changes in CSS

1. Je hebt een class name verwijderd.
2. Je hebt een class name of mixin van naam veranderd. Dit is hetzelfde als het verwijderen van de class name of mixin gevolgd door het toevoegen van een nieuwe. Dat maakt dit een breaking change.
3. Je hebt een spelfout in een class name of mixin gecorrigeerd. Dit lijkt misschien op een patch versie ophoging, maar het is hetzelfde als het verwijderen van de oude name gevolgd door het toevoegen van een nieuwe name. Het is een breaking change omdat de oude name niet meer bestaat.
4. Je hebt de waarde van een CSS property toegevoegd. Bijvoorbeeld color: blue is aangepast naar color: var(--example-link-color, blue).
5. Je hebt de spelling van een CSS property gecorrigeerd. Bijvoorbeeld colour is aangepast naar color.

Minor changes in CSS

1. Je hebt een class name of mixin toegevoegd. Voor gebruikers van het package met dit nieuwe design token is dit backwards-compatibel.

Patch changers in CSS

In een design system dat door meerdere organisaties wordt gebruikt, kunnen zelfs kleine wijzigingen een grote impact hebben. Wat in een eigen project een eenvoudige patch voor verkeerde spacing zou zijn, kan in een design system een minor of zelfs breaking change betekenen. Daarom is het belangrijk om altijd rekening te houden met de impact van jouw wijziging op alle gebruikers.

Breaking changes in JavaScript/TypeScript

1. Je hebt een export weggehaald.
2. Je hebt de naam van een export veranderd. Dit is hetzelfde als het verwijderen van de export en het toevoegen van een nieuwe. Dat maakt dit een breaking change.
3. Je hebt een type signature veranderd naar een kleinere signature waardoor er functionaliteit verdwenen is.

Minor changes in JavaScript/TypeScript

1. Je hebt een export toegevoegd, er is functionaliteit toegevoegd die backwards-compatibel is.
2. Je hebt een type signature veranderd naar een grotere signature op een backwards-compatibele manier.

Patch changes in JavaScript/TypeScript

1. Je hebt een bug opgelost.

Wat betekent het voor ontwikkelaars van een package?

Het is belangrijk om te bepalen wat de impact is van de veranderingen die je hebt gedaan. Er wordt onderscheid gemaakt in major, minor, en patch veranderingen.

Major veranderingen zijn brekende (breaking) veranderingen. Veranderingen die, als iemand de nieuwe versie van het pakketje zou gebruiken niet meer doen wat de vorige versie van het pakketje deed.