Merge pull request #849 from marionbarker/working-docs

Update alive branch information for 3.4.1

Author: marionbarker

docs/gh-actions/automatic.md

@@ -1,15 +1,24 @@
 ## Overview
 
-The instructions on the [Configure to Use Browser](gh-first-time.md) page will, unless you make a change, automatically take the following actions for released versions 3.4.0 and later:
+The instructions on the [Configure to Use Browser](gh-first-time.md) page will, unless you make a change, automatically take the following actions for released versions 3.4.1 and newer:
 
 * Update the version of your&nbsp;<span translate="no">fork</span>&nbsp;within a week of the change
     * When an update to the default `branch`, typically `main`, is detected, a new build is created automatically and uploaded to *TestFlight*
 * Build the app at least once a month and upload the fresh build to *TestFlight*
 
 If you do not want this automatic schedule, you can modify it.
 
+This only works because of special branches that are automatically created in your repository.
+
+* [What are the `alive branches` and why do I need them?](#what-are-the-alive-branches-and-why-do-i-need-them)
+
 Regardless of your choice, please [Disable Automatic Installation from *TestFlight*](gh-deploy.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.
 
+You still need to **take these actions** to ensure a recent build of the *Loop* app is available in *TestFlight* for you to install on your phone when you choose:
+
+* Keep your *Apple Developer* account up to date with agreements signed
+* [Renew Certificate](gh-update.md#renew-certificate){: target="_blank" } once a year
+
 ## Modify Automatic Building
 
 For someone using [development code](build-dev-browser.md) for their own use, they could decide to choose when to update their `fork` to the most recent commit. They can still have the advantage of automatic building without automatic updates; in other words, they want a new build added to TestFlight every month. There may be other configurations someone would choose. These options are available starting with Loop 3.3.0 (`dev` branch) and later.
@@ -101,3 +110,27 @@ What if I decide I don't want the automatic building feature?
     * It is the Build action that kicks off the update and build steps, so simply disabling the one action is sufficient
 
 * If you are done with Loop, you can delete the whole repository; but you should be sure about this because you'll need to start over with [Configure to Use Browser](gh-first-time.md) to restore ability to build Loop with GitHub.
+
+## What are the `alive branches` and why do I need them?
+
+The automatic update and build features of version 3.4.1 and later use branches that start with the name `alive`. You may see branches called `alive`, `alive-dev` and `alive-main` in your repository. These are automatically created. They are used to keep GitHub actions working in your repository.
+
+* GitHub keeps track of repositories
+* If there is no activity in a given repository in 60 days, GitHub disables Actions
+
+In other words, during a time when the *Loop* app is fairly stable, your automatic update and build features would just stop working.
+
+No one wants that. The `alive` branches are created and used to make sure at least one commit per month is added to an `alive` branch in your repository. That keeps your repository active to allow the automatic update and build process to work.
+
+The `alive` branches are only used for the keep-alive functions. Do not build using an `alive` branch. Most people will build using the default branch of `main`.
+
+#### Automatic Creation of `alive branch`
+
+The `alive` branch you need is created automatically when you run the `Build Loop` action.
+
+!!! warning "I got an error regarding a branch with `alive` in the name"
+    * Sometimes you get an error about an `alive` branch
+    * If you do get an error, simply delete the branch and run the `Build Loop` action again
+        * Use this [GitHub link](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch){: target="_blank" } or ask for help when deleting a branch
+    * You can delete every branch that starts with the name `alive`
+    * Leave the other branches alone unless a mentor directs you to take action

docs/gh-actions/build-dev-browser.md

@@ -89,18 +89,11 @@ If you have one branch as default, for example `main`, and choose to build a dif
     * Refresh the browser if you are unsure if the action started
     * Do not start a new action until the first one completes
 
-#### Automatic Creation of `alive branch`
-
-The `alive branch` is created automatically when you run the `Build Loop` action using the `dev branch` (version 3.3 or later). It is used as part of the automatic build process that will be released with the next version.
-
-??? warning "I got an error regarding the `alive branch` (click to open/close)"
-    * Sometimes you get an error about the `alive branch`
-    * If you do get an error, delete the `alive branch` and run the `Build Loop` action again
-        * Use this [GitHub link](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch){: target="_blank" } or ask for help when deleting a branch
-
 ## Automatic Update & Build
 
-The automatic update and build features of the development branch are only available if you set the `dev` branch as your default branch. Be sure to read the [Automatic Update & Build](automatic.md) if you did this.
+The [Automatic Update & Build](automatic.md){: target="_blank" } features are applied to the default branch of your repository. Normally this is the `main` branch. If you are a developer or tester who wants the `dev` branch to be built automatically, you must configure it as your default branch. Be aware that for this situation, you will not get automatic updates of released code.
+
+Most people should keep `main` as default and make a considered decision when to launch a manual build of the `dev` branch. At that time, it will automatically update to the latest `dev` commit unless you have modified your environment settings: [Modify Automatic Building](automatic.md#modify-automatic-building){: target="_blank" }.
 
 ## Change Default `Branch`
 
@@ -145,6 +138,6 @@ Your default branch has been changed.
 
 ## Automatic Update & Build
 
-The automatic update and build features are available for both the released (`main`) and development (`dev`) branch.
+The automatic update and build features are available for both the released (`main`) and development (`dev`) branch, but only for your default branch. For any other branch name set as your default branch, there is no automatic update available but the automatic build will run monthly.
 
 Be sure to read this page: [Automatic Update & Build](automatic.md){: target="_blank" }.

docs/gh-actions/gh-errors.md

@@ -41,6 +41,10 @@ These are some of the most common errors to date.
 1. You skipped running one of the actions
 1. You need to sign a program license agreement or update a credit card at&nbsp;<span translate="no">Apple Developer</span>
     * Be sure to read [Misleading Error Message](#misleading-error-message)
+1. You got an error regarding a branch with `alive` in the name
+    * You can delete any branch that starts with the name `alive` and try again
+    * See [Automatic Creation of `alive branch`](automatic.md#automatic-creation-of-alive-branch){: target="_blank" }
+
 
 ## Error Annotations
 

docs/gh-actions/gh-first-time.md

@@ -804,6 +804,12 @@ Refer to the graphic below for the numbered steps:
 
 The `Validate Secrets` &nbsp;<span class=notranslate>Action</span>&nbsp; should succeed or fail in a few minutes. Do not continue to the next step until this one succeeds.
 
+!!! tip "Hit Refresh"
+    After you tap the green Run workflow button, *GitHub* can be slow to update.
+
+    * Refresh the browser if you are unsure if the action started
+    * Do not start a new action until the first one completes
+
 * If you see the green check (:octicons-check-circle-fill-16:{: .passed })  continue to the next section
 * If you see the red `X` (:octicons-x-circle-fill-16:{: .failed }):
     * [Examine Annotation](gh-errors.md#examine-annotation){: target="_blank" } tells how to view the file needed to diagnose your problem.

docs/version/development.md

@@ -41,20 +41,15 @@ Note that the automatic build feature is opt-out. In other words, unless you tak
 
 It is suggested that all users of the released code (main branch), maintain this automatic schedule so they are never without a valid and up-to-date&nbsp;_<span translate="no">Loop</span>_&nbsp;in their  *TestFlight*  app.
 
-For users of the `dev` branch, it is not uncommon to disable the automatic update portion so they can choose when to update their development version, but should probably keep the monthly build portion of the process.
-
-* [Configure GH_PAT](https://github.com/LoopKit/LoopWorkspace/blob/dev/fastlane/testflight.md#gh_pat-workflow-permission){: target="_blank" }
-* [Modify Scheduled Building and Synchronization](https://github.com/LoopKit/LoopWorkspace/blob/dev/fastlane/testflight.md#modify-scheduled-building-and-synchronization){: target="_blank" }
-
 In addition to the easier to read error messages found with these updates, these additional simplifications include:
 
 * Actions are broken into logical components, each of which provides an easy to understand error message if it fails which includes a suggested fix
 * A new builder no longer needs to create the &nbsp;<span translate="no">Match-Secrets repository</span>
     * If it does not exist, one is created for you
     * Only the App Group ID must be added to the Identifiers; all other App services are    automatically added
-* For new builders and current 3.2.2 users updating to the next release
-    * The &nbsp;<span translate="no">alive</span>&nbsp; branch needed to enable automatic building is created automatically
-    * If their GH_PAT does not have `repo, workflow` permission, a prominent message is displayed with each Action completed
+* For new builders and current 3.2.3 users updating to the next release
+    * The branches with `alive` in the name required to enable automatic update and building are created automatically
+    * Make sure your GitHub repository is in sync with the LoopKit/LoopWorkspace repository
 
 These sections are still useful for version 3.5.0 `dev` users: