Add guidance about updating store PWAs

microsoft-edge/progressive-web-apps-chromium/how-to/microsoft-store.md

@@ -6,7 +6,7 @@ ms.author: msedgedevrel
 ms.topic: conceptual
 ms.prod: microsoft-edge
 ms.technology: pwa
-ms.date: 08/11/2023
+ms.date: 10/06/2023
 ---
 # Publish a Progressive Web App to the Microsoft Store
 
@@ -19,7 +19,7 @@ Publishing your Progressive Web App (PWA) to the [Microsoft Store](/windows/uwp/
 | **Easy install** | The Microsoft Store provides a consistent and user-friendly install experience across [all Windows 10 or later apps](https://www.microsoft.com/store/apps/windows). |
 | **App analytics** | The [Microsoft Partner Center dashboard](/windows/uwp/publish/index) provides [detailed analytics](/windows/uwp/publish/analytics) about your app's health, usage, and more. |
 
-To publish your PWA to the Microsoft Store, no code changes are required.  Instead, you create an app reservation, package your PWA, and submit your package to the Store.  The following sections explain the steps.
+To publish your PWA to the Microsoft Store, no code changes are required.  Instead, you create an app reservation in Microsoft Partner Center, package your PWA using PWA Builder, and then submit your package to the Microsoft Store.  The following sections explain these steps.
 
 
 <!-- ====================================================================== -->
@@ -55,7 +55,7 @@ To create an app reservation:
 <!-- ====================================================================== -->
 ## Package your PWA for the Store
 
-Now that you have your app publishing information, generate a Windows app package for your PWA.
+Now that you've gathered the publishing information about your app, generate a Windows app package for your PWA by using PWA Builder.
 
 To generate an app package:
 
@@ -69,12 +69,9 @@ To generate an app package:
 
     ![Report card page](./microsoft-store-images/report-card.png)
 
-1.  Once your PWA is ready to be packaged, in the upper-right corner of the PWABuilder report card page, click the **Package For Stores** button.
+1.  Once your PWA is ready to be packaged, in the upper-right corner of the PWABuilder report card page, click the **Package For Stores** button. A dialog opens, showing the message **Awesome! Your PWA is store ready!**.
 
-    <!--
-    The XYZ dialog opens. -->
-
-1.  Under **Windows**, click the **Generate Package** button.
+1.  Under **Windows**, click the **Generate Package** button. The **Windows Package Options** dialog opens.
 
 1.  Paste the following values, which you saved in the [Create an app reservation](#create-an-app-reservation) section above:
     *  **Package ID**
@@ -85,10 +82,14 @@ To generate an app package:
 
 1.  Click the **Download Package** button to download your Windows package.
 
-Your download is a `.zip` archive that contains an `.msixbundle` file and a `.classic.appxbundle` file.  The two app packages allow your PWA to run on a wide variety of Windows versions.  For more information, see [What is a classic package?](https://github.com/pwa-builder/pwabuilder-windows-chromium-docs/blob/master/classic-package.md)<!-- changing "master" to "main" in that URL doesn't work, as of August 11, 2023 -->
+Your download is a `.zip` archive that contains an `.msixbundle` file and a `.classic.appxbundle` file.  The two app packages allow your PWA to run on a wide variety of Windows versions.
+
+See also:
 
+* [What is a classic package?](https://github.com/pwa-builder/pwabuilder-windows-chromium-docs/blob/master/classic-package.md)<!-- changing "master" to "main" in that URL doesn't work, as of August 11, 2023 -->
+* [Bundling MSIX packages](/windows/msix/package/bundling-overview).
 
-### Submit your app package to the Store
+#### Submit your app package to the Microsoft Store
 
 To submit your app to the Microsoft Store:
 
@@ -120,36 +121,39 @@ Use this feature to measure distinct traffic from your PWA that was installed fr
 <!-- ====================================================================== -->
 ## Redirect to locale-specific domains without displaying additional UI
 
-By default, a PWA that's installed from the Microsoft Store displays an additional UI when the app is redirected to a locale-specific domain.  The added UI shows the URL and page title.  This UI is added because navigation to the locale-specific domain is considered "out-of-scope".  However, you can prevent this UI from being displayed, by specifying locale-specific origins that are associated with the PWA.
+By default, a PWA that's installed from the Microsoft Store displays an additional UI when the app is redirected to a locale-specific domain.  The added UI shows the URL and page title.  This UI is added because navigation to the locale-specific domain is considered _out of scope_.
 
 The following figure shows the UI that is introduced when a user moves outside the scope of a PWA. 
 
 ![The additional UI with URL and page title when the app is redirected to another domain](./microsoft-store-images/locale-redirection-additional-ui.png)
 
-### Domain redirection with browser-installed PWAs
+#### Domain redirection with PWAs installed from the browser
 
-A Web App Manifest is tied to a single domain.  However, some PWAs use locale-specific domains for their customers in specific regions of the globe.  When visiting the PWA in a web browser, customers are seamlessly transitioned from the principal domain (for example, contoso.com) to a locale-specific domain (for example, contoso.co.ke), because the redirect happens during initial load of that website.
+A Web App Manifest is tied to a single domain.  However, some PWAs use locale-specific domains for their customers in specific regions of the globe.  When visiting the PWA in a web browser, customers are seamlessly transitioned from the principal domain (for example, `contoso.com`) to a locale-specific domain (for example, `contoso.co.ke`), because the redirect happens during initial load of that website.
 
 Customers who install the PWA from Microsoft Edge would therefore install the PWA from the locale-specific domain.  Subsequent launches of the PWA go directly to that locale-specific domain, instead of first going to the principal domain.
 
-### Domain redirection with PWAs installed from the Microsoft Store
+#### Domain redirection with PWAs installed from the Microsoft Store
 
 PWAs that are installed from the Microsoft Store have a hard-coded start URL that is pointed at the principal domain.  When the PWA is launched, the PWA initially navigates to the principal domain, and then a customer may (as necessary) be redirected to their locale-specific domain. If that redirection occurs, the navigation is considered "out of scope".  As a result, the app displays the URL and page title at the top of the page.
 
 Displaying the URL and page title is a security feature to ensure that users know they have left the context of the PWA.  This added UI makes sense when a user loads a page from another website in the context of the PWA.  However, that added UI may be inappropriate when a user moves among domains that are all part of the same website.
 
-### Prevent the locale-specific URL and title from being displayed
+#### Prevent the locale-specific URL and title from being displayed
+
+It's currently impossible, for apps installed from the Microsoft Store, to prevent displaying the additional URL and title UI when redirecting to a locale-specific domain.
 
-To prevent the additional UI from being shown in a PWA that's installed from the Microsoft Store, you can use [URL Handlers](https://github.com/WICG/pwa-url-handler/blob/main/explainer.md) to enable the PWA to span multiple locale-specific domains.
+In the future, _scope extensions_ will make it possible for a PWA to capture navigation to paths, subdomains, or even sites other than its own scope. The scope extensions feature is in active development and isn't ready to be used yet. To find out more about the state of development of this feature in Chromium, check out the [Web app scope extensions feature](https://chromestatus.com/feature/5746537956114432) at Chrome Platform Status.
 
-To prevent displaying the URL and page title:
+Once the feature can be used in Microsoft Edge, we will document it here. In the meantime, to learn more about how scope extensions will work, see the [explainer document on the WICG repository](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md).
 
-1. Within the PWA's Web App Manifest, use [the `url_handlers` member](https://github.com/WICG/pwa-url-handler/blob/main/explainer.md#manifest-changes) to specify an array of origins that are associated with that app.
-1. On each of the referenced origins, include a [`web-app-origin-association` file](https://github.com/WICG/pwa-url-handler/blob/main/explainer.md#web-app-origin-association-file) that associates the PWA with that domain.
 
-When these domain lists are in place, Microsoft Edge no longer shows the additional UI when the principal domain is redirected to the locale-specific domains.
+<!-- ====================================================================== -->
+## Make updates to your app
+
+Generally, when you update your PWA code, you don't need to create a new app package and submit it to the Microsoft Store again. For example, suppose you make changes to your app's front-end HTML, CSS, or JavaScript code, or to your service worker. The next time the user launches the app, the changes are downloaded by the browser that's running your app from your web server.
 
-Eventually, the `url_handlers` feature will be replaced by [`scope_extensions`](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md), but that spec is still in development.  `scope_extensions` will produce the same result as `url_handlers`.
+However, if you make changes to the web app manifest file, you must create a new app package and submit it to the Microsoft Store again. For example, in the manifest, you might change the app icon or app name, or add manifest members such as `file_handlers`, `protocol_handlers`, or `share_target`. Creating and submitting a new app package is required when the manifest is changed, because the information in the web app manifest file is copied to the Windows app package, for better integration with Windows.
 
 
 <!-- ====================================================================== -->