SemVer stands for Semantic Versioning. At the time of writing, 2.0.0 is the latest of the versioning strategy. This article won’t outline the entirety of strategy, that you can get on their website. Just head over to semver.org for that. This article is an excerpt on how to use SemVer safely.
So what is SemVer then? Its a versioning strategy to manage your releases and avoid conflicts/ambiguity in your releases. An example usage can be to tag your repository for production when you’re ready to release it out – deeming it stable.
First off, if you’re going to version a package using SemVer, you have to follow the following standard:
<Major>.<Minor>.<Patch>
Example: git tag 5.2.7
5. -> 5th major release (changes that are backwards incompatible).
2. -> 2nd minor release (features but backwards compatible)
7 -> 7th patch release (bugfixes)
Each of the above represent a number starting from 0. As you make changes, these will be incremented resetting the counter back to 0 to the right of the incremented number.
Each of these number represent the type of change you’ve made to the code and represent the significance of the change for the public using them. To put it simply:
Major: Changes that introduce backwards incompatibility. Importing a change like this is going to break the consumers code, they will have to make adjustments.
Minor: Additional options/features for the public API. These must be non-breaking.
Patch: Fixes/Refactoring/Test coverage of the code. These represent no significant change in terms of consumption of the code.
Examples:
Assume your code is version controlled and is at version 1.0.0. You have a AuthenticationService class with the methods
- public function authenticate(User $user)
- public function login(User $user)
- protected function logout()
- private function isValid(User $user)
Consider all changes to be incremental after one another.
Change 1 – You’ve added test coverage for the above public methods – Patch version bump resulting in version 1.0.1. No public usage impact and no new features for the public have been introduced.
Change 2 – You’ve removed the logout() method deciding that logout will only happen when the session expires. Major version bump resulting in 2.0.0 because of a public facing method removal. People could be using this, and importing this change will break their code.
Change 3 – You’ve removed the isValid(User $user) method. Patch version bump resulting in 2.0.1. No public impact and no new features introduced. A private method is internal to the class.
Change 4 – You’ve add a public method isLoggedIn(User $user). Minor version bump resulting 2.1.0. You’ve added a new feature for the public to use.
As per SemVer, importing minor and patch versions is always safe. Major versions are breaking changes and should be treated carefully. If you use a tool such as composer to manage your project dependencies where you specify versions, the safest way to work is to using a fixed major version but highest minor and patch versions for auto updates. Example could be
^1.0 – import versions >= 1.0.0 && < 2.0.0
Please note that the major version 0.x.x has a different meaning to any other major version number. As per semver, a package with version 0.x.x is in development and not fit for public consumption. Once your package is ready, make sure to mark it with version 1.0.0 to release it to the public.