I would suggest that for our version numbers we use Semantic Versioning, where we start at 0.1.0 and then the numbers increment at Major.Minor.Patch
I see that the intent is to have a stable branch in Git called master and then the work will be done on the development branch. In this case, what I have done before is anytime that development is merged into master, then the corresponding number is incremented and the merge commit is tagged with the new version number.
My quick, non-elaborated answer:
Semantic versioning makes a ton of sense for APIs. Its benefit outside of that is much less clear.
Short list of recommended reading, in no particular order:
This file has been truncated.
Spurred by recent events (https://news.ycombinator.com/item?id=8244700), this is a quick set of jotted-down thoughts about the state of "Semantic" Versioning, and why we should be fighting the good fight against it.
For a long time in the history of software, version numbers indicated the relative progress and change in a given piece of software. A major release (1.x.x) was *major*, a minor release (x.1.x) was *minor*, and a patch release was just a small patch. You could evaluate a given piece of software by name + version, and get a feeling for how far away version 2.0.1 was from version 2.8.0.
But Semantic Versioning (henceforth, SemVer), as specified at http://semver.org/, changes this to prioritize a mechanistic understanding of a codebase over a human one. *Any* "breaking" change to the software must be accompanied with a new major version number. It's alright for robots, but bad for us.
SemVer tries to compress a huge amount of information — the nature of the change, the percentage of users that will be affected by the change, the severity of the change (Is it easy to fix my code? Or do I have to rewrite everything?) — into a single number. And unsurprisingly, it's impossible for that single number to contain enough meaningful information.
If your package has a minor change in behavior that will "break" for 1% of your users, is that a breaking change? Does that change if the number of affected users is 10%? or 20? How about if instead, it's only a small number of users that will have to change their code, but the change for them will be difficult? — a common event with deprecated unpopular features. Semantic versioning treats all of these scenarios in the same way, even though in a perfect world the consumers of your codebase should be reacting to them in quite different ways.
Counterpoint, some part of this project is going to have an API as has already been mentioned, and I don’t think it makes sense to have two types of version numbers.
Sounds like a fair counter-point in principle, but I disagree in that it can make perfect sense (and
is not uncommon). [edit: on second thought, maybe it’s a bit uncommon, yes]
It might be sensible to make the API stable and opt for scheduled releases for the main software. It’s too early to decide, I’m afraid.
I’ll keep this in mind (suspended, as a low-priority background process) and postpone the decision until we are closer to actually making a first release.