Merge pull request #843 from marionbarker/working-docs

Simplify Configure Identifiers for Loop section

Author: marionbarker

docs/build/xcode-settings.md

@@ -39,7 +39,7 @@ The very first time you open Xcode it may install a package of command line tool
 
 * Check that your Command Line Tools installed correctly.
     - First, open Xcode Settings
-        * Click on the word **`Xcode`** in the top menu bar (just to the right of the Apple icon in the upper-left corner) and select `Settings` in the drop-down menu
+        * Click on the word **`Xcode`** in the top menu bar (just to the right of the Apple icon in the upper-left corner) and select `Settings` in the dropdown menu
     - Then select the `Locations` tab in the Settings window to see the dropdown menu for Command Line Tools.  Make sure the Xcode version listed matches what you just installed (not the version in this graphic)
 * If it's blank, use the blue arrows to the right of the Command Line Tools row to select it
 

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

@@ -74,59 +74,108 @@ If you have already completed the One-Time Changes, skip ahead to [Build `Branch
 
 #### Transition to `dev`
 
-When updating from&nbsp;_<span translate="no">Loop</span>_&nbsp;3.2.3 to `dev`, you will need to take some extra steps. 
+When updating from&nbsp;_<span translate="no">Loop</span>_&nbsp;3.2.3 to `dev` (version 3.3.0), you will need to take some extra steps. 
 
 **We recommend most users leave their default branch as `main`.**
 
 * This is the safest choice if you are choosing to build `dev branch` now because you want the bug fixes and features that are found in `dev`
 * When version 3.4.0 is released, most users will return to the building the `main branch`
     * At that time, simply update your `main` branch and return to using released code
-* Each action below requires you to select the `dev` branch in the drop-down menu
+* Each action below requires you to select the `dev` branch in the dropdown menu
 
 Here is a summary of the extra steps you will follow as you progress through this section.
 
-1. Confirm the status of your&nbsp;<span translate="no">*GitHub* Personal Access Token</span>
-    * It should be configured with permission scope of `repo, workflow` and to never expire
-    * You can check this using directions at [*GitHub* Token](gh-update.md#github-token){: target="_blank" }
 1. [Add and Update `New Identifier`](#add-and-update-new-identifier)
 1. [`Create Certificates`](#create-certificates)
 1. [`Build Loop`](#build-branch)
 
-#### 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
-
 #### Add and Update New `Identifier`
 
 The `bundle ID` for the "`widget`" changed from "`SmallStatusWidget`" to the more descriptive "`LoopWidgetExtension`".
 
 * You need to run `Add Identifier` - be sure to select the `dev branch` when you run this action
 * Wait for it to succeed
-* Add the `App Group` to this one new Identifier
+
+??? tip "For detailed instructions (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`)
+        * You should select the `dev` branch in the dropdown menu near the word `Optional` in the graphic
+    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 }):
+        * [Examine the Error](gh-errors.md#examine-the-error) tells how to view the file needed to diagnose your problem.
+        * [Action: Add Identifiers Errors](gh-errors.md#action-add-identifiers-errors) tells you what to search for in the file
+        * Resolve the error and repeat the Action: [Add Identifiers](#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.
+* Add the `Loop App Group` to the new "`LoopWidgetExtension`" identifier
 
 | `NAME` | `IDENTIFIER` |
 |-------|------------|
 | `Loop Widget Extension` | `com.TEAMID.loopkit.Loop.LoopWidgetExtension` |
 
-* Open the [Certificates, Identifiers & Profiles: Identifiers List](https://developer.apple.com/account/resources/identifiers/list){: target="_blank" } page.
-* Click on the "`LoopWidgetExtension`" identifier
-* Edit the App Group to include `group.com.TEAMID.loopkit.LoopGroup` where you use your `TEAMID`
+??? tip "For detailed instructions (Click to open/close)"
+    * 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.
+
+    Looking at the `App Services` column, scroll down to the `App Groups` row
 
-??? tip "Other Identifiers (Click to Open/Close)"
+    * Ensure the check box (under the `Capabilities column`) for `App Groups` is checked
+    * If the word `Edit` shows up under `NOTES`, return to the identifiers list
+        * Tap on the `< All Identifiers` button at the top left
+    * If the word `Configure` shows up, tap on it
+        * This opens the `App Group Assignment` screen
+        * Check the box by `Loop App Group` that uses your `TEAMID` in `group.com.TEAMID.loopkit.LoopGroup` and then `Continue`
+
+    If you had to modify the identifier, the `Save` button at the top right will become active
+
+    * Tap on `Save`
+    * This opens the `Modify App Capabilities confirmation` screen
+    * Click on `Confirm`
+
+    If you did not need to make changes, the `Save` button will not be active.
+
+    * Tap on the `< All Identifiers` button 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](gh-first-time.md#add-app-group-to-identifiers){: target="_blank" }
-    * With the `dev branch`, only the App Group needs to be added; all other `Identifier` settings are automatically included.
 
 #### Create Certificates
 
 You must run the action `Create Certificates` again because the `Identifiers` were updated. Be sure that you run this for the `dev branch`
 
+??? tip "For 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`)
+        * You should select the `dev` branch in the dropdown menu near the word `Optional` in the graphic
+    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
+        * If this action fails, head over to [Action: 3. Create Certificates Errors](gh-errors.md#action-create-certificates-errors)
+
 ### Build `Branch`
 
 > **We recommend most users leave their default branch as `main`.**
@@ -144,6 +193,15 @@ 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.

docs/gh-actions/gh-errors.md

@@ -515,9 +515,9 @@ Select `Action: Build Loop`
 Refer to the first graphic below:
 
 * Tap on Run Workflow (on the right side)
-* Tap on the drop-down arrow to the right of the default `branch`
+* Tap on the dropdown arrow to the right of the default `branch`
 * Choose the `branch` you just created
-    * Start to type `patch` in the `branch` selection drop-down
+    * Start to type `patch` in the `branch` selection dropdown
     * Only `branches` with that phrase will be displayed
 * After you have the correct `branch` selected, tap on run workflow