release: Stamp binaries with released version

[minor-fixes]

Stamping the release version into binaries is necessary for both bug
reporting and reporting of client versions during auth, but is
challenging:

• logic to get the latest release tag info from git can be error-prone,
  due to the number of cases to handle (release off of main, off of
  release branch, etc.)
• tag is created last (so that we can be confident release will be
  successful before creating the tag) and isn't even present in git info
  during the build

Since we know the release version at the time of release, and we already
have a way to plumb buildstamp variables, this change allows the version
to be plumbed in via an environment variable:

• get_workspace_status will set a buildstamp var based on the
  environment variable's value
• the buildstamp library will read this var, and conditionally print the
  release version based on its value

Tested:

• negative case:

  scott-> bazel run --stamp //cmd/engflow_auth -- version
  build time: 2024-07-31 15:38:03 -0400 EDT
  official build: false
  build branch: scott/release_stamped_version
  build revision: 56612bc4adfbb777a76af06f98819ce00efd5808
  clean build: true
  

• positive case:

  scott-> BUILD_RELEASE_VERSION=foobar bazel run --stamp //cmd/engflow_auth -- version
  release version: foobar
  build time: 2024-07-31 15:36:30 -0400 EDT
  official build: false
  build branch: scott/release_stamped_version
  build revision: 56612bc4adfbb777a76af06f98819ce00efd5808
  clean build: true
  

[minor-fixes]

...this change is less polished than usual, because I'm not yet 100% on the approach - would love to hear alternate ideas

[rogerhu]

Stamping the release version into binaries is necessary for both bug reporting and reporting of client versions during auth, but is challenging:

Traditionally artifact-based solutions simply read off the version number hard-coded in a file that gets bumped. I definitely think the git sha is probably the most reliable for bug reporting. The release version is more for humans to discern?

[minor-fixes]

Traditionally artifact-based solutions simply read off the version number hard-coded in a file that gets bumped

We considered but abandoned this approach in the first iterations of the release process - IIRC the initial release script would do a file update, commit, tag, and push; @jayconrod's concerns were that automated commits weren't reviewed, and that tagging should be done last (in case the release process is unsuccessful - it's hard to un-tag). My concern for manually updating such a file is that it is increased friction on the release process and serves as a source of error. So now we have no version files! I think this is better, provided we can get away with it :)

I definitely think the git sha is probably the most reliable for bug reporting.

I agree; especially for testing internal versions. If every released version has a "release version" embedded in it that corresponds 1:1 to a git tag, then "release version" and git sha should be interchangeable.

The release version is more for humans to discern?

The output of engflow_auth version is, yes - although a follow-on PR could send this version string to the server in a header. We'll need to come up with a version string to send when there is no release version (git_branch+sha?) but this is left for a future change precisely because the scope is so much more broad.

[jayconrod]

If you're curious, the go tool uses git ls-remote -r <remote> to map tags to commits. It matches tags that look like versions (refs/tags/v1.2.3 and so on).

It seems nice and simple to just set the version explicitly in an environment variable though.

About keeping versions in files: we did that in the main repo, but it was kind of a pain to manage and often drifted out of date. We don't yet trust automatic changes without review on master or on release branches.