Merge pull request #902 from marionbarker/working-docs

marionbarker · web-flow · commit 550d694012fc · 2025-04-07T16:31:11.000-07:00
Browser Build: remove old 3.2 to 3.4 update section, update information about certificate renewal
diff --git a/docs/browser/automatic.md b/docs/browser/automatic.md
@@ -65,6 +65,64 @@ The `alive` branch you need is created automatically when you run the `Build Loo
     * You can delete every branch that starts with the name `alive`
     * Leave the other branches alone unless a mentor directs you to take action
 
+## Automatic Certificates
+
+Coming soon with `Loop 3.6.0`. 
+
+Already here with `LoopFollow 2.3.0` and some other Open-Source apps.
+
+### Requirements
+
+You must have the `ENABLE_NUKE_CERTS` variable set to `true` for your *GitHub* organization, or when using a personal account to build, add it to each repository.
+
+* Refer to [Add Variable](prepare-fork.md#add-variable){: target="_blank" }
+
+### Certificates and `Match-Secrets`
+
+The Create Certificates action does the following:
+
+* Reads existing signing credentials from your `Match-Secrets` private respository and confirms if they are valid
+* OR
+* Uses your `Distribution` Certificate from *Apple* or creates a new one if one does not exist
+* Securely stores, in  your `Match-Secrets` private repository, signing credentials (like certificates and provisioning profiles from *Apple*) used for code signing for each Identifier in your app when you build
+
+### Annual Renewal
+
+This happens once a year after *Apple* automatically expires your `Distribution` Certificate.
+
+* When the *Apple* `Distribution` certificate expires, the saved credentials in your `Match-Secrets` private repository are invalid and need to be removed (<code>nuke</code>)
+* You need a new `Distribution` Certificate at *Apple*
+* You need to create new signing credentials for `Match-Secrets`
+
+For the `Loop` app, up through version 3.4.4, you need to do this process manually.
+
+### Automatic Certificate Renewal
+
+Some Open-Source apps, in particular `Trio` and `LoopFollow 2.3.0` already have this capability.
+
+* If your signing credentials for the app being built are invalid and `ENABLE_NUKE_CERTS` is `true`, then signing credentials will be cleared from your `Match-Secrets` repository, a new `Distribution` certificate will be created at *Apple* and signing credentials for the current app will be generated and stored in `Match-Secrets`.
+
+* Next app you build will need certificates created because all signing credentials were cleared out of your `Match-Secrets` repository
+    * If that app is configured for automatic certificate renewal, you only need to run the `Build Action`; it detects no signing credentials are available and creates them
+    * If that app is not configured for automatic certificate renewal, you must first run the action  `Create Certificates` and then `Build`
+
+### Open-Source App Schedule
+
+Each Open-Source App has a schedule for when the automatic build happens. This determines when the automatic check for certificate status happens.
+
+The times are shifted to make sure only one Open-Source app performs a `nuke` process at one time. This only happens once a year, but we wanted to be sure there are no conflicts. Even if an app doesn't have automatic certificates implemented yet, they are added to the table as suggested values to use when this capability gets added. All times are UTC. If other apps decide to add this feature, please make a pull request to LoopDocs so we can add those times to the deconfliction table.
+
+| Open-Source App | AutoCerts? | Wed Time | 1st of Month Time |
+|:--|:-:|--:|--:|
+| <span translate="no">Loop</span> | `dev` only | 09:00 | 07:00 |
+| <span translate="no">LoopCaregiver</span> | n | 13:00 | 11:00 |
+| <span translate="no">LoopFollow</span> | y | 12:00 | 10:00 |
+| <span translate="no">LoopFollow_Second</span> | y | 12:20 | 10:20 |
+| <span translate="no">LoopFollow_Third</span> | y | 12:40 | 10:40 |
+| <span translate="no">Trio</span> | y | 08:00 | 06:00 |
+| <span translate="no">xDrip4iOS</span> | n | 16:00 | 14:00 |
+
+
 ## 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.
diff --git a/docs/browser/bb-update.md b/docs/browser/bb-update.md
@@ -6,8 +6,10 @@
 
 > Regardless of build method, this is an **update** and will install over your existing app; your **settings are maintained including your current CGM and Pump.**
 
+**For most, the *Loop* app is configured for automatic build, so you only need to come to this page if the automatic build failed.**
+
 ???+ info "Time Estimate (click to open/close)"
-    Build the *Loop* App
+    Manually update and build the *Loop* App
 
     - 5 min: Check *Apple* account status
     - Check if you need to renew certificates (once a year only)
@@ -21,6 +23,7 @@
 
     * 5 min: Clear out expired certificates
     * 5 min: Generate new certificates
+    > When Loop 3.6.0 is released, certificate renewal will be automatic once you [Add Variable](prepare-fork.md#add-variable){: target="_blank" }
 
     One Time: Complete the information for the Digital Service Act Compliance
 
@@ -32,7 +35,6 @@
 
     Most users will start at [How to Update or Rebuild](#how-to-update-or-rebuild):
 
-    * If currently using verion 3.2.3 or earlier, there are manual steps included to update to 3.4
     * If currently using verion 3.4.0 or later, builds are automatic but you still need to do some actions:
         * Your *Apple Developer* account must be active
         * All agreements must be signed for your *Apple Developer* account
@@ -115,6 +117,8 @@ Digital Service Act Compliance
 
 > This is Step 2 of 6 - it is only needed once a year - you should get an email from Apple 30 days before your `Distribution Certificate` expires. (Don't worry if you did not see the email.)
 
+> If you have not added the `Variable` `ENABLE_NUKE_CERTS`, do it now. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }. Once `Loop 3.6.0` is released, your fork is updated and you set up that variable, you can skip this step - it will be automatic.
+
 **Apps in TestFlight are not affected when a certificate expires or is revoked.**
 
 * Apps installed on the phone continue to run
@@ -222,95 +226,6 @@ The bullets below show typical messages when you are building the `main` branch.
 
 > This is Step 4 of 6 - this is always required.
 
-### Update from 3.2.x to 3.4
-
-For the update from 3.2.x to 3.4, you must do more than "just" build. If you skip this step - the build will fail.
-
-* The `Identifier` for the "`widget`" changed from "`SmallStatusWidget`" to the more descriptive "`LoopWidgetExtension`"
-
-> If you built version 3.3.0 (the `dev branch` before release of version 3.4) or newer, you can skip ahead to [Build the App](#build-the-app).
-
-You will (1) run [`Add Identifiers`](#add-identifiers), (2) [add the `App Group`](#add-app-group-to-new-identifier) to the new identifier, (3) run [`Create Certificates`](#create-certificates) and then (4) run [`Build Loop`](#build-the-app).
-
-#### Add Identifiers
-
-In your fork of LoopWorkspace:
-
-* Run the Action: `Add Identifier`
-* Wait for it to succeed
-
-??? tip "Detailed instructions for `Add Identifier` (Click to open/close)"
-    Refer to the graphic below for the numbered steps:
-
-    1. Click on the `Actions` tab of your <code>LoopWorkspace</code> repository
-    1. On the left side, click on 2. <code>Add Identifiers</code>
-    1. On the right side, click `Run Workflow` to show a dropdown menu
-        * You will see your default branch (typically this is `main`)
-    1. Tap the green button that says `Run workflow`.
-
-        ![add identifiers using github actions](img/action-02-add-identifiers.svg){width="700"}
-        {align="center"}
-
-    The `Add Identifiers` &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.
-
-    * 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 }):
-        * [Action: Add Identifiers Errors](bb-errors.md#action-add-identifiers-errors){: target="_blank" } tells you what to search for in the file
-        * Resolve the error and repeat `Add Identifiers`
-
-#### Add `App Group` to New `Identifier`
-
-Open the [Certificates, Identifiers & Profiles: Identifiers List](https://developer.apple.com/account/resources/identifiers/list){: target="_blank" } page.
-
-Click on the "`LoopWidgetExtension`" identifier to open the `Edit Your App ID Configuration` screen.
-
-| `NAME` | `IDENTIFIER` |
-|-------|------------|
-| `Loop Widget Extension` | `com.TEAMID.loopkit.Loop.LoopWidgetExtension` |
-
-The graphic below has numbered steps that match these directions:
-
-1. Looking at the `App Services` column, scroll down to the `App Groups` row and ensure the check box (under the `Capabilities column`) for `App Groups` is checked
-2. If the word `Configure` shows up, tap on it
-    * This opens the `App Group Assignment` screen
-    * If it said `Edit` instead of `Configure` - you can click to confirm you have the correct App Group but won't need to continue or save if it is correct
-3. Check the box by `Loop App Group` that uses your `TEAMID` in `group.com.TEAMID.loopkit.LoopGroup`
-    * Note that if you previously built with Xcode, the name may be different, i.e., `XC group com TEAMID loopkit LoopGroup`
-4. Tap `Continue`
-5. Tap `Save`
-
-![graphic showing selection of the correct App Group](img/update-identifier-loop-3-4.png){width="700"}
-{align="center"}
-
-If you did not need to make changes, the `Save` button will not be active.
-
-* Tap on the `< All Identifiers` link at the top left
-
-The full list of Identifiers should be displayed again.
-
-!!! note "Other Identifiers"
-    All other identifiers should be already set up.
-
-    * If they are not, refer to [Configure to Use Browser: Add App Group to Identifiers](prepare-app.md#add-app-group-to-identifiers){: target="_blank" }
-
-#### Create Certificates
-
-You must run the action `Create Certificates` again because the `Identifiers` were updated. Wait for this to succeed before trying to build.
-
-???+ tip "Detailed instructions (Click to open/close)"
-    Refer to the graphic below for the numbered steps:
-
-    1. Click on the "<code>Actions</code>" tab of your <code>LoopWorkspace</code> repository
-    1. On the left side, click on "`Create Certificates`"
-    1. On the right side, click "`Run Workflow`" to show a dropdown menu
-        * You will see your default branch (typically `main`)
-    1. Tap the green button that says "`Run workflow`".
-
-        ![create certificates using github actions](img/action-03-create-certs.svg){width="700"}
-        {align="center"}
-
-    1. Wait a minute or two for the action to finish
-
 #### Build the App
 
 Refer to graphic below as you follow the steps to build the *Loop* app.
@@ -328,7 +243,9 @@ Refer to graphic below as you follow the steps to build the *Loop* app.
 
 #### What if the Build Fails
 
-If a new release is announced at [Current Release](../version/releases.md#current-release){: target="_blank" }, look to see if there are instructions about extra steps required with the release. ([Updating from 3.2.3 to 3.4.x](#update-from-32x-to-34) requires extra steps described above.)
+If a new release is announced at [Current Release](../version/releases.md#current-release){: target="_blank" }, look to see if there are instructions about extra steps required with the release. 
+
+> When `Loop 3.6.0` is released, if you customized your Loop app, you may need to discard your customization and manually sync your `fork`. Check out the [Ahead and Behind](#ahead-and-behind) instructions.
 
 If you are using the dev branch, the update steps are the same, but review information on this page: [Build Loop dev with Browser](build-dev-browser.md){: target="_blank" }.
 
diff --git a/docs/browser/other-apps.md b/docs/browser/other-apps.md
@@ -17,6 +17,8 @@ The same technique is used and the same six <code>Secrets</code> are used for ma
 
 If you are coming to this page to update one of the other apps, follow the [How to Update or Rebuild](bb-update.md#how-to-update-or-rebuild){: target="_blank" } instructions provided for the *Loop* app, but substitute the repository name for the app you want to rebuild for all references to&nbsp;*<span translate="no">LoopWorkspace</span>*.
 
+> If you have not added the `Variable` `ENABLE_NUKE_CERTS`, do it now. See [Add Variable](prepare-fork.md#add-variable){: target="_blank" }.
+
 ### 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" }).
@@ -52,6 +54,18 @@ You will return to this page after reviewing (but not doing) this step [Configur
 | <span translate="no">LoopCaregiver</span> | [https://github.com/LoopKit/LoopCaregiver](https://github.com/LoopKit/LoopCaregiver){: target="_blank" } | [LoopDocs: <span translate="no">LoopCaregiver</span>](../nightscout/loop-caregiver.md) |
 | <span translate="no">LoopFollow</span> | [https://github.com/loopandlearn/LoopFollow](https://github.com/loopandlearn/LoopFollow){: target="_blank" } | [<span translate="no">LoopFollow</span>](https://www.loopandlearn.org/loop-follow){: target="_blank" }|
 
+??? tips "LoopFollow Builders: Display Name (Click to Open/Close)"
+    * Would you like the name of your LoopFollow app to be personalized?
+    * Do you have more than one Looper, so you are using LoopFollow_Second or LoopFollow_Third?
+    * The 3 LoopFollow repositories enable you to customize the name shown on your phone
+
+    After you `fork` your *LoopFollow* repository, find the file named: `LoopFollowDisplayNameConfig.xcconfig`
+
+    * Open it in your browser
+    * Follow the directions to change `display_name`
+        * "Save the file" means commit the change to your `main` branch
+        * It is recommended that you use LF_name, where name is the customized name - that way you can find it in an alphabetic list of apps
+
 The two repositories below are only if you need to follow a second or third looper. All others should use just the table above. The instructions for the second and third looper are otherwise identical to the first looper. Note that `LoopCaregiver` can follow multiple Loopers; you select the person inside the app.
 
 | Special Case | Fork from this Address |
@@ -65,7 +79,7 @@ The two repositories below are only if you need to follow a second or third loop
 
 * All `repositories` in your *GitHub* organization use the organization <code>Secrets and Variables</code>
 * If you have not already completed [Add <code>Secrets</code> to your *GitHub* Organization](#add-secrets-to-your-github-organization), do it now
-* Skip ahead to [Validate <code>Secrets</code>](#validate-secrets)
+* Skip ahead to [Add Identifiers](#add-identifiers)
 
 ### Using a Personal *GitHub* Account
 
@@ -98,7 +112,9 @@ Open the text file in which you maintain a copy of your 6 <code>Secrets</code> s
     ![dialog for entering a new secret](img/repeat-secret-dialog.png){width="500"}
     {align="center"}
 
-Once all six <code>Secrets</code> are added, proceed to the first Action to validate your secrets.
+Be sure to [Add Variable](prepare-fork.md#add-variable){: target="_blank" } to the repository as well as `Secrets` to enable automatic certificate creation.
+
+Once the <code>Secrets</code> and `Variable` are added, proceed to the first Action to validate your secrets.
 
 ## Validate <code>Secrets</code>
 
@@ -135,6 +151,8 @@ The `Validate Secrets` &nbsp;<span class=notranslate>Action</span>&nbsp; should
 
 Near the top middle of your Repository fork, click on the "Actions" tab.
 
+* If this is the first `Action` you run with this repository you'll be informed that `Workflows aren't being run on this forked repository`
+    * Tap on the green button that says: `I understand my workflows, go ahead and enable them`
 * The graphic below is an example from Loop, your screen will show your app and associated repository
 
 Refer to the graphic below for the numbered steps:
