Add details on iOS app store publication, and updated Android details.

docs/how-to/code-signing/macOS.rst

@@ -28,30 +28,35 @@ be guided through in this tutorial:
 
 5. Anticipating potential issues with the identity in the future
 
+.. _apple-dev-enroll:
 
 Enrolling in the Apple Developer program
 ----------------------------------------
 
 You can enroll in the Apple Developer program either as an individual, or as an
-organization. In both cases, you'll have to follow the instructions on the
-`Apple Developer website <https://developer.apple.com/programs/enroll/>`__.
+organization. In both cases, you'll have to follow the instructions on the `Apple
+Developer website <https://developer.apple.com/programs/enroll/>`__.
 
-Once you click "Start Enrollment Now" at the bottom of the page, you can either
-sign in with your existing Apple ID or alternatively, create a new one:
+Once you click "Start Enrollment Now" at the bottom of the page, you can either sign in
+with your existing Apple ID or alternatively, create a new one:
 
 .. image:: images/AppleID.png
    :width: 300
 
-As part of the registration procedure, you'll have to pay a **$99 fee**, which
-will be charged on an annual basis.
+There are two types of Apple Developer account - a *personal* account, and a *business*
+account. If you use your personal Apple ID to create an Apple Developer account,
+converting it to a business account later can be painful. If you use your personal Apple
+ID to create a business account, extracting your personal credentials later can also be
+painful.
 
-.. admonition:: Fee waivers
+As part of the registration procedure, you'll have to pay a **$99 fee**, which will be
+charged on an annual basis.
 
-  If you're registering as a non-profit organization, an educational institution
-  or a government entity, you may be eligible for a fee waiver, which you can
-  read more about `here
-  <https://developer.apple.com/support/membership-fee-waiver/>`__.
+.. admonition:: Fee waivers
 
+  If you're registering as a non-profit organization, an educational institution or a
+  government entity, you may be eligible for a fee waiver, which you can read more about
+  `here <https://developer.apple.com/support/membership-fee-waiver/>`__.
 
 Generating a certificate request on Keychain Access
 ---------------------------------------------------

docs/how-to/index.rst

@@ -18,6 +18,5 @@ stand alone.
    access-packaging-metadata
    contribute-code
    contribute-docs
-   See errors on iOS <see_errors_on_ios>
    internal/index
    publishing/index

docs/how-to/publishing/android.rst

@@ -2,12 +2,16 @@
 Android
 =======
 
-Overview
---------
-
 The Google Play Store is the most widely-used Android app store. This guide
 focuses on how to distribute a BeeWare app on the Google Play Store.
 
+.. admonition: App Stores are a moving target
+
+    The Google Play Store makes frequent changes to the workflows and nomenclature
+    associated with publishing apps. As a result, it's very difficult to keep a guide
+    like this one up to date. If you spot any problems, `let us know
+    <https://github.com/beeware/briefcase/issues/new?assignees=&labels=bug,documentation,android&projects=&template=bug_report.yml>`__.
+
 Build the app in release mode
 -----------------------------
 
@@ -22,7 +26,7 @@ Use Briefcase to build a release bundle for your application:
       (venv) $ briefcase package android
       [hello-world] Building Android App Bundle and APK in release mode...
       ...
-      [hello-world] Packaged android/Hello World/app/build/outputs/bundle/release/app-release.aab
+      [hello-world] Packaged dist/Hello World-1.0.0.aab
 
   .. group-tab:: Linux
 
@@ -31,7 +35,7 @@ Use Briefcase to build a release bundle for your application:
       (venv) $ briefcase package android
       [hello-world] Building Android App Bundle and APK in release mode...
       ...
-      [hello-world] Packaged android/Hello World/app/build/outputs/bundle/release/app-release.aab
+      [hello-world] Packaged dist/Hello World-1.0.0.aab
 
   .. group-tab:: Windows
 
@@ -40,7 +44,7 @@ Use Briefcase to build a release bundle for your application:
       (venv) C:\...>briefcase package android
       [hello-world] Building Android App Bundle and APK in release mode...
       ...
