Update mk.sh from fastfoo

setup/mk.sh

@@ -147,6 +147,46 @@ install() {
 }
 
 get_version() {
+    #
+    # Build semver version string with build metadata
+    #
+    # Build version string from available info using following
+    # logic:
+    #
+    #  1. use VERSION (from config.mk)
+    #  2. if we are in git, override the version with last tag
+    #  3. if set, add STAGE (from config.mk) as pre-release ID
+    #     (afer dash)
+    #  4. if we are at a later commit than the last tag, add commit
+    #     sha1 to build metadata (after plus sign)
+    #  5. if the tree is "dirty", i.e. has uncommited changes,
+    #     add "dirty" to build metadata
+    #
+    # The version is compatible with SemVer 2.0.0.
+    #
+    # Examples:
+    #
+    #     myprog v1.0.7                         # all clear
+    #     myprog v1.0.7-alpha                   # STAGE="alpha"
+    #     myprog v1.0.7-alpha+g1aef811          # ^^ + some commits after
+    #     myprog v1.0.7-alpha+g1aef811.dirty    # ^^ + tree edited
+    #     myprog v1.0.7-alpha+dirty             # tag OK but tree edited
+    #     myprog v1.0.7+dirty                   # ^^ but no stage
+    #
+    # Note that versions with "dirty" should be perceived as kind of
+    # dangerous outside developer's own machine.  Versions with sha1 are
+    # safer but must not be released.
+    #
+    # I have considered decorating the git commit refs to make them
+    # sort of sortable (e.g. "r1.g1aef811"), but on second thought,
+    # I don't think it's good idea to give *any* semantics to meta-data
+    # at all.  First, there is no rule that r1<r2<r3; a commit can be
+    # removing what other just added and one change can be split to
+    # multiple commits.  Also, the whole thing breaks anyway once you
+    # rebase your branch (no, it's not a sin).  The sole purpose of
+    # meta-data is to *identify* the code, and provide safe path back
+    # to tree; commit refs are already perfect for that.
+    #
     local version=$VERSION
     local stage=$STAGE
     if git rev-parse HEAD >&/dev/null;