Merge pull request #873 from marionbarker/working-docs

Update some Browser Build Information

Author: marionbarker

docs/browser/build-dev-browser.md

@@ -141,3 +141,27 @@ Your default branch has been changed.
 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" }.
+
+## What Happens in TestFlight
+
+As soon as you build one version of the app from the `dev` branch, that version number (which is higher than the `main` branch) will show up at the top of the available builds in TestFlight.
+
+Suppose you then return to using the `main` branch after your excursion to the `dev` branch.
+
+> *For this example, version 3.4.4 is the released version from the `main` branch and version 3.5.0 is the development version you evaluated.*
+
+Every time you open TestFlight on your phone and select the *Loop* app, it will offer the most recent 3.5.0 version to be installed if you just tap **Install**. You might be in a situation where that build is about to expire or you decide you don't want to test this on your looping phone. In some cases, the released version, 3.4.4, might have fixes that are not available in a development branch.
+
+You have your choice:
+
+* You can manually go into TestFlight each time `main` is automatically built, Select Previous Builds, then choose 3.4.4 and install the top listing
+* You can log in at: [App Store Connect: Apps](https://appstoreconnect.apple.com/apps){: target="_blank" }
+    * Select your *Loop* app
+    * Click on the TestFlight tab
+    * For each 3.5 build, click on the row for a build
+        * Select Expire Build on upper right
+    * This leaves only the released version, 3.4.4 for this example, available in TestFlight on your phone
+
+![expire builds with higher version numbers](img/testflight-expire-dev.png){width="700"}
+{align="center"}
+

docs/browser/img/testflight-expire-dev.png

@@ -285,7 +285,22 @@ You must be logged into your *GitHub* account before starting this step. If you
 
 ## Make up a Password
 
-If you have not already made up a password, do it now and record it as <code>MATCH_PASSWORD</code>.
+If you have not already made up a password, do it now and record it as <code>MATCH_PASSWORD</code>. Note that if you [build more than one app](other-apps.md){: target="_blank" }, you use the same <code>MATCH_PASSWORD</code> for all the apps. Every app needs to have the same 6 Secrets.
+
+!!! info "What is this Password used for?"
+    The <code>MATCH_PASSWORD</code> is a special password called a *passphrase* that is used to encrypt and decrypt your certificates from *Apple* so they can be used when building with *GitHub*; it helps keeps your certificates secret and safe.
+
+    A *passphrase* is a little different from a regular password. A password is what you usually use to log in to a website or game. A *passphrase* is a secret code that helps protect important files by adding an extra layer of security when files are encrypted.
+
+### *Passphrase* Suggestions
+
+To make a *passphrase* that is hard to guess and keeps your certificates safe:
+
+* Use at least 15 characters (20 is even better) and you can include spaces
+* Mix in big letters, small letters, numbers, and symbols like $ or #
+* Don’t use words or numbers that people might guess, like your name or birthday
+
+If you already created a MATCH_PASSWORD that does not meet the criteria listed above, no worries, you are protecting an *Apple* developer certificate - not the family fortune. That information is provided for new builders who want guidance.
 
 ## Next Step
 

docs/browser/secrets.md

@@ -210,7 +210,7 @@ When Google Translate is selected:
 
 **<span translate="no">GH_PAT</span>**&nbsp; (GH_PAT): One of 6 Secrets: Generated with your GitHub account; set it to never expire
 
-**<span translate="no">MATCH_PASSWORD</span>**&nbsp; (MATCH_PASSWORD): One of 6 Secrets: password you make up but must save and cannot change without deleting the Match-Secrets repository
+**<span translate="no">MATCH_PASSWORD</span>**&nbsp; (MATCH_PASSWORD): One of 6 Secrets: Git repo encryption passphrase, used to encrypt the Match-Secrets repository when it is created. You must save and use the same MATCH_PASSWORD for every repository if you build multiple apps.
 
 **<span translate="no">SHA-1</span>**&nbsp; (SHA-1): Secure Hash Algorithm 1; used to generate an alphanumeric code for commits in git (github)
 

docs/faqs/glossary.md

@@ -98,7 +98,7 @@
 *[FASTLANE_KEY_ID]: One of 6 Secrets: Key ID provided when you create an API key in App Store Connect; it is associated with the FASTLANE_KEY
 *[FASTLANE_KEY]: One of 6 Secrets: Really long key (several lines); it and FASTLANE_KEY_ID are generated together
 *[GH_PAT]: One of 6 Secrets: Generated with your GitHub account; set it to never expire
-*[MATCH_PASSWORD]: One of 6 Secrets: password you make up but must save and cannot change without deleting the Match-Secrets repository
+*[MATCH_PASSWORD]: One of 6 Secrets: Git repo encryption passphrase, used to encrypt the Match-Secrets repository when it is created. You must save and use the same MATCH_PASSWORD for every repository if you build multiple apps.
 *[SHA-1]: Secure Hash Algorithm 1; used to generate an alphanumeric code for commits in git (github)
 *[Sign Targets]: associate a Developer ID with an app; must sign all targets for a given app
 *[submodules]: for Loop, submodules are repositories defined in the Workspace repository that are required to build the app