-      [hello-world] Packaged android\Hello World\app\build\outputs\bundle\release\app-release.aab
+      [hello-world] Packaged dist\Hello World-1.0.0.aab
 
 This will result in an Android App Bundle file being generated. An `Android App
 Bundle <https://developer.android.com/guide/app-bundle>`__ is a publishing
@@ -76,7 +80,7 @@ name.
 
     .. code-block:: console
 
-      $ ~/Library/Caches/org.beeware.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "android/gradle/Hello World/app/build/outputs/bundle/release/app-release.aab" upload-key -storepass android
+      $ ~/Library/Caches/org.beeware.briefcase/tools/java/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android
          adding: META-INF/MANIFEST.MF
          adding: META-INF/UPLOAD-K.SF
          adding: META-INF/UPLOAD-K.RSA
@@ -101,7 +105,7 @@ name.
 
     .. code-block:: console
 
-      $ ~/.cache/briefcase/tools/java/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "android/gradle/Hello World/app/build/outputs/bundle/release/app-release.aab" upload-key -storepass android
+      $ ~/.cache/briefcase/tools/java/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android
          adding: META-INF/MANIFEST.MF
          adding: META-INF/UPLOAD-K.SF
          adding: META-INF/UPLOAD-K.RSA
@@ -126,7 +130,7 @@ name.
 
     .. code-block:: doscon
 
-      C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore %HOMEPATH%\.android\upload-key-helloworld.jks "android\gradle\Hello World\app\build\outputs\bundle\release\app-release.aab" upload-key -storepass android
+      C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore %HOMEPATH%\.android\upload-key-helloworld.jks "dist\Hello World-1.0.0.aab" upload-key -storepass android
          adding: META-INF/MANIFEST.MF
          adding: META-INF/UPLOAD-K.SF
          adding: META-INF/UPLOAD-K.RSA
@@ -179,10 +183,10 @@ certificate when you upload your app for distribution.
 Add the app to the Google Play store
 ------------------------------------
 
-To publish to the Google Play store, you will need a Google Play Developer
-account, which costs 25 USD. You will then need to provide
-information for your app's store listing including an icon and screenshots,
-upload the app to Google, and finally roll the app out to production.
+To publish to the Google Play store, you will need a Google Play Developer account,
+which costs 25 USD. You will then need to provide information for your app's store
+listing including an icon and screenshots, upload the app to Google, and finally roll
+the app out to production.
 
 Register for a Google Play Developer account
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -204,12 +208,11 @@ Create a listing
 ~~~~~~~~~~~~~~~~
 
 Visit the `Google Play console. <https://play.google.com/console/about/>`__ and
-log in. You will see a button labeled **Publish an Android App on Google Play**
-or a button to **Create Application**. Click it.
+log in. You will see a button labeled **Create App**; click this button.
 
-Once you've done that, click **Create Application**. Choose a language and
-write a brief app title, up to 50 characters. We suggest making this the
-same as your app's Formal Name in its ``pyproject.toml``.
+Fill out the details for your app. We suggest using your app's formal name (as defined
+in ``pyproject.toml`` as the App name; the other details relate to the listing and legal
+compliance. At the bottom of of the page, press **Create App**.
 
 This will take you to **Store Listing** section of your app. You will need
 to provide a short app description (up to 80 characters) and a full
@@ -243,23 +246,21 @@ Google Play supports optional graphic assets including promo videos, TV banners,
 and 360 degree stereoscopic images. See also `Google's advice on graphic assets.
 <https://support.google.com/googleplay/android-developer/answer/9866151>`__
 
-Once you've completed the store listing, you'll need to fill out a range of
-other details about your app, including the category where it should appear in
-the Play Store, pricing details, details about the app's content and its
-suitability for children, and contact details for you as a developer. The
-navigation pane (typically on the left side of the screen) contains grayed out
-check marks covering all the sections with required details. Visit each of
-these sections in turn; when you have met the requirements of each section, the
-check mark will turn green. Once all the checkmarks are green, you're ready to
-release your app.
+Once you've completed the store listing, you'll need to fill out a range of other
+details about your app, including the category where it should appear in the Play Store,
+pricing details, details about the app's content and its suitability for children, and
+contact details for you as a developer. The navigation pane (typically on the left side
+of the screen) contains grayed out check marks covering all the sections with required
+details. Visit each of these sections in turn; when you have met the requirements of
+each section, the check mark will turn green. Once all the checkmarks are green, you're
+ready to release your app.
 
 Create a release
 ~~~~~~~~~~~~~~~~
 
