Best practices for versioning project after dependency upgrade

Question

Say, my project have dependency N with version 1.0.0. Then something have changed, and I should depend on newer version - let it be 1.0.1.

OK, I'm incrementing dependency version, nothing else changes in my code. It looks like I should increment my own projects' version, but how exactly I should increment?

Should I increment only third number (so-called revision), or best practices here are more complicated. For example, may be, if we are changing projects' dependency minor value, we should do the same thing in the project itself?

Answer 1

I'm not aware of any best practices for this situation, so here's my take:

An updated dependency should be reflected in your version; let's take the example of MAJOR.MINOR.REVISION numbering scheme.

Any version change in a dependency should at least increment your REVISION number, but a bigger change, such as a MAJOR or MINOR change in the dependency version, should cause you to increment your MINOR version.

Although MAJOR version changes in dependencies often come with API changes, I wouldn't increment your own MAJOR version unless you've made more changes than just updating to a new MAJOR version of a dependency.

Answer 2

Semantic Versioning is an attempt to codify the way version numbers ought to work.

In a nutshell:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

According to this, you shouldn't care about whether the change in the final product was due to changes in your code or changes in a dependency. If it adds functionality, change the minor version, if it doesn't, change the patch version, if it makes no difference at all (maybe you're not using the part of the dependency that changed), I think you don't need to update the version number at all.

Answer 3

If you're only updating the dependency, that's a minor revision (barely any change to your code) so I would only update the third numeral. The second numeral is usually reserved for major updates (big bug fixed, new features, balance issues, etc) and the first one for a completely new version of the software.

Answer 4

If you're writing a library, and not an app, then:

The problem I see with the other answers here is that when you upgrade a dependency across MAJOR revisions, OR you change the requirements in your dependency manager config file (package.json, Podfile, etc.), then you DO CHANGE your public API. Your API is not only the functions that you offer to other code, it's the dependencies you require to function.

Too often developers don't think this way and the clients of the library try to do an easy upgrade and end up with a dependency conflict nightmare.

Dependencies are part of your API. Period.

Upgrade your library MAJOR version when you change the MAJOR version of any of your dependency requirements (new min or max MAJOR version for any dependency), even if your own code API hasn't changed. Your library clients will thank you.