Merge pull request #911 from marionbarker/working-docs

Update instructions for adding enable Build Actions when necessary

Author: marionbarker

docs/browser/automatic.md

@@ -2,14 +2,44 @@
 
 The instructions provided for building with a browser include settings to automatically update and build for you.
 
-This keeps the most recent version of the *Loop* app available in *TestFlight* for you to install when you are ready.
+## Manual Action for Automatic Build
+
+!!! important "Automatic Build Requires Manual Action"
+    *GitHub* automatically **disables actions** that run according to a schedule if the repository in question is **inactive**.
+
+    What does that mean?
+
+    * **inactive** means stable code (no new commit within the last 60 days)
+    * **disables actions** means the Build Action shows up as disabled
+
+### What Manual Action is Required?
+
+For any repository that is stable, like the *Loop* app, you may need to take manual action to keep automatic builds flowing every month.
+
+* Put a calendar reminder to check every month on the 2nd day of the month (or later)
+    * Check that *TestFlight* has a new build of the *Loop* (or other) app
+    * If not, go to your repository to see if the build action is disabled
+* If necessary, enable the build action at your repository as shown in the graphic below and then launch a manual build
+
+![fix a disabled build state](img/build-disabled-fix.png )
+
+This keeps the most recent version of your app available in *TestFlight* for you to install when you are ready. This manual enable step should be required no more frequently than every 60 days, however, best to make it a monthly habit to check.
+
+> Builds in *TestFlight* are good for 90 days before they [expire](../operation/features/notifications.md#loop-app-expiration-notification){: target="_blank" }.
+
+## What is Automatic
 
 These events are automatically scheduled:
 
 * Once a week: Check for a new release of the *Loop* app:
     * If found, your fork is automatically updated and a new build created and uploaded to *TestFlight*
 * Once a month: Build the app and upload the fresh build to *TestFlight*
 
+!!! important "You Get No Warning if Repository Build Action is Disabled"
+    These automatic actions happen on schedule, but if your build action is disabled, no build actually happens, no warning email is sent and a green checkmark (✅) appears beside a very short build action in which the actual build was skipped.
+
+    * Refer to [What Manual Action is Required?](#what-manual-action-is-required)
+
 If you do not want this automatic schedule, you can modify it.
 
 Regardless of your choice, please [Disable Automatic Installation from *TestFlight*](phone-install.md#disable-automatic-install-from-testflight){: target="_blank" }. You should be alert any time your *Loop* app is updated. Check that all settings are maintained and pay attention to make sure the app behavior is nominal.
@@ -36,6 +66,11 @@ In that case, you should check your favorite information site to find out what t
 
 On the first day of every month, you will see a successful `build action`. The purpose of this build is to provide a recent version of the app in *TestFlight* so you are never in a situation where you have no app on your phone.
 
+!!! important "You Get No Warning if Repository Build Action is Disabled"
+    If your build action is disabled, no build actually happens, no warning email is sent and a green checkmark (✅) appears beside a very short build action in which the actual build was skipped.
+
+    * Refer to [What Manual Action is Required?](#what-manual-action-is-required)
+
 You start getting [Notifications](../operation/features/notifications.md#loop-app-expiration-notification){: target="_blank" } when there are fewer than 20 days until expiration. When you see the warning, install the newest build from your *TestFlight* app. You do not want to get the dreaded "Loop Beta is not available" message on your phone. (The warnings get very agressive when close to expiration.)
 
 ### What are the `alive branches`?

docs/browser/bb-errors.md

@@ -170,6 +170,14 @@ Ignore the warnings - this does not affect the build.
 
     This affected all the Open-Source apps in our community - Loop, LoopFollow, LoopCaregiver, Trio, iAPS and xDrip4iOS. The developers in our community have restored the ability to build using the Browser Build method. Stay tuned for updates to required actions in the documentation over the next few months, before we hit the 60 day limit.
 
+### Manual Enable for Build Action May be Required
+
+The automatic build actions continue to happen on schedule, but starting May 2025, you may find your build action disabled by *GitHub*. (This might happen every 60 days, but it might happen sooner.) In that case, no build actually happens, no warning email is sent and a green checkmark (✅) appears beside a very short build action in which the actual build was skipped.
+
+If necessary, enable the build action at your repository as shown in the graphic below and then launch a manual build.
+
+![fix a disabled build state](img/build-disabled-fix.png )
+
 ### Rebuild: Create Certificates Error
 
 With `Loop 3.6.0`, these should be a thing of the past - but you must first manually update (sync) your repository in order to get this feature added and you must do this new step [Add Variable](prepare-fork.md#add-variable){: target="_blank" }

docs/browser/bb-overview.md

@@ -122,6 +122,7 @@ These considerations were prepared when most people were using a Mac computer to
 * Automatic Updates are loaded into *TestFlight*
     * With version 3.4 and newer, builds are automatically prepared at least once a month
     * You choose when to install the new app from TestFlight onto your phone
+    * **WARNING:** starting May 2025, [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" } may be required - be sure to check monthly to see if you need to start a build manually
 * Manual Updates are easy
     * Starting an update takes a few minutes of your time; it can be done from your phone; the rest is automatic and is done in about an hour
 * After the *GitHub* Build starts, your app is ready to install on your *iPhone* in about an hour

docs/browser/bb-update.md

@@ -8,6 +8,8 @@
 
 **For most, the *Loop* app is configured for automatic build, so you only need to come to this page if the automatic build failed.**
 
+**WARNING: starting May 2025, [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" } may be required - be sure to check monthly to see if you need to start a build manually.**
+
 ???+ info "Time Estimate (click to open/close)"
     Manually update and build the *Loop* App
 
@@ -161,17 +163,18 @@ The bullets below show typical messages when you are building the `main` branch.
 
 #### Build the App
 
-Refer to graphic below as you follow the steps to build the *Loop* app.
+Refer to graphic below as you follow the steps to build the *Loop* app. The numbers highlighted in the graphic correspond to numbers in parentheses in the bullet list below:
 
-* Click on the `Actions` tab
-* Select the `4. Build Loop` workflow on the left
+* (1) Click on the `Actions` tab
+* (2) Select the `4. Build Loop` workflow on the left
     * If using a mobile browser, be sure to use landscape mode to more closely match how *GitHub* looks on a computer.
-* Look on the right and click `Run workflow` to  see the dropdown
-* Click on the green `Run workflow` button in the dropdown
+* If you notice your build action is disabled, you must (3) click on `Enable workflow`
+* (4) Look on the right and click `Run workflow` to  see the dropdown
+* (5) Click on the green `Run workflow` button in the dropdown
 * Wait ~25 min for the build to complete successfully
 * It is then processed by *Apple* and sent to *TestFlight* (be patient)
 
-![graphic indicating how to build again](img/github-build-actions-build-again.svg){width="700"}
+![graphic indicating how to build again](img/build-disabled-fix.png){width="700"}
 {align="center"}
 
 #### What if the Build Fails

docs/browser/build-dev-browser.md

@@ -70,7 +70,7 @@ Tap the `Code` button (upper left) and ensure this branch in your `fork` is up t
 
 Look in this section for one-time changes for building `dev` with a browser that require special, one-time actions.
 
-With the release of version 3.4, no one-time changes are required. This assumes you built main after the release of 3.4.
+No one-time changes are required. This assumes you built main after the release of 3.6.
 
 ### Build `Branch`
 
@@ -148,19 +148,21 @@ As soon as you build one version of the app from the `dev` branch, that version
 
 Suppose you then return to using the `main` branch after your excursion to the `dev` branch.
 
-> *For this example, version 3.4.4 is the released version from the `main` branch and version 3.5.0 is the development version you evaluated.*
+> *For this example, version 3.6.x is the released version from the `main` branch and version 3.7.0 is the development version you evaluated.*
 
-Every time you open TestFlight on your phone and select the *Loop* app, it will offer the most recent 3.5.0 version to be installed if you just tap **Install**. You might be in a situation where that build is about to expire or you decide you don't want to test this on your looping phone. In some cases, the released version, 3.4.4, might have fixes that are not available in a development branch.
+Every time you open TestFlight on your phone and select the *Loop* app, it will offer the most recent 3.7.0 version to be installed if you just tap **Install**. You might be in a situation where that build is about to expire or you decide you don't want to test this on your looping phone.
 
 You have your choice:
 
-* You can manually go into TestFlight each time `main` is automatically built, Select Previous Builds, then choose 3.4.4 and install the top listing
+* You can manually go into TestFlight each time `main` is automatically built, Select Previous Builds, then choose 3.6.x and install the top listing
 * You can log in at: [App Store Connect: Apps](https://appstoreconnect.apple.com/apps){: target="_blank" }
     * Select your *Loop* app
     * Click on the TestFlight tab
-    * For each 3.5 build, click on the row for a build
+    * For each 3.7 build, click on the row for a build
         * Select Expire Build on upper right
-    * This leaves only the released version, 3.4.4 for this example, available in TestFlight on your phone
+    * This leaves only the released version, 3.6.x for this example, available in TestFlight on your phone
+
+> The example graphic below was created when 3.4.4 was the released version
 
 ![expire builds with higher version numbers](img/testflight-expire-dev.png){width="700"}
 {align="center"}

docs/browser/img/build-disabled-fix.png

@@ -50,6 +50,7 @@
 ???+ question "FAQs (click to open/close)"
     - **Do I need a Mac computer?** No. This can be done on any browser, although it will be easier using a computer or tablet than just using a phone.
     - **Isn't it hard to build every 90 days?** The initial setup and installation take a lot of your focused time. But once you build, future updates and builds are automatic. You just need to keep your Apple Developer account up to date. Review any email that says a GitHub action failed - read the error and take action. For more information, see [Automatic Update & Build](automatic.md){: target="_blank" }.
+    - **When do I have to kick off my automatic build?** Starting in May 2025, you may need to take an extra action after 60 days with no updates to the app: [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" } 
     - **Can you explain the new automatic building?** There's a whole page on [Automatic Update & Build](automatic.md){: target="_blank" } for more explanations
     - **Can I use this for my child?** You, as the adult, can install using *TestFlight* on your child's phone. The explicit steps are provided at [Install on Phone: *TestFlight* for a Child](phone-install.md#testflight-for-a-child){: target="_blank" }.
     - **Can I still use my customizations?** Yes. [Customize using Browser](custom-browser.md){: target="_blank" }
@@ -69,7 +70,7 @@ The steps to configure for building with a browser require a lot of focused atte
 
     When you use an organization, you don't have to add 6 Secrets to each repository for every app you build. It can save a lot of time in the long run.
 
-    * Even if you just build Loop and nothing else, using an organization is pretty easy and your build works just the same as using only a personal account
+    * Even if you just build Loop and nothing else, using an organization is pretty easy and your build works just the same as using only a personal account - but there is no particular advantage (until you decide maybe you do want to build another app)
     * Who should definitely build with an organization:
         * Anyone who is a caregiver will want LoopCaregiver or LoopFollow or both
         * Anyone who wants to use LoopFollow for the amazing alarm capabilties
@@ -156,10 +157,16 @@ First some handy username and password information:
 <your information here>
 suggest you use your desired password tool to save the password for this account
 
-## GitHub username
+## GitHub personal account username
 <your information here>
 suggest you use your desired password tool to save the password for this account
 
+### GitHub organization name
+<your GitHub organization name>
+Using an organization is optional.
+But it you do use one, add the name here for reference.
+You always log in using your GitHub personal account to access your organization.
+
 There are Six Secrets and One Variable:
  - the list below shows the expected format of each.
 You can replace each prototype with your secret as you gather them,
@@ -233,7 +240,8 @@ Some of these **terms** have ToolTips, so hover your mouse over those - or revie
 * Some terms in the Glossary are not in alphabetical order to improve logical grouping. All the individual <code>Secrets</code> are listed after <code>Secrets</code> in the Glossary.
 
 * `Actions`: available in your *GitHub* repositories to build your app
-    * You must be logged in to *GitHub* to run the actions
+    * You must be logged in to *GitHub* to run the actions manually
+    * The build action is automatically run for you once your repository is configured
 * `Fork`: you make a copy of the code needed to build an app and store it in your *GitHub* account (using a free *GitHub* organization is recommended for storing your `forks`)
 * <code>Secrets</code>: are required to enable *GitHub* to build an app from a repository using *GitHub* Actions
     * Six <code>Secrets</code> must be entered to enable your app (or apps) to build

docs/browser/img/github-build-actions-build-again.svg

@@ -19,6 +19,8 @@ If you are coming to this page to update one of the other apps, follow the [How
 
 > If you have not added the `Variable` `ENABLE_NUKE_CERTS`, do it now. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }.
 
+**WARNING: starting May 2025, [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" } may be required - be sure to check monthly to see if you need to start a build manually.**
+
 ### Multiple Copies of `LoopFollow`
 
 For the convenience of caregivers who use `LoopFollow` to monitor multiple people, updates were added in v2.1.2 to make this more convenient. This works regardless of the build method. (Build with Browser or [Build with *Mac*](https://www.loopandlearn.org/loop-follow#lf-script){: target="_blank" }).
@@ -388,7 +390,7 @@ Refer to the graphic below for the first four steps:
 
 1. Wait a few minutes to make sure there is not an early failure
     * If you see the red `X` (:octicons-x-circle-fill-16:{: .failed }):
-        * Use the Browser Build Errors page to resolve the error, then repeat the Action
+        * Use the Browser Build Errors page (which uses LoopWorkspace repository) to resolve the error, substituting the repository name for the app you are building, then repeat the Action
         * [Quick Reference for Browser Build Errors](bb-errors.md#quick-reference-for-browser-build-errors){: target="_blank" }
 1. If the process appears to be happening without an error, go do something else for a while. The build should take less than half an hour (these tend to build faster than the *Loop* app.
     * When you see the green check (:octicons-check-circle-fill-16:{: .passed }) continue

docs/browser/intro-summary.md

@@ -66,6 +66,13 @@ The instructions on the [Configure to Use Browser](intro-summary.md){: target="_
     * This is only for the `default` branch, typically `main`
 * Build the app at least once a month and upload it to *TestFlight*
 
+!!! important "You Get No Warning if Repository Build Action is Disabled"
+    Alert - this issue is new as of May 2025. Your build action might be disabled by *GitHub*, which means you need to enable it manually.
+
+    If your build action is disabled, no build actually happens, no warning email is sent and a green checkmark (✅) appears beside a very short build action in which the actual build was skipped.
+
+    * Refer to [Manual Action for Automatic Build](automatic.md#manual-action-for-automatic-build){: target="_blank" }
+
 Unless you make the recommended one-time change to [Disable Automatic Install from *TestFlight*](#disable-automatic-install-from-testflight), the default setting for each app found in *TestFlight* is to:
 
 * Install each new build from *TestFlight* on the phone as soon as it is detected