Update MKit to v0.0.56

mkit.ini

@@ -30,4 +30,4 @@
 [files]
     bin = src/app dummy
 
-#mkit version=0.0.40
+#mkit version=0.0.56

utils/mkit/include/build.sh

@@ -14,7 +14,7 @@ __build1() {
     local dstpath=$2    # destination meaty animal path
     local ftype=$3      # file/builder type
     test -n "$dstpath"  || dstpath=${srcpath%.skel}
-    test -n "$ftype"    || ftype=$(__guess_ftype "$dstpath")
+    test -n "$ftype"    || ftype=MKIT_COMMON
     debug_var srcpath dstpath ftype
     <"$srcpath" __build1_ftype "$ftype" >"$dstpath"
     __rec_built "$dstpath"
@@ -26,16 +26,45 @@ __build1_ftype() {
     #
     local ftype=$1      # file/builder type
     case $ftype in
-        MKIT_COMMON)    __expand_macros "macros" ;;
-        rpmstuff)       __expand_macros "macros" "rpmstuff:macros" ;;
-        debstuff)       __expand_macros "macros" "debstuff:macros" ;;
+        MKIT_COMMON)    __expand_macros "build:macros" ;;
+        rpmstuff)       __expand_macros "rpmstuff:macros" ;;
+        debstuff)       __expand_macros "debstuff:macros" ;;
+        pystuff)        __expand_macros "pystuff:macros" ;;
         *)              die "unknown file type: $ftype" ;;
     esac
 }
 
