Git, semantic versioning and how it fits into (my) a typical development timeline?

Question

I'm working on a Q&A system and about to tag my current application with "1.0.0" for it's first official version/tag. It's about to be rolled out for beta testing to a limited test audience next. Is "1.0.0" correct at this stage?

Also, no doubt there will be many bugs found at that stage. Do I keep it as "1.0.0" but forcefully moving the tag until it's release. Or upon fixing the bugs, would I give it a new tag "1.0.1". Then after another round of testing perhaps "1.0.2"

So when working on enhancements (e.g. new features such as a new menu, new search input field) would these be minor changes as in from "1.0.0" to "1.1.0"?

Answer 1

You mention that you are looking at using semantic versioning, so lets look at the semantic versioning spec at http://semver.org/:

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.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

and a little further down:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

So if you a releasing a true beta of your 1.0 release, you should tag it 1.0.0-beta (or similar according to the spec). If you are going to have multiple beta releases as you fix bugs, then 1.0.0-beta.1, 1.0.0-beta.2, etc.

When you are adding features that are backwards-compatible, you should increment the MINOR number. If you make lots of internal changes that would cause breaking changes elsewhere in your application, then that is a MAJOR change. If you are making less dramatic changes (for example, you only add code and don't change behavior of existing code), then this would be a MINOR change. If you have a UI heavy application and completely change that UI, I would also say that is a MAJOR change as well (UI can be considered the API for end users).

As for how to add indicators to your git repo, I'd suggest that you first create a 1.x branch. This will allow you to easily follow everything in version 1 while allowing continued development of version 2 on master. Then you tag the beta release with a tag 1.0.0-beta (or -beta.1 if there will be multiple betas). Once you fix all the bugs you need to fix, tag the actual 1.0.0 release. Then tag each release as necessary.

You can take a look at some tried-and-true workflows for git like git flow and github flow for ideas of how you want to set up your ongoing workflow.

Also, if you want a little more context about semantic versioning for programs without an API, this answer goes into some depth.

Answer 2

Yes, update the version number all the time it moves out of your control and into someone else's.

the reason is you need ot know what they were working with. When test comes back and says"we found a bug in version 1.0.0", the last thing you want is to say "which version 1.0.0, the one we gave you on Monday or the updated one I gave you on Friday?"

Updating the 3rd number is really designed for this, the functional difference between 1.0.0 and 1.0.999 should be limited, when you add big new features, then you update the 2nd number. Though, adding a new search input field doesn't really count as a big enough change to warrant a 2nd number update, but YMMV.

Personally, I tend to use the 2nd number not so much for feature updates but to mark a "full release", ie one that has been through test and passed. Then I update that value and repeat the back-and-forth between dev and test, incrementing the 3rd number each time until it all passes.

Answer 3

Good answers already given, but I would also find a way to incorporate the git sha1 in your application, so you can find that it was git commit 1b5619273127398123 that was the one used in this particular release. That way, if Mr Smith from BigCo calls and complains that his app isn't working just right, you can ask "What is the long row of digits and letters on the second wor when you click About?", and git checkout NNNNNN to get exactly that version, then do the same steps as Mr Smith did, and (hopefully) reproduce the problem. There's nothing worse than trying to find a problem that you can't reproduce because you are using a subtly different version (where you by chance or on purpose avoid that particular issue).

Also make sure that your build system is included in the version - preferrably including which compiler version and so on - either encoded or store which build tools you use when you build the product inside your git repo.