Should versions be bumped in dev branches or master branch?

Question

I have released API 1.0.0 in the master branch (default branch). Since then I have separately branched to branches api2/foo and api2/bar, both containing backwards-incompatible changes.

The API version is declared in the source code. Should I bump the version to 2.0.0 in both api2/* branches, or in the master branch?

If I bump version in the master branch, the versions in the source code on api2/* branches will not be updated. If I am to release development builds for the branches, things in API 2 may be used when the project declares to be API 1. As a result, I have to merge the commit in the master branch that bumps the version, but I will mege other changes in the master branch altogether, and I don't want it to happen yet.

On the other hand, if I bump version in dev branches, there will be two commits bumping the versions, so when they are both merged into the master branch, there would potentially be conflicts.

What would be a good solution between these two options?

Answer 1

Version the code when you build a release on your CI server.

Normally this would be on a check in to develop, master if you don't have a develop branch

If you version the feature branches you will get into trouble as there is no clear definition of which is 'the latest' version.

Because you are lacking the develop branch, and both changes are incompatible you will have to:

• merge foo into master, build v2
• merge master into bar, fix incompatiblities
• merge bar into master, build v3

Answer 2

The underlying question is: what is a good commit size?

My advice is: a commit should contain a single but complete change.

"Single" means the least possible amount of changed lines.
"Complete" means that the project compiles and all automated test run successfully.

In that sense the "version bump" is such single but complete change.

If that "version bump" would be in a separate commit then you could simply remove (skip) that commit by git rebase -i before merging.

Answer 3

In my opinion, it would be unwise to update to 2.0.0 in both branches separately, because that would imply that both of them represent version 2.0.0. But this is clearly a contradiction, because they are incompatible with each other. To have two incompatible builds with the same version number defeats the whole purpose of versioning in the first place!

You should merge both into a release branch, or merge foo into bar (or vice versa) and then bump the version to 2.0.0. You can then merge that back into master.

Answer 4

How you choose to do this depends on how your pipeline looks.

There should be no way to accidentally start using an incompatible version, if you were previously using a stable released version. This means that the version number needs to be changed before the first opportunity to build an artefact that gets distributed (a local build by any developer working on the feature would be fine).

You could have a pipeline where the only way to build an artefact that might get used by someone else is to run a job on your build server which requires you to specify a new version, causing the build server to push a commit with the updated version number.

You could implement a versioning scheme that prevents automatic upgrades to "in-progress" branches - e.g. make sure that whatever dependency manager you use doesn't automatically upgrade to versions with qualifiers, and have a policy that all checkouts should immediately add a qualifier like "-branch-name" to the version number (if you have an automated pipeline, it could instead add that qualifier for you on every build).

Since you already have the branches and it seems you don't have any other solution in place, I would mark both branches as "2.0.0-SNAPSHOT", merge them, and then bump to "2.0.0". Making the same change twice should not cause a merge conflict - and if there is one, resolution should be trivial. Using a "SNAPSHOT" qualifier will prevent the version from counting as a "full" 2.0.0 (in most dependency managers I'm familiar with) and be a clear indication to humans that it is a work in progress, while the 2.0.0 allows you to show that it is not backwards-compatible.