+__macrol() {
+    #
+    # List known macros
+    #
+    find "${MacroDirs[@]}" -mindepth 1 -depth -printf '%P\n' \
+      | sed 's/[.]/:/g'
+}
+
+__macror() {
+    #
+    # Read macro $1
+    #
+    local key=$1
+    find "${MacroDirs[@]}" -mindepth 1 -depth -name "$key" \
+      | head -1 \
+      | xargs -r cat
+}
+
+__macrow() {
+    #
+    # Write stdin as macro $1
+    #
+    local fqkey=$1
+    local file="$MKIT_LOCAL/data/${fqkey//:/.}"
+    mkdir -p "${file%/*}"
+    cat >"$file"
+}
+
 __expand_line() {
     #
-    # Expand macro from $MacroMap in single line $1
+    # Expand macro from config in single line $1
     #
     # If macro value has multiple lines, repeat original line with
     # different substitution.
@@ -49,12 +78,12 @@ __expand_line() {
     local mvline    # line of macro value
     local xline     # expanded line
     xline=$line
-    for mname in "${!MacroMap[@]}"; do
+    for mname in $(__macrol); do
         if ! test "${line//$mname}" == "$line"; then
             xline=$(
                 while IFS= read -r mvline; do
                     echo "${line//$mname/$mvline}"
-                done <<<"${MacroMap[$mname]}"
+                done <<<"$(__macror "$mname")"
             )
         fi
         line=$xline
@@ -65,44 +94,25 @@ __expand_line() {
 
 __expand_macros() {
     #
-    # Read stdin, expanding macros from sections $@
+    # Read stdin, expanding macros from extra sections $@
     #
-    local section       # each section to expand macros from
+    local MacroDirs=()  # directories to lookup macros in
+    local mdir          # every ^^
     local line          # each line on stdin
-    local mname         # each macro name
-    local -A MacroMap   # macro value map
-    MacroMap[__MKIT_MKIT_VERSION__]=$MKIT_VERSION
-    MacroMap[__MKIT_PROJ_NAME__]=$(ini 1value project:name)
-    MacroMap[__MKIT_PROJ_CODENAME__]=$(ini 1value project:codename)
-    MacroMap[__MKIT_PROJ_LICENSE__]=$(ini 1value project:license)
-    MacroMap[__MKIT_PROJ_PKGNAME__]=$(ini 1value project:pkgname)
-    MacroMap[__MKIT_PROJ_TAGLINE__]=$(ini 1value project:tagline)
-    MacroMap[__MKIT_PROJ_MAINTAINER__]=$(ini 1value project:maintainer)
-    MacroMap[__MKIT_PROJ_VCS_BROWSER__]=$(ini 1value project:vcs_browser)
-    MacroMap[__MKIT_PROJ_GIT_LASTHASH__]=$(__cached git_lasthash)
-    MacroMap[__MKIT_PROJ_GIT_LASTSUMMARY__]=$(__cached git_lastsummary)
-    MacroMap[__MKIT_PROJ_VERSION__]=$(__cached semver)
-    for section in "$@"; do
-        for mname in $(ini lskeys "$section"); do
-            MacroMap[$mname]=$(ini values "$section:$mname")
-        done
+    local bltndata="$MKIT_LOCAL/data/MKIT_BUILTIN"
+    local usrdata="$MKIT_LOCAL/data/macros"
+    test -d "$bltndata" && MacroDirs+=("$bltndata")
+    test -d "$usrdata" && MacroDirs+=("$usrdata")
+    for extra in "$@"; do
+        mdir="$MKIT_LOCAL/data/${extra//:/.}"
+        test -d "$mdir" || continue
+        MacroDirs+=("$mdir")
     done
-    debug_var MacroMap
     while IFS= read -r line; do
         __expand_line "$line"
     done
 }
 
-__guess_ftype() {
-    #
-    # Guess file type from destination path $1
-    #
-    local dstpath=$1    # destination path
-    case $dstpath in
-        *)    echo MKIT_COMMON ;;
-    esac
-}
-
 __qfs() {
     #
     # Quote for our sed scipt's RHS
@@ -165,38 +175,139 @@ __rec_built() {
     echo "1:$file" >> "$MKIT_LOCAL/built.lst"
 }
 
-_mkit_data() {
+__rec_builtr() {
     #
-    # Build sampler showing all macro values
+    # Record dir $1 for recursive  deletion on `clean`
+    #
+    local path=$1
+    mkdir -p "$MKIT_LOCAL"
+    echo "r:$path" >> "$MKIT_LOCAL/built.lst"
+}
+
+_mkit_builddata() {
+    #
+    # Build config data
     #
     local macro
     local section
-    local sections
-    sections=()
-    ini lskeys macros | grep -q . && sections=(macros)
-    sections+=( $(ini lssect | grep ':macros$') )
-    {
-        echo "(builtin):"
-        echo "  x_MKIT_MKIT_VERSION__ => '__MKIT_MKIT_VERSION__'"
-        echo "  x_MKIT_PROJ_NAME__ => '__MKIT_PROJ_NAME__'"
-        echo "  x_MKIT_PROJ_CODENAME__ => '__MKIT_PROJ_CODENAME__'"
-        echo "  x_MKIT_PROJ_LICENSE__ => '__MKIT_PROJ_LICENSE__'"
-        echo "  x_MKIT_PROJ_PKGNAME__ => '__MKIT_PROJ_PKGNAME__'"
-        echo "  x_MKIT_PROJ_TAGLINE__ => '__MKIT_PROJ_TAGLINE__'"
-        echo "  x_MKIT_PROJ_MAINTAINER__ => '__MKIT_PROJ_MAINTAINER__'"
-        echo "  x_MKIT_PROJ_VCS_BROWSER__ => '__MKIT_PROJ_VCS_BROWSER__'"
-        echo "  x_MKIT_PROJ_GIT_LASTHASH__ => '__MKIT_PROJ_GIT_LASTHASH__'"
-        echo "  x_MKIT_PROJ_GIT_LASTSUMMARY__ => '__MKIT_PROJ_GIT_LASTSUMMARY__'"
-        echo "  x_MKIT_PROJ_VERSION__ => '__MKIT_PROJ_VERSION__'"
-        for section in "${sections[@]}"; do
-            echo "$section:"
-            for macro in $(ini lskeys "$section"); do
-                echo "  x${macro:1} => '$macro'"
-            done
+    test -d "$MKIT_LOCAL/data/build.macros" && {
+        warn "mkit: using cached _mkit_builddata: $(date -Isec -r "$MKIT_LOCAL/data/build.macros")"
+        warn "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    __rec_builtr "$MKIT_LOCAL/data"
+    for macro in $(ini lskeys "build:macros"); do
+        ini values "build:macros:$macro" | __macrow "build:macros/$macro"
+    done
+}
+
+_mkit_inidata() {
+    #
+    # Build INI data
+    #
+    test -d "$MKIT_LOCAL/data/ini" && {
+        warn "mkit: using cached _mkit_inidata: $(date -Isec -r "$MKIT_LOCAL/data/ini")"
+        warn "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    __rec_builtr "$MKIT_LOCAL/data"
+    local sect
+    local key
+    ini lssect \
+      | while read -r sect; do
+            mkdir -p "$MKIT_LOCAL/data/ini/$sect"
+            ini lskeys "$sect" \
+              | while read -r key; do
+                    ini values "$sect:$key" >"$MKIT_LOCAL/data/ini/$sect/$key"
+                done
         done
-    } \
-      | __expand_macros "MKIT_BUILTIN" "${sections[@]}" \
-      | sed '/^  x/ s|x|_|'
+}
+
+_mkit_metadata() {
+    #
+    # Build meta data
+    #
+    test -d "$MKIT_LOCAL/data/MKIT_BUILTIN" && {
+        warn "mkit: using cached _mkit_metadata: $(date -Isec -r "$MKIT_LOCAL/data/MKIT_BUILTIN")"
+        warn "mkit:   (hint: run 'make clean' to regenerate it)"
+        return 0
+    }
+    __rec_builtr "$MKIT_LOCAL/data"
+    echo "$MKIT_VERSION"            | __macrow MKIT_BUILTIN/__MKIT_MKIT_VERSION__
+    ini 1value project:name         | __macrow MKIT_BUILTIN/__MKIT_PROJ_NAME__
+    ini 1value project:codename     | __macrow MKIT_BUILTIN/__MKIT_PROJ_CODENAME__
+    ini 1value project:license      | __macrow MKIT_BUILTIN/__MKIT_PROJ_LICENSE__
+    ini 1value project:pkgname      | __macrow MKIT_BUILTIN/__MKIT_PROJ_PKGNAME__
+    ini 1value project:tagline      | __macrow MKIT_BUILTIN/__MKIT_PROJ_TAGLINE__
+    ini 1value project:maintainer   | __macrow MKIT_BUILTIN/__MKIT_PROJ_MAINTAINER__
+    ini 1value project:vcs_browser  | __macrow MKIT_BUILTIN/__MKIT_PROJ_VCS_BROWSER__
+    __cached git_lasthash           | __macrow MKIT_BUILTIN/__MKIT_PROJ_GIT_LASTHASH__
+    __cached git_lastsummary        | __macrow MKIT_BUILTIN/__MKIT_PROJ_GIT_LASTSUMMARY__
+    __cached semver                 | __macrow MKIT_BUILTIN/__MKIT_PROJ_VERSION__
+    for section in macros pystuff:macros debstuff:macros rpmstuff:macros; do
+        for macro in $(ini lskeys "$section"); do
+            ini values "$section:$macro" | __macrow "$section/$macro"
+        done
+    done
+}
+
+__subdirs() {
+    #
+    # List direct sub-directories of $1
+    #
+    find "$1" -maxdepth 1 -mindepth 1 -printf '%P\n' -type d
+}
+
+__subfiles() {
+    #
+    # List direct sub-files of $1
+    #
+    find "$1" -maxdepth 1 -mindepth 1 -printf '%P\n' -type f
+}
+
+_mkit_data() {
+    #
+    # Build sampler showing all macro values
+    #
+    warn "DEPRECATION: _mkit_data is deprecated and will be removed soon!"
+    warn "DEPRECATION: Use _mkit_show_metadata or _mkit_show_build instead."
+    warn "DEPRECATION: (redirecting to _mkit_show_metadata)"
+    _mkit_show_metadata
+}
+
+_mkit_show_metadata() {
+    #
+    # Show sampler of macro values
+    #
+    __show_msection MKIT_BUILTIN
+    __show_msection macros
+    __show_msection rpmstuff:macros
+    __show_msection debstuff:macros
+    __show_msection pystuff:macros
+}
+
+_mkit_show_builddata() {
+    #
+    # Show sampler of config values
+    #
+    __show_msection build:macros
+}
+
+__show_msection() {
+    #
+    # Show macros of section $1
+    #
+    local section=$1
+    local mname
+    local first=true
+    local label=$section
+    local secdir="$MKIT_LOCAL/data/${section//:/.}"
+    test -d "$secdir" || return 0
+    test "$section" == MKIT_BUILTIN && label="(builtin)"
+    for mname in $(__subfiles "$secdir"); do
+        $first && echo "$label:"; first=false
+        echo "    $mname => '$(<"$secdir/$mname")'"
+    done
 }
 
 build() {
@@ -271,7 +382,7 @@ debstuff() {
             mkdir -p "$(dirname "$dftgt")"
             __build1 "$dfsrc" "$dftgt" debstuff
         done
-    __rec_built debian
+    __rec_builtr debian
 }
 
 dist() {
@@ -292,6 +403,7 @@ dist() {
     mkdir -p "$dirname/.mkit"
     echo -n "$version" > "$dirname/.mkit/semver"
     echo -n "$git_lasthash" > "$dirname/.mkit/git_lasthash"
+    cp -r "$MKIT_LOCAL/data" "$dirname/.mkit/"
     tar -cf "$dirname.tar" "$dirname"
     gzip -f "$dirname.tar"      # see above FIXME
     __rec_built "$dirname.tar.gz"
@@ -309,3 +421,17 @@ rpmstuff() {
     test -f "$specsrc" || die "specfile template not found: $specsrc"
     __build1 "$specsrc" "$specname" rpmstuff
 }
+
+build_pystuff() {
+    #
+    # Build setup.py
+    #
+    local skel  # source of specfile
+    skel="$(ini 1value "dist:pystuff")"
+    test -n "$skel" || die "dist:pystuff not specified"
+    test -f "$skel" || die "setup.py template not found: $skel"
+    __build1 "$skel" "setup.py" pystuff
+    python setup.py sdist
+    __rec_builtr dist
+    __rec_built MANIFEST
+}

utils/mkit/include/facts.sh

@@ -20,6 +20,13 @@ git_bool() {
         dirty)
             git_bool dirty_files || git_bool dirty_index
             ;;
+        async)
+            local status_desc   # status description (in square brackets)
+            status_desc=$(git status -sb | grep '^##.*' | grep -o '\[[^]]*\]$')
+            grep -qw behind <<<"$status_desc" && return 0
+            grep -qw ahead <<<"$status_desc" && return 0
+            return 1
+            ;;
         *)
             warn "unknown git bool asked: $bool_name"
             return 2
@@ -124,6 +131,42 @@ git_lastsummary() {
       | cut -d' ' -f2-
 }
 
+make_bmeta() {
+    #
+    # Compose build metadata string
+    #
+    local is_tagged=T   # T if tagged (clean, no metadata), F if devel
+    local brname        # current branch name
+    local ghash         # current commit short hash
+    if ! git describe --tags --exact-match HEAD >&/dev/null;
+    then    # we are at a later commit than the last tag
+        is_tagged=F
+        brname=$(git_fact current_branch | sed 's/[^[:alnum:]]/_/g')
+        ghash=$(git_fact latest_sha)
+    fi
+    {
+        if test "$is_tagged" == F; then
+            test -n "$stamp" && echo "t$stamp"
+            echo "$brname"
+            echo "g$ghash"
+            test -n "$MKIT_UPSTREAM" && echo "u$MKIT_UPSTREAM"
+            git_bool async && "$MKIT_ASYNC" && echo async
+            "$MKIT_IN_CI" && test -z "$MKIT_UPSTREAM" && git_bool async && {
+                warn "branch is out-of sync with upstream; git hash might be misleading"
+                warn "  (hint: if this is due to CI auto-rebase, set MKIT_UPSTREAM to original shorthash)"
+            }
+        fi
+        git_bool dirty && echo dirty
+    } | paste -sd.
+}
+
+make_suffix() {
+    local bmeta
+    bmeta=$(make_bmeta)
+    test -n "$bmeta" || return 0
+    echo "+$bmeta"
+}
+
 semver() {
     #
     # Build proper SemVer version string
@@ -162,10 +205,6 @@ semver() {
     local xyz           # base version string
     local prerl         # pre-release keyword (from mkit.ini, eg. 'beta')
     local latest_tag    # latest git tag
-    local brname        # current branch name
-    local ghash         # current commit short hash
-    local is_tagged=T   # T if tagged (clean, no metadata), F if devel
-    local is_dirty=F    # F if dirty, T if clean
     local stamp         # timestamp or nothing (see $MKIT_TSTAMP)
     local suffix        # version suffix
     prerl=$(ini 1value project:prerl)
@@ -189,24 +228,7 @@ semver() {
         *)  warn "bad form of last tag, using base version from mkit.ini: tag is '$latest_tag'"
             xyz=$(ini 1value project:version) ;;
     esac
-    if ! git describe --tags --exact-match HEAD >&/dev/null;
-    then    # we are at a later commit than the last tag
-        is_tagged=F
-        brname=$(git_fact current_branch | sed 's/[^[:alnum:]]/_/g')
-        ghash=$(git_fact latest_sha)
-    fi
-    git_bool dirty && is_dirty=T
-    case "$is_dirty:$is_tagged:$stamp" in
-        F:T:*)  suffix=""                                 ;;
-        T:T:)   suffix="+dirty"                           ;;
-        T:T:*)  suffix="+t$stamp.dirty"                   ;;
-        F:F:)   suffix="+$brname.g$ghash"                 ;;
-        F:F:*)  suffix="+t$stamp.$brname.g$ghash"         ;;
-        T:F:)   suffix="+$brname.g$ghash.dirty"           ;;
-        T:F:*)  suffix="+t$stamp.$brname.g$ghash.dirty"   ;;
-        *)      suffix=MKIT_BUG
-                warn "MKIT_BUG: bad dirt/commit detection" ;;
-    esac
+    suffix=$(make_suffix)
     test -n "$prerl" && suffix="-$prerl$suffix"
     echo "$xyz$suffix"
 }