-Click **App releases** in the navigation pane. To produce a production app
-(i.e., an app in the public Play Store that anyone can download) click
-**Manage** within the **Production track**, then select **Create Release.**
-If prompted to enable App Signing by Google Play, click **Continue**.
+In the left navigation bar, select **Production** (in the "Release" grouping), Then
+select **Create Release.** If prompted to enable App Signing by Google Play, click
+**Continue**.
 
 .. admonition:: Non-production releases
 
@@ -268,33 +269,28 @@ If prompted to enable App Signing by Google Play, click **Continue**.
     test releases
     <https://support.google.com/googleplay/android-developer/answer/9845334>`__.
 
-In an earlier section of this tutorial, we used ``briefcase publish`` and
-``jarsigner`` to create a signed Android App Bundle file. It is stored at
-``android/Hello World/app/build/outputs/bundle/release/app-release.aab``
-(substituting the name of your own app as necessary). Upload this file to the
-Google Play console within **Browse Files** under **Android App Bundles and
-APKs to add.**
+In an earlier section of this tutorial, we used ``briefcase publish`` and ``jarsigner``
+to create a signed Android App Bundle file. It is stored in the ``dist`` folder of your
+project. Upload this file to the Google Play console in the **App Bundles** section,
+fill out the **Release notes** section of the app, and click **Next**.
 
-You will need to write release notes for the app in the **What's new in this
-release?** section. If this is your first upload of the app, you can use
-something like "Initial application release." Review your application details,
+Google will then check that you've filled out all the necessary compliance details for
+your app; if there are any missing, you'll be prompted to complete those details.
 
-Once you have answered those questions, you can switch back to the
-**App releases** tab. Click **Edit release**, save your changes, and
-click **Start Rollout To Production.**
+Once you've completed those details, select **Publishing Overvie** from the navigation
+sidebar. You should see "Changes ready to send for review", and a button marked **Send
+for review**. Click this button.
 
-The Google Play Store will now review your app. You will be emailed if any
-updates are required; otherwise, after a day or two, your app will be rolled
-out to the Play Store.
+The Google Play Store will now review your app. You will be emailed if any updates are
+required; otherwise, after a day or two, your app will be rolled out to the Play Store.
 
 Publish an update
 -----------------
 
-At some point, you'll want to publish an updated version of your application.
-Generate a fresh AAB file, signed with the *same* certificate as your original
-release. Then log into the Play Store console, and select your application.
-Select **Release Management** in the navigation bar, then **App Releases**.
+At some point, you'll want to publish an updated version of your application. Generate a
+fresh AAB file, signed with the *same* certificate as your original release. Then log
+into the Play Store console, and select your application. Select **Release Management**
+in the navigation bar, then **App Releases**.
 
-At this point, the release process is the same as it was for your initial
-release; create a release, upload your AAB file, and submit the application
-for roll out.
+At this point, the release process is the same as it was for your initial release;
+create a release, upload your AAB file, and submit the application for roll out.

docs/how-to/publishing/iOS.rst