@@ -448,6 +466,7 @@ The directions below may be sufficient for some.
 * In the left pane, scroll down to find `Secrets and variables` and click on the dropdown symbol and choose `Actions`
 * At this point, tap on `New organization secret` and add your 6 secrets
 * Then tap on the `Variable` tab and enter your Variable
+    * For details on adding the variable, see [Add Variable](prepare-fork.md#add-variable){: target="_blank" }
 
 ### Build with Organization
 
diff --git a/docs/browser/prepare-fork.md b/docs/browser/prepare-fork.md
@@ -225,7 +225,7 @@ If you are someone who already has a lot of forks in your personal account and w
 
 1. Follow the steps to create your organization
     * [Create a Free *GitHub* Organization](secrets.md#create-a-free-github-organization){: target="_blank" }
-1. Add the `Secrets` and the `Variable` as explained in [Prepare to Enter `Secrets`](#prepare-to-enter-secrets)
+1. Add the `Secrets` and the `Variable` to your *GitHub* organization as explained in [Prepare to Enter `Secrets`](#prepare-to-enter-secrets)
 1. Fork all the repos you normally use, but this time, set your organization as the owner
 1. For each repository in your organization:
     * Tap on the Actions tab
diff --git a/docs/faqs/glossary.md b/docs/faqs/glossary.md
@@ -164,6 +164,8 @@ When Google Translate is selected:
 
 **<span translate="no">Nightscout</span>**&nbsp; (Nightscout): a personal website used to view your glucose and diabetes management data, `Loop` can upload to `Nightscout`
 
+**<span translate="no">nuke</span>**&nbsp; (nuke): clear signing credentials from your Match-Secrets repository
+
 **<span translate="no">Onboarding</span>**&nbsp; (Onboarding): familiarize new, and existing, Loop users with settings in Loop 3 and ensure the Therapy Settings are all entered and are within safety guardrails
 
 **<span translate="no">Omnipod</span>**&nbsp; (Omnipod): Insulet tubeless insulin pump; Loop supports Eros (with RileyLink) and DASH.  Eros is also known as Classic, UST400, and System.
diff --git a/includes/tooltip-list.txt b/includes/tooltip-list.txt
@@ -75,6 +75,7 @@
 *[MPC]: model predictive control; the type of control algorithm used by Loop
 *[NFC]: Near-Field Communication is used for scanning devices such as Libre sensors
 *[Nightscout]: a personal website used to view your glucose and diabetes management data, `Loop` can upload to `Nightscout`
+*[nuke]: clear signing credentials from your Match-Secrets repository
 *[Onboarding]: familiarize new, and existing, Loop users with settings in Loop 3 and ensure the Therapy Settings are all entered and are within safety guardrails
 *[Omnipod]: Insulet tubeless insulin pump; Loop supports Eros (with RileyLink) and DASH.  Eros is also known as Classic, UST400, and System.
 *[OrangeLink]: radio-frequency device Loop uses to control Eros pods (aka. Gen 3) and older Medtronic pumps