utils/mkit/include/mkit.sh

@@ -34,8 +34,14 @@ __valid_targets() {
     #
     # List valid routes
     #
+    echo _mkit_builddata
     echo _mkit_data
+    echo _mkit_inidata
+    echo _mkit_metadata
+    echo _mkit_show_builddata
+    echo _mkit_show_metadata
     echo build
+    echo build_pystuff
     echo clean
     echo debstuff
     echo dist
@@ -80,27 +86,82 @@ __compver() {
     #
     # True if version $1 matches our version
     #
-    # If our x is 0, check first two fragments, otherwise check just
-    # the x.  Fragments must equal.
+    # We're following a particular convention described in SemVer
+    # issue #363:
+    #
+    #     https://github.com/semver/semver/issues/363
+    #
+    # In short: If our X is 0, check first two fragments, otherwise
+    # check just the x.  Fragments must equal.
     #
     local their_ver=$1      # their version
     local our_x             # our X
     local our_y             # our Y
+    local our_z             # our z
     local their_x           # their X
     local their_y           # their Y
-    their_x=${their_ver%%.*}
-    their_y=${their_ver##$their_x.}
-    their_y=${their_y%%.*}
-    our_x=${MKIT_VERSION%%.*}
-    our_y=${MKIT_VERSION##$our_x.}
-    our_y=${our_y%%.*}
-    debug_var MKIT_VERSION our_x our_y their_ver their_x their_y
-    test "$their_x" -eq "$our_x" || return 1
-    test "$our_x" -eq 0 && {
-        test "$their_y" = "$our_y"
-        return $?
+    local their_z           # their Z
+    local diff_x='='        # difference in X: '=' for equal, 'o' for different
+    local diff_y='='        #  ^^ ...... in Y
+    local diff_z='='        #  ^^ ...... in Z
+    read -r their_x their_y their_z <<<"$(__parse_ver_xyz "$their_ver")" || die
+    read -r our_x   our_y   our_z   <<<"$(__parse_ver_xyz "$MKIT_VERSION")" || die
+    test "$their_x" -eq "$our_x" || diff_x=o
+    test "$their_y" -eq "$our_y" || diff_y=o
+    test "$their_z" -eq "$our_z" || diff_z=o
+    debug_var MKIT_VERSION our_x our_y our_z their_ver their_x their_y their_z diff_x diff_y diff_z
+    case $our_x.$our_y:$diff_x.$diff_y.$diff_z in
+        *.*:=.=.=)  return 0 ;;
+        *.*:o.?.?)  return 1 ;;
+        0.0:=.=.o)  __compver_hint_async ;;
+        0.*:=.=.?)  __compver_hint_async ;;
+        0.*:=.o.?)  return 1 ;;
+        *.*:=.=.o)  __compver_hint_async ;;
+        *)          warn "MKit bug while comparing versions!"
+                    warn " .. MKit could not handle version difference; here's dump:"
+                    warn " ...... MKIT_VERSION=$MKIT_VERSION"
+                    warn " ...... their_ver=$their_ver"
+                    warn " ...... our_x=$our_x our_y=$our_y our_z=$our_z"
+                    warn " ...... their_x=$their_x their_y=$their_y their_z=$their_z"
+                    warn " ...... diff_x=$diff_x diff_y=$diff_y diff_z=$diff_z"
+                    return 1 ;;
+    esac
+}
+
+__parse_ver_xyz() {
+    #
+    # Print space-separated X, Y and Z from version $1
+    #
+    local ver=$1
+    local xyz
+    xyz=$(grep -oE '^[0-9]+[.][0-9]+[.][0-9]+' <<<"$ver")
+    test -n "$xyz" || {
+        warn "could not parse version: $ver"
     }
-    return 0
+    echo "${xyz//./ }"
+}
+
+__compver_hint_async() {
+    #
+    # Warn about the version being async
+    #
+    # Versions where later fragments are different are considered
+    # compatible, but when MKit is updated, the best practice is
+    # to consult the changelog and see if fixes or new features
+    # enable optimizing or removing workarounds from the mkit.ini
+    # file.
+    #
+    # For that reason we will inform the maintainer about this
+    # fact.
+    #
+    # Because in typical MKit usage the MKit itself is embedded
+    # in the same git repository as the file, it should be easy
+    # to maintain the synchronicity.
+    #
+    warn "hint: mkit.ini version is out of sync: MKit: $MKIT_VERSION, mkit.ini: $their_ver"
+    warn "hint:  .. To hide this hint, consider updating mkit.ini based"
+    warn "hint:  .. on changes between these versions and update version"
+    warn "hint:  .. directive (\`#mkit version=..\`) to match MKit."
 }
 
 __chkiniversion() {
@@ -116,10 +177,10 @@ __chkiniversion() {
         {
             head -3 "$MKIT_INI"
             tail -3 "$MKIT_INI"
-        } | grep -m 1 -E '^# *mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
+        } | grep -m 1 -E '^#mkit +version *= *v?[0-9]+\.[0-9]+\.[0-9]+'
     )
     test -n "$ver_line" \
-     || die "version mark ('#mkit version=x.y.z') not found in: $MKIT_INI"
+     || die "version directive ('#mkit version=x.y.z') not found in: $MKIT_INI"
     their_ver="$(tr -d '[:blank:]v' <<<"${ver_line##*=}")"
     __compver "$their_ver" \
      || die "bad mkit.ini version: $their_ver does not match $MKIT_VERSION"

utils/mkit/include/vars.sh

@@ -4,6 +4,20 @@
 # See LICENSE file for copyright and license details.
 
 
+#
+# Add 'async' tag to build meta-data (true|false)
+#
+# If 'true' and during the version computation git branch is behind
+# or ahead its remote counterpart, build meta-data (part after '+'
+# sign) will contain word 'async'.
+#
+# This is to warn testers and developers when build was done after
+# automatic rebase done by CI system.
+#
+# Defaults to 'true'.
+#
+MKIT_ASYNC=${MKIT_ASYNC:-true}
+
 #
 # Bump size (for vbump_? and release_?)
 #
@@ -26,6 +40,16 @@ MKIT_DEFAULT_MODE="644"
 #
 MKIT_DRY=${MKIT_DRY:-false}
 
+#
+# Is MKit running in CI (true|false)
+#
+# If MKit is running in CI, it's recommended to set this to 'true'
+# to enable one or more useful warnings.
+#
+# Defaults to 'false'.
+#
+MKIT_IN_CI=${MKIT_IN_CI:-false}
+
 #
 # Path to mkit.ini
 #
@@ -83,7 +107,46 @@ MKIT_PROJ_PKGNAME=""
 #
 MKIT_TSTAMP=${MKIT_TSTAMP:-ctime}
 
+#
+# Upstream hash to add to build meta-data
+#
+# If set to non-empty string, it must represent a short-hash of
+# upstream commit on which local branch was automatically rebased
+# before build.
+#
+# If CI system automatically rebases branches, the resulting short-hash
+# (appearing with `g` prefix) will be meaningless, and might be
+# misleading -- testers and developers might see the build as coming
+# from an unknown source.
+#
+# In that case, it's strongly recommended for CI to set this to the
+# original pushed short-hash before the rebase.  Resulting meta-data
+# will contain both hashes, allowing users to pair test results with
+# original push.  The appearance of the extra hash will also warn
+# about the fact that the rebase took place.
+#
+# For example, if developer pushed branch 'foo' that pointed to
+# `5faf551`, and CI system rebased it, altering the HEAD to
+# `bb4baa4`, by default the version would look like:
+#
+#     0.0.1+t202103011224.foo.gbb4baa4
+#
+# This would be meaningless for testing, as the `bb4baa4` hash is
+# completely temporary and unknonwn.
+#
+# However, a conformant CI should set `MKIT_UPSTREAM=5faf551`, which
+# will result in version like:
+#
+#     0.0.1+t202103011224.foo.gbb4baa4.u5faf551
+#
+# which still has technically correct git hash after `g`, but contains
+# the original hash as pushed after `u`.
+#
+# Defaults to empty value.
+#
+MKIT_UPSTREAM=${MKIT_UPSTREAM:-}
+
 #
 # This MKit version
 #
-MKIT_VERSION=0.0.40
+MKIT_VERSION=0.0.56

utils/mkit/make

@@ -20,15 +20,30 @@ init_core() {
 #
 MKIT_DIR=${MKIT_DIR:-$(dirname "$0")}
 
+just_ini() {
+    #
+    # Just do one mkit.ini operation $1
+    #
+    local op=$1
+    local key=$2
+    mkit_init || return $?
+    ini "$op" "$key"
+}
 
-init_core
-
-case "$1" in
-    -V|--version-semver)    echo "$MKIT_VERSION"; exit 0 ;;
-    --version)              echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
-                            exit 0 ;;
-esac
-
-mkit_init
+main () {
+    init_core
+    case "$1" in
+        -V|--version-semver)    echo "$MKIT_VERSION"; exit 0 ;;
+        -i|--ini-1value)        just_ini 1value "$2"; exit $? ;;
+        -I|--ini-values)        just_ini values "$2"; exit $? ;;
+        --ini-lskeys)           just_ini lskeys "$2"; exit $? ;;
+        --ini-lssect)           just_ini lssect "$2"; exit $? ;;
+        --ini-sec)              just_ini sec    "$2"; exit $? ;;
+        --version)              echo "Mkit (Simple Makefile target helper) $MKIT_VERSION"
+                                exit 0 ;;
+    esac
+    mkit_init
+    route "$@"
+}
 
