Versioning

Inherent problem with versioning is that no text or code naturally have any version number attached to it. It's just a construct to keep track of changes, and be capable to compare own version with what is available in a repository. Additionally, I have to keep track of changes between the book and application; ideally, without having to do it by-hand, which is very error-prone, and time-consuming.

Currently, before each commit of book sources README and the book root files are updated with incremented commit number and current UTC time. Problem is, it is used exclusively for the book, versioning is not compatible with anything used for application versioning, and usage of commit number to keep track of changes. Commit number greatly depends on history, which one can easily mess with; by changing master branch (git branch master --onto my_branch), by squishing or deleting commits, by merging other branch, by starting a new (or relocating existing) repository at some other git hosting company.

So, in a following few days I'll be re-doing versioning, starting from what has been done to keep track of book related commits, changing commit number to independent counter, and expanding to include application sources. Independent counter needs to be saved, I'll use JSON in the root of the project so that it is shared between the book and the application; JSON is widely used, is human readable, has great support, and it's easily extensible, too.

In short, for application sources I'll adopt Semantic versioning 2.0 (https://semver.org/); seems reasonable, a lot of people is using it, has great support. I'll use 4th item, build number, so that for my project version would have <major>.<minor>.<patch>+<build>.<squished-utc-commit-time> format. For book full-blown versioning does not make any sense; so, only build number will be used, instead of currently used commit number; UTC commit time is already used. For instance, based on current application version and last commit to the book newly formatted version would be  0.1.0+962.20210305164027, in the book and README new version would be written just as 962.20210305164027 to simplify comparison.

Build number then would be incremented after each meaningful commit, i.e. either to the book or to the sources. If application sources has been changed, then in addition to the build number, at least a patch number has to be incremented as well, or, depending on a scope of commit, minor or even major number. Build number would not be incremented for administrative commits, e.g. if readme file is updated. Build number will never be reset, this is crucial to enable comparing the book and the application versions.