Merge pull request #413 from loopandlearn/add_release_script

marionbarker · web-flow · commit f0a3958429ae · 2025-06-26T11:01:15.000-07:00
Add a script to assist in release process for LoopFollow, LoopFollow_Second and LoopFollow_Third
diff --git a/README.md b/README.md
@@ -1,8 +1,9 @@
 > **Message from the Loop and Learn Team:**
-> * We have taken responsibility for updates to the Loop Follow app
-> * Additional Loop Follow documentation is at [Loop and Learn: Loop Follow](https://www.loopandlearn.org/loop-follow/)
+> * We have taken responsibility for updates to the LoopFollow app - many thanks to Jon Fawcett, the originator of this app
+> * Additional LoopFollow documentation is at [Loop and Learn: LoopFollow](https://www.loopandlearn.org/loop-follow/)
 > * If you are having problems with the app:
->     * Post in the [Loop and Learn Facebook group](https://www.facebook.com/groups/LOOPandLEARN); indicate that your question is related to Loop Follow
+>     * Please join the [LoopFollow Facebook group](https://www.facebook.com/groups/loopfollowlnl);
+>     * You can also post in the [Loop and Learn Facebook group](https://www.facebook.com/groups/LOOPandLEARN); but be sure to indicate that your question is related to LoopFollow
 >     * If you do not use Facebook - please click on this [link to file an Issue](https://github.com/loopandlearn/LoopFollow/issues) with your problem
 
 > **New location for LoopFollow Repository:**
@@ -11,37 +12,26 @@
 >    * GitHub should automatically redirect you to this new address
 >    * We have also modifed one branch and one file name to match standard conventions: _main_ (from _Main_) and _README.md_ (from _readme.md_)
 
-> **Message from Jon Fawcett:**
-> * Because our family now uses Omnipod 5, I will no longer be involved in updating LoopFollow
-> * I have transferred the _LoopFollow_ repository from the _JonFawcett_ to the _loopandlearn_ username
-> * I will also no longer provide an option for a TestFlight invitation from me. (Jon Fawcett)
->   * You must build the app yourself.
-
 > **Message to Developers**
 
 * Please click on this link: [For Developers](#for-developers)
 
-## Loop Follow 
-![screenshot](https://user-images.githubusercontent.com/38429455/93782187-436e8880-fbf8-11ea-8709-e2afba692132.png)
+## LoopFollow 
 
 ### Purpose:
 
-Using so many different apps as a parent or caregiver of a T1D can be very cumbersome. Add in the extra details from Looping
-and it can be a challenge flipping back and forth between apps. Each app has different strengths and weaknesses.
-- Spike is great for alarms. 
-- Spike and Sugarmate are great for the calendar complication on Apple Watch. 
-- Nightscout X or Nightscout in Safari are needed for intricate details from NS.
-- IFTTT and Pushover are  needed for Not Looping alerts.
+Using so many different apps as a parent or caregiver of a T1D can be very cumbersome. Add in the extra details from looping with an Open Source Automated Insulin Delivery app 
+and it can be a challenge flipping back and forth between apps. Each app has different strengths and weaknesses. LoopFollow melds together some needs into one app.
+
+An example of the main screen for LoopFollow is shown in the graphic below:
 
-And there are some functions I've always wished for and not found anywhere such a one-time temporary alert
-for those nights when Loop is stuck on high and you open loop with a correction. This lets you set a higher
-low alert for the BG you want to wake up to and close Loop.
+![example of main screen for LoopFollow](img/loopfollow-main-screen.png)}
 
 ### Building Options
 
-Please see [Loop and Learn: Loop Follow](https://www.loopandlearn.org/loop-follow/) for all the building options.
+Please see [Loop and Learn: LoopFollow](https://www.loopandlearn.org/loop-follow/) for all the building options.
 
-With the release of version 2.1.0, there is now an easy option for building up to three instances of the Loop Follow app for multiple Loopers in your family. Each instance can be configured to have the display name you choose with these names being the default:
+With the release of version 2.1.0, there is now an easy option for building up to three instances of the LoopFollow app for multiple Loopers in your family. Each instance can be configured to have the display name you choose with these names being the default:
 
 * LoopFollow
 * LoopFollow_Second
@@ -56,7 +46,7 @@ The _display_name_ is found in a single file.
 Summary instructions by build method:
 
 * Browser Build: 
-    * Fork and setup the repository for each Loop Follow instance you want to use: 
+    * Fork and setup the repository for each LoopFollow instance you want to use: 
         * https://github.com/loopandlearn/LoopFollow
         * https://github.com/loopandlearn/LoopFollow_Second
         * https://github.com/loopandlearn/LoopFollow_Third
@@ -69,55 +59,27 @@ Summary instructions by build method:
         *  LoopFollowDisplayNameConfig_Second.xcconfig 
         *  LoopFollowDisplayNameConfig_Third.xcconfig 
 
-#### Updates
+### Updates
 
-When modifications and versions are updated, there might be a slight delay for getting the second and third forks updated as well, so if you are using this feature, wait until all three repositories are updated.
+When modifications and versions are updated, you might see activity at GitHub. Please wait for the release message to be posted at [LoopFollow Releases](https://github.com/loopandlearn/LoopFollow/releases) before using the updated versions for the `main` branch of LoopFollow, LoopFollow_Second and LoopFollow_Third.
 
-### General feature list
+### Version Numbers
 
-Please review the list on [Loop and Learn: Loop Follow](https://www.loopandlearn.org/loop-follow/) which may be updated more frequently than this README.md file.
-
-Each time a release is made, the features added or bugs fixed are found at [Loop Follow Releases](https://github.com/loopandlearn/LoopFollow/releases).
-
-Each of the features below is selectable - you decide whether to use them.  Additionally, many features are adjustable because YDMV (your diabetes may vary).
-
-1. Scrollable/scalable graph display with BG, IOB, COB, Basal, Bolus, and the General Nightscout Care portal info
-    * Supports Glucose display when Dexcom is available but Nightscout is not
-    * Supports compatible data from Nightscout when the URL is provided (enable `Show Nightscout Settings` to see the URL, Token and Status rows)
-        * Loop: Loop status, Loop Prediction
-        * Trio and iAPS: status, Prediction lines, Autosens
-        * To remove the Data Table associated with NS, enter a blank line in URL
-2. Tap on Alarms on Toolbar to configure.
-    * Override DND (Do Not Disturb) and system volume for all alerts with a Snooze All Until and a Mute All Until
-    * List of Alarms covers the standard high/low/rise/fall/urgent glucose but also include alerts for missed glucose readings, if below configured glucose, IOB, COB, Not Looping, Overrides, Pump, Missed Bolus, SAGE, CAGE, Battery and Rec. Bolus
-    * Each Alarm has configurable settings including Sound selection, PreSnooze (set to be quiet At Night, During Day or Never) and Snooze Until and in some cases glucose ranges at which they are active
-3. Calendar entries (displayed on watch and/or carplay at 5 minute intervals) pre-formatted with two lines that the user can modify:
-    * BG, arrow, delta,  MINAGO (minutes ago for reading)
-    * COB, IOB, Basal (U/hr)
-4. Background silent audio is played to keep iOS from killing the app; this trick is why it can’t go into the App Store for a simple download and why Loop Follow puts an extra load on the phone battery
-5. Badge displays the current BG value on the app icon
-6. Information Display Settings allows user to configure the items selected and their order for the right panel when Nightscout URL is provided
-    * IOB, COB, Basal, Override, Battery, Pump, SAGE, CAGE, (Recommended) Rec. Bolus, (Glucose Eventually) Pred., Carbs today (Loop, Trio and iAPS)
-    * Autosens (Trio and iAPS only)
-7. Pull down on the glucose value to force a refresh from Nightscout (iPhone only - does not work on Mac)
-8. When adding a Nightscout site, NS Status says "Checking", "Site Not Found", "Token Required", "Invalid Token", or "OK"
-9. New with v2.1.2: Multiple Loopers (up to 3) are easily supported with either Browser Build or Mac-Xcode build
-10. New with v2.1.2: The app name (displayed on phone) can be customized when building
-    * If enabled, that custom name will be displayed on the main Loop Follow display
+Updates to the `main` branch (releases) have a version number that ends in 0; for example, 2.7.0.
 
-### Open Source DIY
-- This is a DIY open source project that may or may not function as you expect. You take full responsibility for building and running this app and do so at your own risk.
+* Immediately following the release, the `dev` branch is at the same version as `main` indicating the code is identical
+* Each time a feature is merged into the `dev` branch, the final number increments; for example, 2.7.1, 2.7.2
+* When the next release is made, the second digit is incremented and the final digit is restore to 0 for both `main` and `dev`; for example, 2.8.0
 
-## Versions
+### General feature list
 
-We added version numbers to Loop Follow. Typically the main branch and dev branch are at the same version, but when work is underway, the dev branch may have different code, which we try to indicate with a different version number.
+Please review the list on [Loop and Learn: LoopFollow](https://www.loopandlearn.org/loop-follow/).
 
-The versioning is:
+Each time a release is made, the features added or bugs fixed for that particular release are found at [LoopFollow Releases](https://github.com/loopandlearn/LoopFollow/releases).
 
-* major.minor.micro
-* For example our first version is 2.0.0
+### Open Source DIY
 
-For the most part, the deveopers keep main and dev branches at the same level. But sometimes we want to combine several PR or keep a modification in dev for additional testing.
+> This is a DIY open source project that may or may not function as you expect. You take full responsibility for building and running this app and do so at your own risk.
 
 ## For Developers
 
@@ -126,8 +88,27 @@ For the most part, the deveopers keep main and dev branches at the same level. B
 
 New PR are directed to the dev branch. If you direct one to main, we will move it to point to dev. So always start with your code aligned with dev.
 
-After a PR is merged to dev, the repository maintainers will bump up the verion number before merging to main - please do not modify the version in your branch.
+Always rename your branch (that is aligned with `dev`) to a name suitable for your feature, for example, `feature_name`, before starting to add commits to your branch.
+
+After a PR is merged to `dev`, there is an automatic bump up the version number - please do not modify the version in your branch.
+
+### Version Updates
+
+Only the maintainers for LoopFollow will update version numbers.
+
+### Release Process
+
+To assist in releasing to all three LoopFollow repositories, the script `release.sh` is now available. This bumps up the version number to M.N+1.0 for a minor release or M+1.0.0 for a major release. It also updates the LoopFollow_Second and LoopFollow_Third repositories with parallel changes to what was just released for LoopFollow. Only LoopFollow uses a `dev` branch. The other repositories use just the `main` branch and are kept at the released version.
+
+When a release is generated, the updates found in the `dev` branch are merged into `main`; the version number in the `Config.xcconfig` file is updated to A.B.O; a tag of the form v.A.B.0 is created and associated with the `main` branch at that time.
+
+When PR are subsequently merged to `dev`, the version number is incremented by 1 in the last place, e.g., "v.A.B.1" etc.
+
+### Files in LoopFollow Only
+
+There are several files found only in the LoopFollow repository:
 
-#### Version Updates
+* .github/workflow/auto_version_dev.yml
+* release.sh
 
-Only the maintainers for Loop Follow will update version numbers. This is done by incrementing the LOOP_FOLLOW_MARKETING_VERSION in Config.xcconfig file.
+These files are not added to _Second or _Third version because they are not needed for those repositories.
diff --git a/img/loopfollow-main-screen.png b/img/loopfollow-main-screen.png
diff --git a/release.sh b/release.sh
@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# ------------------------------------------------------------
+#  release.sh  – semi-automatic release helper
+# ------------------------------------------------------------
+set -euo pipefail
+set -o errtrace
+trap 'echo "❌  Error – aborting"; exit 1' ERR
+
+# -------- configurable -----------------
+APP_NAME="${1:-LoopFollow}"
+SECOND_DIR="${APP_NAME}_Second"
+THIRD_DIR="${APP_NAME}_Third"
+VERSION_FILE="Config.xcconfig"
+MARKETING_KEY="LOOP_FOLLOW_MARKETING_VERSION"
+DEV_BRANCH="dev"
+MAIN_BRANCH="main"
+PATCH_DIR="../${APP_NAME}_update_patches"
+# ---------------------------------------
+
+# --- functions here ---
+pause()     { read -rp "▶▶  Press Enter to continue (Ctrl-C to abort)…"; }
+echo_run()  { echo "+ $*"; "$@"; }
+
+push_cmds=()
+queue_push() { push_cmds+=("git -C \"$(pwd)\" $*"); echo "+ [queued] (in $(pwd)) git $*"; }
+
+queue_push_tag () {
+  local tag="$1"
+  queue_push push origin "refs/tags/$tag"
+}
+
+update_follower () {
+  local DIR="$1"
+  echo; echo "🔄  Updating $DIR …"
+  cd "$DIR"
+
+  # 1 · Make sure we’re on a clean, up-to-date main
+  echo_run git switch "$MAIN_BRANCH"
+  echo_run git fetch
+  echo_run git pull
+
+  # 2 · Apply the patch with 3-way fallback
+  if ! git apply --3way  --whitespace=nowarn "$PATCH_FILE"; then
+    echo "‼️  Some hunks could not be merged automatically."
+  fi
+
+  # 3 · Pause if any conflict markers remain
+  if git ls-files -u | grep -q .; then
+    echo "⚠️  Conflicts detected."
+    echo "    If Fastfile or build_LoopFollow.yml were modified, these are expected."
+    echo "    Open your merge tool, resolve, then press Enter."
+    pause
+  fi
+
+  # 4 · Single commit capturing all staged changes
+  git add -u
+  git add $(git ls-files --others --exclude-standard) 2>/dev/null || true
+  git commit -m "transfer v${new_ver} updates from LF to ${DIR}"
+
+  echo_run git status
+  pause                                     # build & test checkpoint
+  queue_push push origin "$MAIN_BRANCH"
+  cd ..
+}
+
+# ---------- PRIMARY REPO ----------
+PRIMARY_ABS_PATH="$(pwd -P)"
+echo "🏁  Working in $PRIMARY_ABS_PATH …"
+
+# --- start out in main to capture old_ver ---- 
+echo_run git switch "$MAIN_BRANCH"
+echo_run git fetch
+echo_run git pull
+
+# -------- version bump logic (unchanged) -----------
+old_ver=$(grep -E "^${MARKETING_KEY}[[:space:]]*=" "$VERSION_FILE" | awk '{print $3}')
+major_candidate="$(awk -F. '{printf "%d.0.0", $1 + 1}' <<<"$old_ver")"
+minor_candidate="$(awk -F. '{printf "%d.%d.0", $1, $2 + 1}' <<<"$old_ver")"
+
+echo
+echo "Which version bump do you want?"
+echo "  1) Major  →  $major_candidate"
+echo "  2) Minor  →  $minor_candidate"
+read -rp "Enter 1 or 2 (default = 2): " choice
+echo
+
+case "$choice" in
+  1) new_ver="$major_candidate" ;; ""|2) new_ver="$minor_candidate" ;;
+  *) echo "❌  Invalid choice – aborting."; exit 1 ;;
+esac
+
+echo "🔢  Bumping version: $old_ver  →  $new_ver"
+
+# --- switch to dev branch ----
+echo_run git switch "$DEV_BRANCH"
+echo_run git fetch
+echo_run git pull
+
+# --- update version number ----
+sed -i '' "s/${MARKETING_KEY}[[:space:]]*=.*/${MARKETING_KEY} = ${new_ver}/" "$VERSION_FILE"
+echo_run git diff "$VERSION_FILE"; pause
+echo_run git commit -m "update version to ${new_ver} [skip ci]" "$VERSION_FILE"
+
+echo "💻  Build & test dev branch now."; pause
+queue_push push origin "$DEV_BRANCH"
+
+# --- create a patch  ---------------------------
+mkdir -p "$PATCH_DIR"
+PATCH_FILE="${PATCH_DIR}/LF_diff_${old_ver}_to_${new_ver}.patch"
+
+git diff -M --binary "$MAIN_BRANCH" "$DEV_BRANCH"  \
+  > "$PATCH_FILE"
+
+# --- merge dev into main for new release
+echo_run git switch "$MAIN_BRANCH"
+echo_run git merge "$DEV_BRANCH"
+echo "💻  Build & test main branch now."; pause
+queue_push push origin "$MAIN_BRANCH"
+
+cd ..
+update_follower "$SECOND_DIR"
+update_follower "$THIRD_DIR"
+
+# ---------- GitHub Actions Test ---------
+echo; echo "💻  Test GitHub Build Actions and then continue."; pause
+
+# --- return to primary path
+cd ${PRIMARY_ABS_PATH}
+
+# ---------- push queue ----------
+echo; echo "🚀  Ready to tag and push changes upstream."
+echo_run git log --oneline -2
+
+read -rp "▶▶  Ready to tag? (y/N): " confirm
+if [[ $confirm =~ ^[Yy]$ ]]; then
+  git tag -a "v${new_ver}" -m "v${new_ver}"
+  queue_push_tag "v${new_ver}"
+  echo_run git log --oneline -2
+else
+  echo "🚫  tag skipped, can add later"
+fi
+
+read -rp "▶▶  Push everything now? (y/N): " confirm
+if [[ $confirm =~ ^[Yy]$ ]]; then
+  for cmd in "${push_cmds[@]}"; do echo "+ $cmd"; bash -c "$cmd"; done
+  echo "🎉  All pushes completed."
+  echo; echo "🎉  All repos updated to v${new_ver} (local)."
+  echo "👉  Remember to create a GitHub release for tag v${new_ver}."
+else
+  echo "🚫  Pushes skipped.  Run manually if needed:"; printf '   %s\n' "${push_cmds[@]}"
+  echo "🚫  Release not completed, pushes to GitHub were skipped"
+fi
