build/version-at-commit.sh

   1 #!/bin/bash
   2 # Copyright (C) The Arvados Authors. All rights reserved.
   3 #
   4 # SPDX-License-Identifier: AGPL-3.0
   5
   6 set -e -o pipefail
   7 commit="$1"
   8 devsuffix="~dev"
   9
  10 # automatically assign *development* version
  11 #
  12 # handles the following cases:
  13 #
  14 # *  commit is on main or a development branch, the nearest tag is older
  15 #    than commit where this branch joins main.
  16 #    -> take greatest version tag in repo X.Y.Z and assign X.(Y+1).0
  17 #
  18 # *  commit is on a release branch, the nearest tag is newer
  19 #    than the commit where this branch joins main.
  20 #    -> take nearest tag X.Y.Z and assign X.Y.(Z+1)
  21
  22 # X.Y.Z releases where Z=0 are called major
  23 # releases and X.Y.Z releases where Z>1 are called point releases.
  24 #
  25 # The development process distinction is that X.Y.0 releases are
  26 # branched from main and then subsequent X.Y.Z releases cherry-pick
  27 # individual features from main onto the "X.Y-staging" branch.
  28 #
  29 # In semantic versioning terminology an "X.Y.0" release which only
  30 # increments Y is called a "minor" release but typically these
  31 # releases have significant changes that calling them "minor" in
  32 # communications with users feels misleading.
  33 #
  34 # Incrementing X is reserved for times when a release has significant
  35 # backwards-incompatible changes, which we don't do very often and try
  36 # to avoid.
  37 #
  38 # In order to assign a useful development version, we need to
  39 # determine if we're on the main branch (or a development branch off
  40 # main) or on a release branch.  We do this by looking at the point
  41 # where the current commit history branched from main.
  42 #
  43 # If the tag for a new X+1 version appears on a release branch and not
  44 # directly in the history of main, the merge-base between main and the
  45 # release should be tagged as "development-X.Y.Z" so that
  46 # version-at-commit understands what version to assign to subsequent
  47 # commits on main.  It is also helpful to assign development-X.Y.Z
  48 # tags to make git-describe provide better version strings.
  49
  50 # 1. get the nearest tag with 'git describe'
  51 # 2. get the merge base between this commit and main
  52 # 3. if the tag is an ancestor of the merge base,
  53 #    (tag is older than merge base) increment minor version
  54 #    else, tag is newer than merge base, so increment point version
  55
  56 nearest_tag=$(git describe --abbrev=0 "$commit")
  57 # We must use a remote branch here because Jenkins CI checkouts usually only
  58 # have the current work branch ref (and not even that if we're working by
  59 # commit hash). As of June 2025 everything uses origin, so,
  60 merge_base=$(git merge-base origin/main "$commit")
  61
  62 if git merge-base --is-ancestor "$nearest_tag" "$merge_base" ; then
  63     # the nearest tag appears before the merge base with main (the
  64     # branch point), so assume this is a tag for the previous major
  65     # release (or a tag with the "development-" prefix indicating the
  66     # point where a major release branched off).  Subsequent
  67     # development versions are given the anticipated version for the
  68     # next major release.
  69     #
  70     # x.(y+1).0~devTIMESTAMP, where x.y.z is the newest version that does not contain $commit
  71     # grep reads the list of tags (-f) that contain $commit and filters them out (-v)
  72     # this prevents a newer tag from retroactively changing the versions of everything before it
  73     v=$(git tag |
  74             grep -vFf <(git tag --contains "$merge_base") |
  75             sed -e 's/^development-//' |
  76             sort --version-sort |
  77             awk '
  78 BEGIN { FS="."; OFS="."; }
  79 END { print $1, $2+1, 0; }
  80 ')
  81 else
  82     # the nearest tag comes after the merge base with main (the branch
  83     # point).  Assume this means this is a point release branch,
  84     # following a major release.
  85     #
  86     # x.y.(z+1)~devTIMESTAMP, where x.y.z is the latest released ancestor of $commit
  87     v=$(awk '
  88 BEGIN { FS="."; OFS="."; }
  89 { print $1, $2, $3+1; exit; }
  90 ' <<EOF
  91 ${nearest_tag#development-}
  92 EOF
  93         )
  94 fi
  95
  96 isodate=$(TZ=UTC git log -n1 --format=%cd --date=iso "$commit")
  97 ts=$(TZ=UTC date --date="$isodate" "+%Y%m%d%H%M%S")
  98 echo "${v}${devsuffix}${ts}"