@@ -0,0 +1,120 @@
+===
+iOS
+===
+
+This guide will walk you through the process of publishing an app to the Apple App
+Store.
+
+.. admonition: App Stores are a moving target
+
+    The Apple App Store makes frequent changes to the workflows and nomenclature
+    associated with publishing apps. As a result, it's very difficult to keep a like
+    this one up to date. If you spot any problems, `let us know
+    <https://github.com/beeware/briefcase/issues/new?assignees=&labels=bug,documentation,apple&projects=&template=bug_report.yml>`__.
+
+To distribute an app on the iOS App Store, you'll need to :ref:`enroll in the Apple
+Developer Program <apple-dev-enroll>`. You don't need to generate any of the
+certificates described on that page - you just need an Apple ID registered in the
+developer program.
+
+Once you've signed up for an Apple ID account, open the Xcode Settings dialog, and
+add your account under the "Accounts" tab.
+
+Open the app in Xcode
+=====================
+
+Use Briefcase to open the Xcode project associated with your project.
+
+.. code-block:: console
+
+    (venv) $ briefcase open iOS
+
+Run the app in the simulator
+============================
+
+In order to submit your app to the App Store, you will need to provide a range of
+screenshots:
+
+* 3-5 screenshots running on a 6.5" iPhone (e.g., iPhone 14 Plus)
+* 3-5 screenshots running on a 5.5" iPhone (e.g., iPhone 8 Plus)
+* 3-5 screenshots running on an 12.9" iPad Pro (Gen 6; without a physical home button)
+* 3-5 screenshots running on an 12.9" iPad Pro (Gen 2; with a physical home button)
+* (optionally) 3-5 screenshots running on a 6.7" iPhone (e.g., iPhone 14 Pro Max)
+
+The iOS and iPad simulators have a "Save Screen" button in their title bar; this will
+capture screenshots of the necessary size.
+
+You can change simulator device by clicking on the device target int the top bar of the
+Xcode window. Click on the device name, and select the device from the list. If the device
+you need doesn't exist on this list, click on "Manage Run Destinations" to add a simulator
+for that device type.
+
+Produce an App archive
+======================
+
+Select the root node of the Xcode project browser (it should be the formal name of your
+app), then select the **Signing & Capabilities** tab from configuration options that are
+displayed. The "Team" option under "Signing" will be listed as "None"; select the name
+of the development team that will sign the app. If there's no team listed, select "Add
+an Account", and choose one of the teams that is associated with your Apple ID.
+
+In the top bar of the Xcode window, change the target device from a simulator to "Any
+iOS device". Clean the build products folder (select "Clean Build Folder..." from the
+Product menu), then build an archive by selecting "Archive" from the Product menu. This
+will perform a clean build of your application, build an archive, and open a new window,
+called the Organizer. It should list a freshly created archive of your app, with the
+current version number.
+
+Select the archive, and click the "Distribute App" on the right side of the Organizer
+window. This will display a wizard that will ask details about your app; accept the
+default values; once the wizard completes, your app binary has been sent to the App
+Store for inclusion in a release.
+
+After a few minutes, you should receive an email notifying you that the binary has been
+processed.
+
+Create an App Store entry
+=========================
+
+Log into `App Store Connect <http://appstoreconnect.apple.com>`__, click on "My Apps",
+then on + to add an app.
+
+Fill out the form for a new app. If you've run the app in Xcode, the Bundle ID for your
+app should be listed; select it from the list. You must also create an SKU for your app
+- we suggest ``ios-<appname>``, substituting the short app name that you selected when
+you initially created your app. So, if you've created an app with a formal name of
+"Hello World", with an app name of ``helloworld``, and a bundle of ``org.beeware``, you
+should have a Bundle ID of ``org.beeware.helloworld``; we'd suggest an SKU of
+``ios-helloworld``.
+
+You'll then be shown another page for app details, including:
+
+* Primary and Secondary Category.
+* Screenshots
+* Promotional Text
+* Description
+* Keywords
+* Support URL
+* Marketing URL
+* A URL for your app's privacy policy
+* Version number
+* The name of the copyright holder
+
+Under the "Build" section, you'll be able to select the archive that you uploaded
+through Xcode.
+
+The "App Review Information" section allows you to provide contact details in case Apple
+has questions during the review process. If your app requires a login, you *must*
+provide a set of credentials so that Apple can log in. You can also provide any
+additional notes to assist the reviewer.
+
+Click on "Pricing and Availability" tab on the sidebar, and set up the pricing schedule
+and availability for your app.
+
+Then, click on "App Privacy", and click on "Get Started"; this will ask you a series of
+questions about the information about users that your app collects.
+
+Once these details have all been provided, click on the "1.0 Prepare for Submission" link
+in the sidebar. On the right of the screen, click on "Add for Review"; this will ask some
+final questions, and provide one more button "Submit for Review". Click that button, and
+you're done!

docs/how-to/publishing/index.rst

@@ -9,3 +9,4 @@ covers how to publish your app to the appropriate distribution system.
    :maxdepth: 1
 
    android
+   iOS