-route "$@"
+main "$@"

utils/mkit/mkit.mk

@@ -5,10 +5,26 @@ export MKIT_DIR
 
 all: build
 
-_mkit_data:
+_mkit_builddata: _mkit_metadata
+	@"$(MKIT_DIR)"/make _mkit_builddata
+
+_mkit_data: _mkit_metadata _mkit_builddata
 	@"$(MKIT_DIR)"/make _mkit_data
+	@"$(MKIT_DIR)"/make clean
+
+_mkit_inidata:
+	@"$(MKIT_DIR)"/make _mkit_inidata
+
+_mkit_metadata:
+	@"$(MKIT_DIR)"/make _mkit_metadata
 
-build:
+_mkit_show_metadata: _mkit_metadata
+	@"$(MKIT_DIR)"/make _mkit_show_metadata
+
+_mkit_show_builddata: _mkit_builddata
+	@"$(MKIT_DIR)"/make _mkit_show_builddata
+
+build: _mkit_builddata
 	@"$(MKIT_DIR)"/make build
 
 clean:
@@ -17,9 +33,12 @@ clean:
 debstuff: dist
 	@"$(MKIT_DIR)"/make debstuff
 
-dist: clean
+dist: clean _mkit_metadata
 	@"$(MKIT_DIR)"/make dist
 
