build: pin flutter SDK version

sketch of a .envrc for using fvm's flutter
add notes in notice
add note to comment out check flutter version
update README

.envrc

@@ -0,0 +1,27 @@
+# This file is used by direnv to setup the environment when entering to use fvm's flutter.
+
+# Comment out the next line if you want to use your system flutter.
+PATH_add .fvm/flutter_sdk/bin
+
+# Check flutter version matches what's in .fvmrc
+check_flutter_version() {
+  local fvm_flutter_version_string=$(cat .fvmrc)
+  # Fetch string from format `"flutter": "18340ea16c"``
+  local fvm_flutter_version=$(echo "$fvm_flutter_version_string" | grep -o '"flutter": "[a-z0-9]*"' | cut -d '"' -f 4)
+
+  local flutter_version_string=$(flutter --version)
+  # Fetch string from format `Framework • revision 11c034f037`
+  local flutter_version=$(echo $flutter_version_string | grep -o 'Framework • revision [a-z0-9]*' | cut -d ' ' -f 4)
+
+  if [ "$fvm_flutter_version" != "$flutter_version" ]; then
+    echo "Flutter version mismatch: $fvm_flutter_version != $flutter_version"
+    echo "Expected Flutter version: $fvm_flutter_version"
+    echo "Actual Flutter version: $flutter_version"
+    echo "Run 'fvm install' to fix this or see README on Setup."
+    return 1
+  fi
+}
+
+# Check flutter version when entering directory
+# Comment this out at your own risk if you want to use a custom flutter version.
+check_flutter_version

.fvmrc

@@ -0,0 +1,4 @@
+{
+  "flutter": "18340ea16c",
+  "updateVscodeSettings": false
+}

.github/workflows/ci.yml

@@ -8,15 +8,32 @@ jobs:
     steps:
     - uses: actions/checkout@v3
 
-    - name: Clone Flutter SDK
-      # We can't do a depth-1 clone, because we need the most recent tag
-      # so that Flutter knows its version and sees the constraint in our
-      # pubspec is satisfied.  It's uncommon for flutter/flutter to go
-      # more than 100 commits between tags.  Fetch 1000 for good measure.
+    - name: Set up Homebrew
+      id: set-up-homebrew
+      uses: Homebrew/actions/setup-homebrew@master
+
+    # - name: Clone Flutter SDK
+    #   # We can't do a depth-1 clone, because we need the most recent tag
+    #   # so that Flutter knows its version and sees the constraint in our
+    #   # pubspec is satisfied.  It's uncommon for flutter/flutter to go
+    #   # more than 100 commits between tags.  Fetch 1000 for good measure.
+    #   run: |
+    #     git clone --depth=1000 https://github.com/flutter/flutter ~/flutter
+    #     TZ=UTC git --git-dir ~/flutter/.git log -1 --format='%h | %ci | %s' --date=iso8601-local
+    #     echo ~/flutter/bin >> "$GITHUB_PATH"
+
+    - name: Install FVM
       run: |
-        git clone --depth=1000 https://github.com/flutter/flutter ~/flutter
-        TZ=UTC git --git-dir ~/flutter/.git log -1 --format='%h | %ci | %s' --date=iso8601-local
-        echo ~/flutter/bin >> "$GITHUB_PATH"
+        brew tap leoafarias/fvm
+        brew install fvm
+
+    - name: Install Flutter SDK
+      run: |
+        fvm install
+        fvm use
+
+    - name: Load direnv (.envrc)
+      uses: HatsuneMiku3939/direnv-action@v1
 
     - name: Download Flutter SDK artifacts (flutter precache)
       run: flutter precache --universal

.gitignore

@@ -49,3 +49,6 @@ app.*.map.json
 
 # Old scaffolding hack
 lib/credential_fixture.dart
+
+# FVM Version Cache
+.fvm/

.vscode/settings.json

@@ -17,4 +17,5 @@
 
   // This much more focused automatic fix is helpful, though.
   "files.trimTrailingWhitespace": true,
+  "dart.flutterSdkPaths": [".fvm/flutter_sdk"],
 }

README.md

@@ -91,27 +91,50 @@ Two specific points to expand on:
 ## Getting started in developing this beta app
 
 ### Setting up
-
-1. Follow the [Flutter installation guide](https://docs.flutter.dev/get-started/install)
-   for your platform of choice.
-2. Switch to the latest version of Flutter by running `flutter channel main`
-   and `flutter upgrade` (see [Flutter version](#flutter-version) below).
+> [!NOTE]
+> (Advanced Users) If you want to manage own flutter SDK installation, you can skip step 1-2. See below section on [Flutter version](#flutter-version)
+
+1. Install [direnv][direnv] and [fvm][fvm], for most
+users, you can use Homebrew:
+
+  ```sh
+  brew install direnv
+  # Follow instructions for to add the hook https://direnv.net/docs/hook.html
+  brew tap leoafarias/fvm
+  brew install fvm
+  # Close and open a new terminal to ensure that direnv is loaded.
+  # For any changes in the contents of direnv, and first use, you need to call
+  # this.
+  direnv allow
+  ```
+2. Run `fvm use` to setup the flutter version.
 3. Ensure Flutter is correctly configured by running `flutter doctor`.
 4. Start the app with `flutter run`, or from your IDE.
 
 
 ### Flutter version
 
-While in the beta phase, we use the latest Flutter from Flutter's
-main branch.  Use `flutter channel main` and `flutter upgrade`.
-
-We don't pin a specific version, because Flutter itself doesn't offer
-a way to do so.  So far that hasn't been a problem.  When it becomes one,
-we'll figure it out; there are several tools for this in the Flutter
-community.  See [issue #15][].
-
-[issue #15]: https://github.com/zulip/zulip-flutter/issues/15
-
+We use [direnv][direnv] and [fvm][fvm] to ensure that the version of flutter SDK
+that you're using matches what has been tested on CI, and across developer
+setups.
+The Flutter version pinned for the current build is in the [.fvmrc](.fvmrc)
+file under the `flutter` key. It can either be a hash like
+[`18340ea16c`](https://github.com/flutter/flutter/commit/18340ea16c) or a
+version number like `3.21.0-11.0.pre`.
+
+However, if you want to manage your own flutter SDK version you can opt out of
+this behavior.
+Do note that if you do this, you need to manually make sure that the flutter SDK
+version matches or is compatible with the pinned version in `.fvmrc`. Otherwise,
+the build can fail as we have not tested the current code with that particular
+flutter SDK version.
+
+If you want manage your own flutter SDK version, follow the [Flutter
+installation guide](https://docs.flutter.dev/get-started/install) for your
+platform of choice.
+
+[direnv]: https://direnv.net/
+[fvm]: https://fvm.app/
 
 ### Tests