Semantic Versioning (SemVer)

• Wat is Semantic Versioning?
• Wat zijn de vereisten voor Semantic Versioning?
• Waarom Semantic Versioning gebruiken?
• Hoe koppel je versienummers aan Git-versiebeheer?
• Hoe houd je een changelog bij?
• Hoe werken versies in composer.json?

Lees alle details over Semantic Versioning op de website server.org: https://semver.org/spec/v2.0.0.html.

Wat is Semantic Versioning?

Semantic Versioning (of kort Semver) is een manier om software versies bij te houden. Je hebt vast wel eens een zo’n versienummer gezien, bijvoorbeeld: 1.1.0. Het nummer is opgebouwd uit drie cijfers die gescheiden worden door een punt. Primair, Secundair en Patch. Primair staat voor een Major-versie, Secundair staat voor een Minor-versie en Patch staat voor een Patch-versie.

1. Major betekend een grote update. Hierbij worden er grote wijzigingen doorgevoerd waardoor bestaande functionaliteit niet meer compatibel is of heel anders werkt.
2. Minor betekend een kleine update. Bestaande functionaliteit blijft ongeveer hetzelfde werken.
3. Patch wordt gebruikt voor bugfixes en kleine aanpassingen. Bestaande functionaliteit blijft werken.

Als uitbreiding op de opbouw Major.Minor.Patch zijn er nog enkele mogelijkheden voor als de software in ontwikkeling is. Denk bijvoorbeeld aan de toevoeging -alpha of -beta.

Wat zijn de vereisten voor Semantic Versioning?

Er is een lange lijst beschikbaar waarin de specificatie van Semantic Versioning is opgenomen. De belangrijkste punten zijn in het kort gezegd:

• Er moet documentatie zijn,
• Versienummers moeten oplopend zijn,
• Versienummers mogen niet negatief zijn,
• Source code wat uitgebracht is mag niet meer aangepast worden onder hetzelfde versienummer. Bij hotfixes of bugfixes moet minimaal het Patch-onderdeel verhoogd worden,
• Major-versie 0 wordt alleen gebruikt voor initiële ontwikkeling. Dan mag je de gehele API nog aanpassen zonder backwards compatibel te zijn.
• Wanneer je een Major- of Minor-versie aanpast moet de opvolgende nummers altijd teruggezet worden op 0. Dus een Minor update op versie 1.2.3 gaat naar 1.3.0 en niet naar 1.3.3, 1.3.4, 2.3.4 of iets anders.

Waarom Semantic Versioning gebruiken?

Als jij versiebeheer en versienummers gebruikt werk je hoogstwaarschijnlijk al volgens Semver of volgens een vergelijkbaar principe. Wij adviseren duidelijk op te nemen volgens welk principe je werkt zodat je eenvoudig andere stakeholders kunt wijzen op de manier hoe je werkt. Ze kunnen de versie opbouw dan zelf nalezen of ze weten direct wat je bedoeld.

Als je nog geen versienummers gebruikt is Semver een zeer geschikte methode om te introduceren, maar dan komt al snel de vraag bij welke versie je moet beginnen. Je product kan natuurlijk al in gebruik zijn, waardoor versie 1.0.0 eigenlijk niet zou kloppen. Je zou ervoor kunnen kiezen om bij 2.0.0 te beginnen en vanaf daar verder te werken volgens het Semver-principe.

Hoe koppel ik versies aan mijn Git-versiebeheer?

Lees hoe je versies koppelt aan een Git-commit in deze tutorial. Je leert hoe je een Git-tag aanmaakt in de belangrijkste Git-clients: Github Desktop, VSCode, en via de terminal.

Hoe houd ik een changelog bij?

Een changelog bijhouden is iets wat nauw verbonden is aan een systeem in versienummers. Wij hebben al eens eerder geschreven over wat een changelog is en hoe een changelog werkt.

Hoe werken versies in composer.json?

Hoe versies in composer.json werken kan je lezen in de gelinkte blog.