Formalize update_engine_version.{sh|ps1}. (#162118)

Towards flutter/flutter#162201.

**NOTE**: This renames the environment variable to
`FLUTTER_PREBUILT_ENGINE_VERSION`.

---

We occasionally break ourselves, our users, and the Dart up (or is it
down? side-ways) stream repos (i.e. HHH) when we change how the
undocumented
[`update_engine_version.sh`](https://github.com/flutter/flutter/blob/master/bin/internal/update_engine_version.sh)
script, and it's Windows counterpart
[`update_engine_version.ps1`](https://github.com/flutter/flutter/blob/master/bin/internal/update_engine_version.ps1)
work, but have no way of knowing until N days/weeks later when someone
tells us.

For example,
<https://flutter-review.googlesource.com/c/recipes/+/62400>.

This is my attempt to encode "this is what you can guarantee by calling
this script".

It _still_ will be an internal only API that we might rev at any time,
but at least we:

1. Can tell the Dart team "this is tested and how it works"
2. If we want to change it, the tests will keep us from changing it
without informing folks it changed

These tests should (in theory) cover both Linux/MacOS and Windows.

/cc @a-siva

Author: matanlurey

.github/workflows/files-changed.yml

@@ -22,7 +22,7 @@ jobs:
         run: |
           git fetch --no-tags --prune --depth=1 origin ${{ github.event.pull_request.base.sha }}
           git fetch --no-tags --prune --depth=1 origin master
-          echo "FLUTTER_ENGINE_VERSION=${{ github.event.pull_request.base.sha }}" >> "$GITHUB_ENV"
+          echo "FLUTTER_PREBUILT_ENGINE_VERSION=${{ github.event.pull_request.base.sha }}" >> "$GITHUB_ENV"
 
       - name: Initialize Dart SDK
         # This downloads the version of the Dart SDK for the current platform.

bin/internal/update_engine_version.ps1

@@ -2,6 +2,9 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+# Want to test this script?
+# $ cd dev/tools
+# $ dart test test/update_engine_version_test.dart
 
 # ---------------------------------- NOTE ---------------------------------- #
 #
@@ -11,13 +14,28 @@
 #
 # -------------------------------------------------------------------------- #
 
-$ErrorActionPreference = "Stop"
-
 $progName = Split-Path -parent $MyInvocation.MyCommand.Definition
 $flutterRoot = (Get-Item $progName).parent.parent.FullName
 
+# Allow overriding the intended engine version via FLUTTER_PREBUILT_ENGINE_VERSION.
+#
+# This is for systems, such as Github Actions, where we know ahead of time the
+# base-ref we want to use (to download the engine binaries and avoid trying
+# to compute one below), or for the Dart HH bot, which wants to try the current
+# Flutter framework/engine with a different Dart SDK.
+#
+# This environment variable is EXPERIMENTAL. If you are not on the Flutter infra
+# or Dart infra teams, this code path might be removed at anytime and cease
+# functioning. Please file an issue if you have workflow needs.
+if (![string]::IsNullOrEmpty($env:FLUTTER_PREBUILT_ENGINE_VERSION)) {
+  $engineVersion = $env:FLUTTER_PREBUILT_ENGINE_VERSION
+  Write-Error "[Unstable] Override: Setting engine SHA to $engineVersion"
+}
+
+$ErrorActionPreference = "Stop"
+
 # Test for fusion repository
-if ((Test-Path "$flutterRoot\DEPS" -PathType Leaf) -and (Test-Path "$flutterRoot\engine\src\.gn" -PathType Leaf)) {
+if ([string]::IsNullOrEmpty($engineVersion) -and (Test-Path "$flutterRoot\DEPS" -PathType Leaf) -and (Test-Path "$flutterRoot\engine\src\.gn" -PathType Leaf)) {
     # Calculate the engine hash from tracked git files.
     $branch = (git -C "$flutterRoot" rev-parse --abbrev-ref HEAD)
     if ($null -eq $Env:LUCI_CONTEXT) {
@@ -34,15 +52,15 @@ if ((Test-Path "$flutterRoot\DEPS" -PathType Leaf) -and (Test-Path "$flutterRoot
     else {
         $engineVersion = (git -C "$flutterRoot" rev-parse HEAD)
     }
+}
 
-    if (($branch -ne "stable" -and $branch -ne "beta")) {
-        # Write the engine version out so downstream tools know what to look for.
-        $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
-        [System.IO.File]::WriteAllText("$flutterRoot\bin\internal\engine.version", $engineVersion, $utf8NoBom)
+if (($branch -ne "stable" -and $branch -ne "beta")) {
+    # Write the engine version out so downstream tools know what to look for.
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    [System.IO.File]::WriteAllText("$flutterRoot\bin\internal\engine.version", $engineVersion, $utf8NoBom)
 
-        # The realm on CI is passed in.
-        if ($Env:FLUTTER_REALM) {
-            [System.IO.File]::WriteAllText("$flutterRoot\bin\internal\engine.realm", $Env:FLUTTER_REALM, $utf8NoBom)
-        }
+    # The realm on CI is passed in.
+    if ($Env:FLUTTER_REALM) {
+        [System.IO.File]::WriteAllText("$flutterRoot\bin\internal\engine.realm", $Env:FLUTTER_REALM, $utf8NoBom)
     }
-}
+}

bin/internal/update_engine_version.sh

@@ -3,6 +3,9 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+# Want to test this script?
+# $ cd dev/tools
+# $ dart test test/update_engine_version_test.dart
 
 # ---------------------------------- NOTE ---------------------------------- #
 #
@@ -14,17 +17,18 @@
 
 set -e
 
-# Allow overriding the intended engine version via FLUTTER_ENGINE_VERSION.
+# Allow overriding the intended engine version via FLUTTER_PREBUILT_ENGINE_VERSION.
 #
 # This is for systems, such as Github Actions, where we know ahead of time the
 # base-ref we want to use (to download the engine binaries and avoid trying
-# to compute one below).
+# to compute one below), or for the Dart HH bot, which wants to try the current
+# Flutter framework/engine with a different Dart SDK.
 #
 # This environment variable is EXPERIMENTAL. If you are not on the Flutter infra
-# team, this code path might be removed at anytime and cease functioning. Please
-# file an issue if you have workflow needs.
-if [ -n "${FLUTTER_ENGINE_VERSION}" ]; then
-  ENGINE_VERSION="${FLUTTER_ENGINE_VERSION}"
+# or Dart infra teams, this code path might be removed at anytime and cease
+# functioning. Please file an issue if you have workflow needs.
+if [ -n "${FLUTTER_PREBUILT_ENGINE_VERSION}" ]; then
+  ENGINE_VERSION="${FLUTTER_PREBUILT_ENGINE_VERSION}"
   echo "[Unstable] Override: Setting engine SHA to $ENGINE_VERSION" 1>&2
 fi
 

dev/tools/pubspec.yaml

@@ -33,6 +33,8 @@ dev_dependencies:
   test: 1.25.14
   test_api: 0.7.4
 
+  file_testing: 3.0.2
+
   _fe_analyzer_shared: 76.0.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
   analyzer: 6.11.0 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
   boolean_selector: 2.1.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
@@ -64,4 +66,4 @@ dev_dependencies:
   web_socket_channel: 3.0.2 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
   webkit_inspection_protocol: 1.2.1 # THIS LINE IS AUTOGENERATED - TO UPDATE USE "flutter update-packages --force-upgrade"
 
-# PUBSPEC CHECKSUM: 1d50
+# PUBSPEC CHECKSUM: 7e9e