How to version: software, tools, and libraries?

Vishwas Trivedi
3 min readJan 3, 2021

Most of the new manager's developers don’t give importance to maintaining the version of APIs, libraries, or tools. They are often too focused on coding, infra, and architecture which is a good thing but it often results in long-term mismanagement of features released, changes implemented, bug fixes, etc.

New managers or software developers often think that changes can be easily tracked through git or SVN(if you are still using it) but as the software and development team gets bigger; keeping track of changes gets difficult. Sooner or later every manager comes to the same conclusion:

Let’s maintain the version.

Well, let me give you a glimpse of how to properly maintain a version with the format and rules.

What is a version?

Versioning is the creation and management of multiple releases of a product, all of which have the same general function but are improved, upgraded, or customized. The term applies especially to operating systems (OSs), software, and web services.

Why does the software need to be versioned?

A versioned API/library is a contract between the producer of the API and its consumers saying:

I guarantee that this API will continue to work this way for the foreseeable future.

Put simply, if add(2, 3) returns 5 now, it will always return 5. And that’s the number 5, not a string “5″, or a JSON object { value: 5 }. Of course, not all APIs are this simple.

Realistically, APIs need to change. Bugs need to be fixed, security holes closed, out-of-date schemas updated, and so on. You absolutely cannot expect an API to never change. It’s how you manage these changes that make all the difference to consumers. Versioned APIs provide the ability to make breaking changes without breaking already-existing implementations.

It’s important for an API or library to find a balance between stability for existing users and innovation for the future. Library authors lean towards refactoring and rethinking code until it’s perfect, but breaking your existing users has a negative impact, especially for low-level libraries.

Version number format

--

--

Vishwas Trivedi

I am an accomplished Software Engineer/ Project Manager with 8.5 years of technical experience in driving successful software development teams.