Update README and testflight instruction files (#39)

marionbarker · web-flow · commit 3b83f8ebdebe · 2023-03-11T07:46:34.000-06:00
* Update GitHub build instructions

* Add link to testflight.md in README

* grammar fix

* Update for clarity

* update GitHub row to Secrets and variables

* fix link and add notes

* fix typo

* Change suggested expiration for GH_PAT to 90 days

* Update README

* Clarify a comment on testflight instructions
diff --git a/README.md b/README.md
@@ -1,6 +1,19 @@
 # LoopWorkspace
 
-## Clone
+The Loop app can be built using GitHub in a browser on any computer or using a Mac with Xcode.
+
+* Non-developers may prefer the GitHub method
+* Developers or Loopers who want full build control may prefer the Mac/Xcode method
+
+## GitHub Build Instructions
+
+The GitHub Build Instructions are at this [link](fastlane/testflight.md) and further expanded in [LoopDocs: Browser Build](https://loopkit.github.io/loopdocs/gh-actions/gh-overview/).
+
+## Mac/Xcode Build Instructions
+
+The rest of this README contains information needed for Mac/Xcode build. Additonal instructions are found in [LoopDocs: Mac/Xcode Build](https://loopkit.github.io/loopdocs/build/overview/).
+
+### Clone
 
 This repository uses git submodules to pull in the various workspace dependencies.
 
@@ -12,7 +25,7 @@ git clone --branch=<branch> --recurse-submodules https://github.com/LoopKit/Loop
 
 Replace `<branch>` with the initial LoopWorkspace repository branch you wish to checkout.
 
-## Open
+### Open
 
 Change to the cloned directory and open the workspace in Xcode:
 
@@ -21,13 +34,13 @@ cd LoopWorkspace
 xed .
 ```
 
-## Input your development team
+### Input your development team
 
 You should be able to build to a simulator without changing anything. But if you wish to build to a real device, you'll need a developer account, and you'll need to tell Xcode about your team id, which you can find at https://developer.apple.com/.
 
 Select the LoopConfigOverride file in Xcode's project navigator, uncomment the `LOOP_DEVELOPMENT_TEAM`, and replace the existing team id with your own id.
 
-## Build
+### Build
 
 Select the "Loop (Workspace)" scheme (not the "Loop" scheme) and Build, Run, or Test.
 
diff --git a/fastlane/testflight.md b/fastlane/testflight.md
@@ -1,53 +1,104 @@
-# Using Github Actions + FastLane to deploy to TestFlight
+# Using GitHub Actions + FastLane to deploy to TestFlight
 
-These instructions allow you to build Loop without having access to a Mac. They also allow you to easily install Loop on phones that are not connected to your computer. So you can send builds and updates to those you care for easily, or have an easy to access backup if you run Loop for yourself. You do not need to worry about correct Xcode/Mac versions either. An app built using this method can easily be deployed to newer versions of iOS, as soon as they are available.
+These instructions allow you to build Loop without having access to a Mac.
 
-The setup steps are somewhat involved, but nearly all are one time steps. Subsequent builds are trivial.  Note that TestFlight requires apple id accounts 13 years or older. Your app must be updated once every 90 days, but it's a simple click to make a new build and can be done from anywhere.
+* You can install Loop on phones via TestFlight that are not connected to your computer
+* You can send builds and updates to those you care for
+* You can install Loop on your phone using only the TestFlight app if a phone was lost or the app is accidentally deleted
+* You do not need to worry about specific Xcode/Mac versions for a given iOS
+
+The setup steps are somewhat involved, but nearly all are one time steps. Subsequent builds are trivial. Your app must be updated once every 90 days, but it's a simple click to make a new build and can be done from anywhere. The 90-day update is a TestFlight requirement, which can be automated.
+
+There are more detailed instructions in LoopDocs for using GitHub for Browser Builds of Loop, including troubleshooting and build errors. Please refer to:
+
+* [LoopDocs: GitHub Overview](https://loopkit.github.io/loopdocs/gh-actions/gh-overview/)
+* [LoopDocs: GitHub Errors](https://loopkit.github.io/loopdocs/gh-actions/gh-errors/)
+
+Note that installing with TestFlight, (in the US), requires the Apple ID account holder to be 13 years or older. For younger Loopers, an adult must log into Media & Purchase on the child's phone to install Loop. More details on this can be found in [LoopDocs](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/#install-testflight-loop-for-child).
 
 ## Prerequisites
 
-* A [github account](https://github.com/signup). The free level comes with plenty of storage and free compute time to build loop, multiple times a day, if you wanted to.
-* A paid [Apple Developer account](https://developer.apple.com). You may be able to use the free version, but that has not been tested.
+* A [GitHub account](https://github.com/signup). The free level comes with plenty of storage and free compute time to build loop, multiple times a day, if you wanted to.
+* A paid [Apple Developer account](https://developer.apple.com).
 * Some time. Set aside a couple of hours to perform the setup.
 
+## Save 6 Secrets
+
+You require 6 Secrets (alphanumeric items) to use the GitHub build method and if you use the GitHub method to build more than Loop, e.g., Loop Follow or LoopCaregiver, you will use the same 6 Secrets for each app you build with this method. Each secret is indentified below by `ALL_CAPITAL_LETTER_NAMES`.
+
+* Four Secrets are from your Apple Account
+* Two Secrets are from your GitHub account
+* Be sure to save the 6 Secrets in a text file using a text editor
+    - Do **NOT** use a smart editor, which might auto-correct and change case, because these Secrets are case sensitive
 
 ## Generate App Store Connect API Key
 
+This step is common for all GitHub Browser Builds; do this step only once. You will be saving 4 Secrets from your Apple Account in this step.
+
 1. Sign in to the [Apple developer portal page](https://developer.apple.com/account/resources/certificates/list).
-1. Copy the team id from the upper right of the screen. Record this as your `TEAMID`.
-1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it a name like "FastLane API Key".
-1. Record the key id; this will be used for `FASTLANE_KEY_ID`.
+1. Copy the Team ID from the upper right of the screen. Record this as your `TEAMID`.
+1. Go to the [App Store Connect](https://appstoreconnect.apple.com/access/api) interface, click the "Keys" tab, and create a new key with "Admin" access. Give it the name: "FastLane API Key".
 1. Record the issuer id; this will be used for `FASTLANE_ISSUER_ID`.
+1. Record the key id; this will be used for `FASTLANE_KEY_ID`.
 1. Download the API key itself, and open it in a text editor. The contents of this file will be used for `FASTLANE_KEY`. Copy the full text, including the "-----BEGIN PRIVATE KEY-----" and "-----END PRIVATE KEY-----" lines.
 
-## Setup Github
-1. Create a [new empty repository](https://github.com/new) titled `Match-Secrets`. It should be private.
-1. Fork https://github.com/LoopKit/LoopWorkspace into your account.
+## Create GitHub Personal Access Token
+
+Log into your GitHub account to create a personal access token; this is one of two GitHub secrets needed for your build.
+
 1. Create a [new personal access token](https://github.com/settings/tokens/new):
-    * Enter a name for your token. Something like "FastLane Access Token".
-    * 30 days is fine, or you can select longer if you'd like.
+    * Enter a name for your token, use "FastLane Access Token".
+    * Change the selection to 90 days.
     * Select the `repo` permission scope.
     * Click "Generate token".
     * Copy the token and record it. It will be used below as `GH_PAT`.
-1. In the forked LoopWorkspace repo, go to Settings -> Secrets -> Actions.
+
+## Make up a Password
+
+This is the second one of two GitHub secrets needed for your build.
+
+The first time you build with the GitHub Browser Build method for any DIY app, you will make up a password and record it as `MATCH_PASSWORD`. Note, if you later lose `MATCH_PASSWORD`, you will need to delete and make a new Match-Secrets repository (next step).
+
+## Setup GitHub Match-Secrets Repository
+
+The creation of the Match-Secrets repository is a common step for all GitHub Browser Builds; do this step only once. You must be logged into your GitHub account.
+
+1. Create a [new empty repository](https://github.com/new) titled `Match-Secrets`. It should be private.
+
+Once created, you will not take any direct actions with this repository; it needs to be there for the GitHub to use as you progress through the steps.
+
+## Setup GitHub LoopWorkspace Repository
+
+1. Fork https://github.com/LoopKit/LoopWorkspace into your account.
+1. In the forked LoopWorkspace repo, go to Settings -> Secrets and variables -> Actions.
 1. For each of the following secrets, tap on "New repository secret", then add the name of the secret, along with the value you recorded for it:
     * `TEAMID`
-    * `FASTLANE_KEY_ID`
     * `FASTLANE_ISSUER_ID`
+    * `FASTLANE_KEY_ID`
     * `FASTLANE_KEY`
     * `GH_PAT`
-    * `MATCH_PASSWORD` - just make up a password for this
+    * `MATCH_PASSWORD`
+
+## Validate repository secrets
+
+This step validates most of your six Secrets and provides error messages if it detects an issue with one or more.
+
+1. Click on the "Actions" tab of your LoopWorkspace repository and enable workflows if needed
+1. On the left side, select "1. Validate Secrets".
+1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
+1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
+1. The workflow will check if the required secrets are added and that they are correctly formatted. If errors are detected, please check the run log for details.
 
 ## Add Identifiers for Loop App
 
 1. Click on the "Actions" tab of your LoopWorkspace repository.
-1. Select "Add Identifiers".
-1. Click "Run Workflow", and tap the green button.
+1. On the left side, select "2. Add Identifiers".
+1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
 1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
 
 ## Create App Group
 
-If you have already built Loop via Xcode using this Apple ID, you can skip on to [Create Loop App in App Store Connect](#create-loop-app-in-app-store-connect).
+If you have already built Loop via Xcode using this Apple ID, you can skip on to [Add App Group to Bundle Identifiers](#add-app-group-to-bundle-identifiers).
 
 1. Go to [Register an App Group](https://developer.apple.com/account/resources/identifiers/applicationGroup/add/) on the apple developer site.
 1. For Description, use "Loop App Group".
@@ -56,6 +107,10 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to
 
 ## Add App Group to Bundle Identifiers
 
+Note 1 - If you previously built with Xcode, the `Names` listed below may be different, but the `Identifiers` will match. A table is provided below the steps to assist. The Add Identifier Action that you completed above generates 6 identifiers, but only 4 need to be modified as indicated in this step.
+
+Note 2 - Depending on your build history, you may find some of the Identifiers are already configured - and you are just verifying the status; but in other cases, you will need to configure the Identifiers.
+
 1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list) on the apple developer site.
 1. For each of the following identifier names:
     * Loop
@@ -70,6 +125,18 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to
 1. Click "Confirm".
 1. Remember to do this for each of the identifiers above.
 
+#### Table with Name and Identifier for Loop 3
+
+| NAME | IDENTIFIER |
+|-------|------------|
+| Loop | com.TEAMID.loopkit.Loop |
+| Loop Intent Extension | com.TEAMID.loopkit.Loop.Loop-Intent-Extension |
+| Loop Status Extension | com.TEAMID.loopkit.Loop.statuswidget |
+| Small Status Widget | com.TEAMID.loopkit.Loop.SmallStatusWidget |
+| WatchApp | com.TEAMID.loopkit.Loop.LoopWatch |
+| WatchAppExtension | com.TEAMID.loopkit.Loop.LoopWatch.watchkitextension |
+
+
 ## Add Time Sensitive Notifications to Loop App ID
 1. Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list) on the apple developer site.
 1. Click on the "Loop" identifier
@@ -80,7 +147,7 @@ If you have already built Loop via Xcode using this Apple ID, you can skip on to
 
 ## Create Loop App in App Store Connect
 
-If you have created a Loop app in App Store Connect before, you can skip this section as well.
+If you have created a Loop app in App Store Connect before, you can skip this section.
 
 1. Go to the [apps list](https://appstoreconnect.apple.com/apps) on App Store Connect and click the blue "plus" icon to create a New App.
     * Select "iOS".
@@ -95,18 +162,22 @@ You do not need to fill out the next form. That is for submitting to the app sto
 
 ## Create Building Certficates
 
-1. Go back to the "Actions" tab of your LoopWorkspace repository in github.
-1. Select "Create Certificates".
-1. Click "Run Workflow", and tap the green button.
+1. Go back to the "Actions" tab of your LoopWorkspace repository in GitHub.
+1. On the left side, select "3. Create Certificates".
+1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
 1. Wait, and within a minute or two you should see a green checkmark indicating the workflow succeeded.
 
-## Build Loop!
+## Build Loop
 
 1. Click on the "Actions" tab of your LoopWorkspace repository.
-1. Select "Build Loop".
-1. Click "Run Workflow", select your branch, and tap the green button.
+1. On the left side, select "4. Build Loop".
+1. On the right side, click "Run Workflow", and tap the green `Run workflow` button.
 1. You have some time now. Go enjoy a coffee. The build should take about 20-30 minutes.
 1. Your app should eventually appear on [App Store Connect](https://appstoreconnect.apple.com/apps).
 1. For each phone/person you would like to support Loop on:
     * Add them in [Users and Access](https://appstoreconnect.apple.com/access/users) on App Store Connect.
     * Add them to your TestFlight Internal Testing group.
+
+## TestFlight and Deployment Details
+
+Please refer to [LoopDocs: Set Up Users](https://loopkit.github.io/loopdocs/gh-actions/gh-first-time/#set-up-users-and-access-testflight) and [LoopDocs: Deploy](https://loopkit.github.io/loopdocs/gh-actions/gh-deploy/)