+build_pystuff: clean _mkit_metadata build
+	@"$(MKIT_DIR)"/make build_pystuff
+
 rpmstuff: dist
 	@"$(MKIT_DIR)"/make rpmstuff
 
@@ -53,4 +72,4 @@ vbump_y:
 vbump_z:
 	@"$(MKIT_DIR)"/make vbump_z
 
-.PHONY: all _mkit_data clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z
+.PHONY: all _mkit_builddata _mkit_data _mkit_inidata _mkit_metadata _mkit_show_builddata _mkit_show_metadata build_pystuff clean dist rpmstuff install uninstall release release_x release_y release_z vbump vbump_x vbump_y vbump_z

utils/mkit/stub

@@ -63,6 +63,153 @@ deploy() {
             else
                 echo "(Nothing to say about this project.)"
             fi
+            echo ""
+            echo "See MAINTAINERS.md for instructions how to build and"
+            echo "maintain this MKit project."
+            ;;
+
+        MAINTAINERS.md)
+            local heading="$any_name - maintainer instructions"
+            echo "${heading^^}"
+            tr -c '=\n' '=' <<<"$heading"
+            echo ''
+            echo "<!--"
+            echo "    Note: This file has been auto-generated by MKit"
+            echo "    v$MKIT_VERSION when initializing the project."
+            echo "-->"
+            echo ''
+            echo "This project is using MKit for packaging and versioning"
+            echo "meta-data; this file describes how to do basic maintenance"
+            echo "operations."
+            echo ''
+            echo "MKit uses GNU Make as an interface, so all operations are"
+            echo "'make' targets and GNU Make takes care of the dependencies"
+            echo "between them.  For example, to install the project it's enough"
+            echo "to call 'make install'; GNU Make will call 'make built'"
+            echo "automatically if needed."
+            echo ""
+            echo ""
+            echo "Variables"
+            echo "---------"
+            echo ""
+            echo " *  \`DESTDIR\` - root of the installation destination"
+            echo " *  \`PREFIX\` - deployment prefix (often \`/usr\` or"
+            echo "    \`/usr/local\`)"
+            echo " *  \`MKIT_DRY\` - set to \`true\` to prevent MKit from making"
+            echo "    any changes"
+            echo " *  \`MKIT_DEBUG\` - set to \`true\` to have MKit display"
+            echo "    (lots of) debugging information"
+            echo ""
+            echo "See *utils/mkit/include/vars.sh* for full list oof supported"
+            echo "variables. (You can use \`sfdoc utils/mkit/include/vars.sh\`"
+            echo "if you have sfdoc installed.)"
+            echo ""
+            echo ""
+            echo "Building and installation"
+            echo "-------------------------"
+            echo ""
+            echo "These operations are allowed on any branch.  Assets built from"
+            echo "development branches will be marked using distinctive version"
+            echo "number containing timestamp, branch name and commit short-hash."
+            echo ""
+            echo " *  \`make\` - same as \`make build\`"
+            echo " *  \`make build\` - build project files"
+            echo " *  \`make install\` - install project to \`\$DESTDIR\`"
+            echo " *  \`make uninstall\` - uninstall project from \`\$DESTDIR\`"
+            echo " *  \`make rpmstuff\` - create RPM SPEC file and a source"
+            echo "    tarball"
+            echo " *  \`make debstuff\` - create 'debian' directory and a source"
+            echo "    tarball"
+            echo " *  \`make clean\` - remove any previously built assets".
+            echo ""
+            echo ""
+            echo "Versioning"
+            echo "----------"
+            echo ""
+            echo "These operations are only allowed on *release source branch*:"
+            echo ""
+            echo " *  \`make vbump\` - bump version and create bump commit"
+            echo " *  \`make release\` - create release tag"
+            echo ""
+            echo ""
+            echo "Recommended workflow"
+            echo "--------------------"
+            echo ""
+            echo ""
+            echo "### Development and testing ###"
+            echo ""
+            echo "Any branch can be used to create any kind of asset.  Assets"
+            echo "built from development branch will be marked using distinctive"
+            echo "version number in all MKit macros."
+            echo ""
+            echo "Development is done in branches as needed, but one branch"
+            echo "(often called *master*, *main* or *trunk*) is designated as"
+            echo "**release source** branch.  Only maintainer can push into this"
+            echo "branch and this is where maintainer creates the next release."
+            echo ""
+            echo ""
+            echo "### Versioning and releases ###"
+            echo ""
+            echo "After all development branches are merged and project is"
+            echo "considered ready for release, maintainer will create new"
+            echo "release.  This consists of three steps (only two of them are"
+            echo "assisted by MKit):"
+            echo ""
+            echo " 1. \`make vbump\` - will auto-edit [project:version] in"
+            echo "     mkit.ini and start creating **bump commit**."
+            echo ""
+            echo "    **Bump commit** is a special commit which consists of:"
+            echo ""
+            echo "     *  Bump of version in mkit.ini"
+            echo "     *  commit message providing rudimentary human"
+            echo "        readable summary of changes."
+            echo ""
+            echo "    \`make vbump\` target will cause bump of the *last*"
+            echo "    version fragment (Z, or PATCH in SemVer).  To bump other"
+            echo "    fragments, use \`make vbump_y\` or \`make vbump_x\` (MINOR"
+            echo "    or MAJOR in SemVer, respectively)."
+            echo ""
+            echo "    MKit will create a template of the message by scanning"
+            echo "    all commits since last release and invoke 'git commit' so"
+            echo "    that maintainer is presented with a window editing the"
+            echo "    commit message."
+            echo ""
+            echo "    Maintainer is responsible for finishing the commit message"
+            echo "    by:"
+            echo ""
+            echo "     *  Re-wording and merging the items as needed."
+            echo "     *  Adding any details, if needed."
+            echo "     *  Removing short hashes and file lists added by MKit"
+            echo "        (these are added only to make editing easier)."
+            echo ""
+            echo "    Once maintainer is happy with *bump commit* message,"
+            echo "    they can exit the editor and move on to next step."
+            echo ""
+            echo " 2. \`make release\` - will check if latest commit on current"
+            echo "    branch is a *bump commit*, and if yes, will create"
+            echo "    a corresponding **release tag**."
+            echo ""
+            echo "    **Release tags** are annotated tags (see *git-tag(1)*)"
+            echo "    formed by version number prefixed by letter \`v\` and are"
+            echo "    used by MKit to calculate version number when building"
+            echo "    assets.  Release tags contain the *bump commit* message"
+            echo "    as the annotation."
+            echo ""
+            echo "    If a *release destination* branch is specified as"
+            echo "    [project:reldst] in mkit.ini, MKit will also update that"
+            echo "    branch so that it points to the same commmit as the"
+            echo "    newly created release tag."
+            echo ""
+            echo " 3. Maintainer will push branches and commits to any shared"
+            echo "    remotes as needed."
+            echo ""
+            echo "    Warning: This is your last chance to fix any mistakes."
+            echo "    git tags are designed to be permanent, \"official\","
+            echo "    write-only objects and they will typically quickly spread"
+            echo "    to other clones.  *Don't count on getting rid of release"
+            echo "    tag*."
+            echo ""
+
             ;;
 
         */mkit.ini|mkit.ini)
