Skip to content

install-script-latest-release-verification.md

Latest commit

 

History

History
290 lines (189 loc) · 6.98 KB

install-script-latest-release-verification.md

File metadata and controls

290 lines (189 loc) · 6.98 KB

Verify curl -fsSL https://myflow.sh/install.sh | sh Installs the Latest Flow Release

Use this runbook whenever you need to prove that the public installer is actually pulling the current latest stable Flow release.

The fastest repo-local check is now:

./scripts/verify-install-latest-release.sh

Or through Flow:

f verify-install-latest-release

This is the check that matters for users:

curl -fsSL https://myflow.sh/install.sh | sh

What This Must Prove

After a stable release, these values must all agree:

  • Cargo.toml package version
  • pushed release tag vX.Y.Z
  • GitHub releases/latest tag
  • version reported by a fresh temp-home install of ~/.flow/bin/f

If any one of those differs, the public install story is broken.

One-Command Verification

The script performs all of these checks:

  1. validate expected tag vs Cargo.toml via scripts/check_release_tag_version.py
  2. poll GitHub releases/latest until it matches the expected tag
  3. run the real public installer in a fresh temp HOME
  4. verify the installed binary version
  5. download the direct release asset for the current platform and verify that too

Default usage:

./scripts/verify-install-latest-release.sh

Useful options:

./scripts/verify-install-latest-release.sh --latest-timeout 300
./scripts/verify-install-latest-release.sh --tag v0.1.3
./scripts/verify-install-latest-release.sh --skip-asset
./scripts/verify-install-latest-release.sh --keep-temp

When To Run This

Run this after:

  • cutting a new stable release tag
  • changing install.sh
  • changing release packaging
  • changing versioning logic
  • fixing a release mismatch bug

Fast Pass Criteria

The installer is correct only if all of these are true:

  1. the release tag matches Cargo.toml
  2. GitHub marks that tag as latest stable
  3. a fresh temp-home install gets that same version
  4. a direct release asset download reports that same version

Manual Debug Procedure

If the one-command script fails, use the manual steps below to see exactly where the mismatch is.

Step 1: Confirm the Expected Version Locally

Read the package version from the repo:

python3 - <<'PY'
import pathlib, re
text = pathlib.Path("Cargo.toml").read_text(encoding="utf-8")
match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
if not match:
    raise SystemExit("failed to read Cargo.toml version")
print(match.group(1))
PY

If you already know the expected tag, validate it directly:

python3 scripts/check_release_tag_version.py v0.1.3

That script should fail hard on mismatches.

Step 2: Confirm GitHub Latest Stable

Check the public API that the installer uses:

curl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["tag_name"])'

This should print the expected stable tag, for example:

v0.1.3

Optional cross-checks:

gh release list --limit 5
gh release view v0.1.3 --json tagName,publishedAt,isDraft,isPrerelease,url

Step 3: Run the Real Public Installer in a Fresh Temp HOME

This is the main test. Use a fresh HOME and a minimal PATH so an existing install cannot leak in.

tmp_home="$(mktemp -d)"
echo "$tmp_home"

HOME="$tmp_home" PATH="/usr/bin:/bin:/usr/sbin:/sbin" sh -c \
  'curl -fsSL https://myflow.sh/install.sh | sh'

HOME="$tmp_home" "$tmp_home/.flow/bin/f" --version

Expected result:

  • install succeeds
  • ~/.flow/bin/f exists under the temp home
  • f --version reports the latest stable version

Example expected output:

flow 0.1.3

Step 4: Compare Installed Version to Latest Tag

Use this one-shot comparison:

latest_tag="$(curl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["tag_name"])')"

tmp_home="$(mktemp -d)"
HOME="$tmp_home" PATH="/usr/bin:/bin:/usr/sbin:/sbin" sh -c \
  'curl -fsSL https://myflow.sh/install.sh | sh >/dev/null'

installed_version="$(HOME="$tmp_home" "$tmp_home/.flow/bin/f" --version \
  | python3 -c 'import sys,re; m=re.search(r"flow ([0-9][^ ]*)", sys.stdin.read()); print(m.group(1) if m else "")')"

echo "latest_tag=$latest_tag"
echo "installed_version=$installed_version"

test "v$installed_version" = "$latest_tag"

If that final test fails, the installer path is not trustworthy.

Step 5: Isolate Installer Bug vs Release Artifact Bug

If the fresh install reports the wrong version, download the release asset directly.

Choose the target for your machine:

  • macOS Apple Silicon: aarch64-apple-darwin
  • macOS Intel: x86_64-apple-darwin
  • Linux x64: x86_64-unknown-linux-gnu
  • Linux arm64: aarch64-unknown-linux-gnu

Example for macOS Apple Silicon:

latest_tag="$(curl -fsSL https://api.github.com/repos/nikivdev/flow/releases/latest \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["tag_name"])')"

tmp_dir="$(mktemp -d)"
cd "$tmp_dir"

curl -fsSLO \
  "https://github.com/nikivdev/flow/releases/download/${latest_tag}/flow-aarch64-apple-darwin.tar.gz"

tar -xzf flow-aarch64-apple-darwin.tar.gz
./f --version

Interpretation:

  • direct asset wrong too: release artifact/versioning bug
  • direct asset correct but installer wrong: installer selection logic bug
  • API still shows old tag: release publication/propagation is not complete yet

Common Failure Modes

1. Release tag does not match Cargo version

Symptom:

  • python3 scripts/check_release_tag_version.py vX.Y.Z fails

Meaning:

  • the release was tagged from the wrong crate version

Fix:

  • bump Cargo.toml
  • refresh generated artifacts if needed
  • cut a new release tag

2. GitHub releases/latest still returns the old tag

Symptom:

  • release workflow is green
  • release page shows the new version
  • releases/latest still returns the old tag for a short time

Meaning:

  • GitHub publication or cache propagation delay

Fix:

  • wait and retry until releases/latest flips
  • do not declare success until the API itself returns the new tag

3. Installer reports old version but latest tag is correct

Symptom:

  • releases/latest returns the new tag
  • temp-home install still reports an older version

Meaning:

  • likely wrong binary inside the published release asset

Fix:

  • test the direct asset
  • if direct asset is also wrong, cut a corrected release

4. Temp-home test passes locally but users still get old f

Symptom:

  • your test is clean
  • user machine still reports an older version by plain f --version

Meaning:

  • user shell is resolving another binary earlier on PATH

Fix:

  • ask them to run:
which -a f
~/.flow/bin/f --version

Recommended Release Checklist

After publishing a stable tag:

  1. run python3 scripts/check_release_tag_version.py vX.Y.Z
  2. wait for the Release workflow to complete
  3. verify releases/latest returns vX.Y.Z
  4. run ./scripts/verify-install-latest-release.sh
  5. if there is any mismatch, test the direct asset before debugging the installer

Do not mark the release done until step 4 is green.