Learning patterns/Communicating with developers through Semantic Versioning

From Meta, a Wikimedia project coordination wiki
Jump to navigation Jump to search
A learning pattern forhackathons
Communicating with developers through Semantic Versioning
Semver.jpg
problemWhen developing a software that will be depended on, being able to communicate breaking changes is crucial
solutionUsing packages version numbers, we can efficiently communicate when an update should be performed carefully
creatorMaxlath
endorse
created on10:26, 18 October 2019 (UTC)
status:DRAFT

What problem does this solve?[edit]

When developing a software that will be depended on, being able to communicate breaking changes is crucial: developers using your software as a dependency might update the version their software uses for different reasons - from new features to security patches - but it can be hard to quickly access the implied changes just by looking at the code or even the commit history.

What is the solution?[edit]

Using packages version numbers, we can efficiently communicate when an update should be performed carefully: that's called Semantic Versioning and it's awesome.

Semver

It boils down to the following rules:

  • the major number would be incremented for every release containing a breaking change
  • the minor would be incremented for every release containing a new feature that doesn't break previously published interfaces
  • patch versions would then just be for releases fixing something, without breaking any interface or adding any new feature

Things to consider[edit]

  • This might mean that you often update the major version number of your package, which doesn't go well in certain software cultures, but that is progressively changing

When to use[edit]

When other pieces of software depend on your piece of software, and you need to communicate with the developers of those dependent software on changes that might break their code.

Example: see the change logs of a major version in wikibase-sdk for instance: every time breaking changes are released, the major version number is incremented[1], so tools such as NPM knows that they shouldn't install that version automatically[2]

Endorsements[edit]

See also[edit]

Related patterns[edit]

External links[edit]

References[edit]