Web Software Versioning
I started working on the new, but yet unreleased, version of Candidio.com a few months ago and one thing that I look back and regret, is that we had not software versioning established. With over 500 commits to our Master repository, its a bit of a nightmare to look at our history and pull out any logical milestones to reference.
Going forward, we're going to establish some conventions that make sense for us as a team. The first is entrenching ourselves in a good Git workflow that makes sense and reduces the amount cruddy commit message to nil (hopefully). After a bit of Stack Overflow research, I've come to this awesome article by Rein Henrichs, A Git Workflow for Agile Teams — I wish I had seen this 9 months ago.
Also crucial to this is ensuring our commit messages are not too verbose, yet descriptive enough to encapsulate everything in the commit that changed. I then ran into this article, A note about Git commit messages, which elaborates on what makes a well formed commit message — just some plain ol' common sense is needed.
Finally, establishing a convention for version numbering is crucial. For Candidio, we've taken on this scheme:
[major].[minor].[release].[build]
Major increments when code is committed to the develop repository that can be considered a "major" product update, or code that once in production, there is no going back. This update is not backwards-compatible.
Minor increments when one or more feature is added or undergoes a workflow refactoring. Reset this to 0 when incrementing Major.
Release increments every time we hit a development milestone and release the product, event internally (e.g. to staging). This is especially important for communication in the organization. For us, anytime we push an update to the staging server is our key to increment. Reset this to 0 when incrementing Major or Minor.
Generating a Build Number.
We use Git for version control, so there is no monotonically increasing numbers like'v123' or the equivalent to go with each commit, like SVN. We run git describe on a commit to get a human-readable name. When running this command, Git gives the name of the nearest tag with the number of commits on top of that tag and a partial SHA-1 value of the commit you're describing. This way, we can export a snapshot or build and name it something understandable to people.