@@ -90,6 +237,7 @@ deploy() {
                 echo "[dist]"
                 {
                     $MkLicense  && echo "tarball = LICENSE.md"
+                    $MkReadme   && echo "tarball = MAINTAINERS.md"
                     $MkMakefile && echo "tarball = Makefile"
                     $MkReadme   && echo "tarball = README.md"
                     echo "tarball = mkit.ini"
@@ -115,6 +263,9 @@ deploy() {
                 echo "[macros]"
                 {
                     echo "__${PackageName^^}_FOO__ = Barr.."
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION - replace this with your project"
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION .. description; this will appear"
+                    echo "    __PROJECT_DESC_MAIN__ = MKIT_STUB_DESCRIPTION .. in places like rpm -i"
                 } | reformat_section
                 echo ""
                 echo "[modes]"
@@ -135,18 +286,19 @@ deploy() {
             ;;
 
         packaging/template.spec)
-            echo 'Name:       __MKIT_PROJ_PKGNAME__'
-            echo 'Version:    __MKIT_PROJ_VERSION__'
-            echo 'Release:    1%{?dist}'
-            echo 'Summary:    __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
+            echo 'Name:           __MKIT_PROJ_PKGNAME__'
+            echo 'Version:        __MKIT_PROJ_VERSION__'
+            echo 'Release:        1%{?dist}'
+            echo 'Summary:        __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
             test -n "$VcsBrowser" && echo 'URL:        __MKIT_PROJ_VCS_BROWSER__'
-            $MkLicense && echo "License:    $License"
-            echo 'Source0:    %{name}-%{version}.tar.gz'
-            echo 'BuildArch:  noarch'
+            $MkLicense && echo "License:        $License"
+            echo 'Source0:        %{name}-%{version}.tar.gz'
+            echo 'BuildArch:      noarch'
+            echo 'BuildRequires:  make'
             echo ''
             echo 'Requires: MKIT_STUB_REQUIRES'
             echo '%description'
-            echo 'MKIT_STUB_DESCRIPTION'
+            echo '__PROJECT_DESC_MAIN__'
             echo ''
             echo '%prep'
             echo '%setup -q'
@@ -163,6 +315,7 @@ deploy() {
             echo '%changelog'
             echo ''
             echo '# specfile built with MKit __MKIT_MKIT_VERSION__'
+            echo "#  .. based on stub from: $MKIT_VERSION"
             ;;
 
         packaging/debian/copyright)
@@ -178,14 +331,16 @@ deploy() {
             echo 'Standards-Version: 3.9.2'
             echo 'Build-Depends:'
             echo ' debhelper (>= 9),'
+            echo ' make,'
             echo ''
             echo 'Package: __MKIT_PROJ_PKGNAME__'
             echo 'Architecture: all'
             echo 'Depends: MKIT_STUB_REQUIRES'
             echo 'Description: __MKIT_PROJ_NAME__ - __MKIT_PROJ_TAGLINE__'
-            echo ' MKIT_STUB_DESCRIPTION'
+            echo ' __PROJECT_DESC_MAIN__'
             echo ''
             echo '# control file built with MKit __MKIT_MKIT_VERSION__'
+            echo "#  .. based on stub from: $MKIT_VERSION"
             ;;
 
         packaging/debian/changelog)
@@ -205,11 +360,11 @@ deploy() {
             echo ''
             echo '%:'
             echo ''
-            echo '	dh $@'
+            echo '	PREFIX=/usr dh $@'
             echo ''
             echo 'override_dh_auto_install:'
             echo ''
-            echo '	make install PREFIX=/usr DESTDIR=debian/tmp'
+            echo '	make install DESTDIR=debian/tmp'
             ;;
 
         packaging/debian/source/format)
@@ -430,11 +585,15 @@ deploy() {
             if $MkReadme; then
             echo ""
             echo ""
-            echo "README.md"
-            echo "---------"
+            echo "README.md and MAINTAINERS.md"
+            echo "----------------------------"
             echo ""
             echo "Each serious project needs a serious README.  Which is why"
             echo "*stub* has created a 'stub' of one for you."
+            echo ""
+            echo "Furthermore MAINTAINERS.md is created to help maintainers"
+            echo "do basic MKit operations such as building assets and making"
+            echo "releases."
             fi
 
             echo ""
@@ -479,7 +638,7 @@ usage() {
         echo "    -V VERSION    initial version (default: 0.0.0)"
         echo "    -a            enable autoclean ('make clean' after"
         echo "                  each 'make install')"
-        echo "    -g            make git commits before and adter"
+        echo "    -g            make git commits before and after"
         echo "                  (implies -y)"
         echo "    -y            don't ask, just do it"
         echo "    -R            skip creating README.md"
@@ -699,6 +858,7 @@ main() {
     deploy src/"$PackageName".skel
     $MkMakefile     && deploy Makefile
     $MkReadme       && deploy README.md
+    $MkReadme       && deploy MAINTAINERS.md
     $MkLicense      && deploy LICENSE.md
     $AutoClean      && deploy .mkit/autoclean
     $MkPackaging    && deploy_packaging