Merge pull request #917 from marionbarker/working-docs

Update README and add section for Refresh FastLane API Key

Author: marionbarker

README.md

@@ -48,9 +48,9 @@ If it is a more substantive change and you want to [install LoopDocs locally](#i
   # Run the next line **each time** you start a new shell window/tab
   source venv/bin/activate
   ```
-- Install the project's required *Python* packages
+- **Install** the **dependencies** (that is the project's required *Python* packages)
   ```shell
-  cd loopdocs # Make sure you are in the folder where you cloned this repository
+  cd loopdocs # where you cloned the loopdocs repository
 
   python -m pip install -r dev-requirements.txt
   python -m pip install -r requirements.txt
@@ -612,3 +612,60 @@ The website uses the Markdown page of the glossary.
 > [!IMPORTANT]
 > Remember to commit these two files.
 
+### Add a Package
+
+> [!NOTE]
+> In this section, the terms Python **package** and **dependency** refer to the same thing.
+
+- **Create** a feature **branch** (aka. topic branch)
+  ```shell
+  git switch dev
+  git switch -c feature/add_dependency_XXX
+  ```
+- **Add** the pinned version of the new **package** to the **`requirements.in`** file
+  ```shell
+    MY_FAVORITE_EDITOR_HERE requirements.in
+    
+    # Add the pinned version of the package to `requirements.in
+    XXX_PACKAGE_NAME_HERE==XXX_PACKAGE_VERSION_HERE
+    ```
+    For example, to add the `mkdocs-exporter` package version `6.1.1`, I added the following line to the `requirements.in` file:
+     ```text
+     mkdocs-exporter==6.1.1
+     ```
+- Generate **`requirements.txt`**
+  ```shell
+    cd loopdocs
+    
+    # IMPORTANT: The project's virtual environment MUST be activated first
+    source venv/bin/activate
+    
+    # Remove the already installed packages in case you need to start from a blank slate
+    # python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y
+    
+    # Install the development packages
+    # (among which `pip-tools` that contains `pip-compile`)
+    pip install -r dev-requirements.txt
+    
+    # Install the direct dependencies (listed in `requirements.in`
+    # This also installs the indirect dependencies these packages depend upon.
+    pip install -r requirements.in
+    
+    # Add code/doc using this package and test until it is ready.
+    
+    # Generate the `requirements.txt` file from `requirements.in`
+    # This can be slow, be patient
+    pip-compile requirements.in
+    
+    # Commit the changes (where XXX denotes the package name)
+    git add requirements.in requirements.txt
+    git commit -m "➕ Add dependency: XXX"
+    
+    # Push your feature branch to your `origin` repository
+    git push -u origin feature/add_dependency_XXX
+    ```
+- [**Create a Pull Request**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your changes:
+	- Open your clone repository of `trio-docs` on *GitHub* (`https://github.com/YOUR_USERNAME/trio-docs`)
+		- Click the `Pull Requests` tab 
+		- Click "`Compare & pull request`" in the yellow banner next to your branch name
+

docs/browser/bb-errors.md

@@ -117,6 +117,97 @@ Digital Service Act Compliance
 
 Open your *GitHub* account and select your <code>LoopWorkspace repository</code> from your repositories list.
 
+### Update from 3.2.x to 3.4
+
+This should only be necessary if you are changing from an older, Mac-Xcode build of version 3.2.x to a Browser Build of 3.6.x. Most people are updating from 3.4.x to 3.6.x and should skip ahead to [Special Instructions for 3.6.0](#special-instructions-for-360).
+
+For the update from 3.2.x to 3.6, 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 [Special Instructions for 3.6.0](#special-instructions-for-360).
+
+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
+
 ### Special Instructions for 3.6.0
 
 When updating to version 3.6.0, there are two "extra" things to do.
@@ -430,7 +521,7 @@ Manual certificate renewal is not longer required if you added the `Variable` `E
     {align="center"}
 
     !!! question "Deleting the certs/distribution folder did not work for me"
-        Some people reported trouble with this step. The other option is to delete and create a new `Match-Secrets` repository: see [Reset `Match-Secrets`](bb-errors.md#reset-match-secrets){: target="_blank" }
+        Some people reported trouble with this step. The other option is to delete and create a new `Match-Secrets` repository: see [Delete `Match-Secrets`](bb-errors.md#delete-match-secrets){: target="_blank" }
 
 1. While still within your *Github* account, navigate to your fork of LoopWorkspace.
     * You can do this several ways, but one method is demonstrated by the GIF below

docs/browser/bb-update.md

@@ -198,7 +198,10 @@ Once you add all six <code>Secrets</code>, your screen should look similar to th
 
 This is a new step required with `Loop 3.6.0` and newer versions. It provides automatic renewal of certificates, which expire once per year.
 
-1. While in the same screen where you enter the `Secrets`, click on the `Variables` tab to the right of the `Secrets` tab:
+1. While in the same screen where you enter the `Secrets`, click on the `Variables` tab to the right of the `Secrets` tab
+    * If you aren't at the screen:
+        * ***GitHub* organization account**: go to your organization page and select Settings; scroll down, select `Secret and Variable` and then select `Actions`
+        * ***GitHub* personal account**: go to your repository for the app you are building, select Settings; scroll down, select `Secret and Variable` and then select `Actions`
 1. Select new variable and give it the name the `ENABLE_NUKE_CERTS` and enter `true` as the value
 
 ``` { .text .copy }