Adds SharePoint marketplace guidance (SharePoint#5851)

* Adds SharePoint marketplace guidance

* Removes optional locales from URLs

Author: waldekmastykarz

docs/spfx/publish-to-marketplace.md

@@ -0,0 +1,82 @@
+---
+title: Publish SharePoint Framework applications to the marketplace
+description: Considerations for publishing SharePoint Framework applications to the marketplace
+ms.date: 06/09/2020
+ms.prod: sharepoint
+localization_priority: Priority
+---
+
+# Publish SharePoint Framework applications to the marketplace
+
+Publishing your SharePoint Framework solutions to marketplace allows you to reach other organizations and let them easily install your application in their Microsoft 365 tenant. Following sections describe considerations that you should take into account before publishing your solutions to the marketplace.
+
+## Use SharePoint Framework v1.11 or newer
+
+We recommend that you use SharePoint Framework v1.11 or newer to build solutions that you want to publish to the marketplace. Starting from version 1.11, SharePoint Framework solution manifest has additional information about your organization and solution.
+
+In the solution's manifest (managed in the `package-solution.json` file) there is a new section named `developer` with the following properties:
+
+Attribute|Description|Mandatory
+---|---|---
+`name`|Name of the organization that built the application|Yes
+`websiteUrl`|URL of a website with additional information about the application|Yes
+`mpnId`|Microsoft Partner Network ID (more details on [MS Partner Network](https://docs.microsoft.com/partner-center/mpn-overview))|Yes (for solutions published to the marketplace)
+`privacyUrl`|Privacy statement URL|Yes
+`termOfUseUrl`|Terms of use URL|Yes
+
+Including this additional information allows you to clearly communicate information about your application towards your users and in the future should allow you to access additional usage data.
+
+The developer information is displayed when installing web parts in Microsoft Teams. Information about the application and the developer that is displayed in the marketplace is managed separately in the marketplace.
+
+> [!TIP]
+> If your application is built using an older version of the SharePoint Framework, you can easily upgrade it to SharePoint Framework v1.11 or newer using Office 365 CLI. For more information, visit [https://pnp.github.io/office365-cli/cmd/spfx/project/project-upgrade/](https://pnp.github.io/office365-cli/cmd/spfx/project/project-upgrade/).
+
+## Install applications from the marketplace in the tenant app catalog
+
+SharePoint Online allows you to create a tenant app catalog where you centrally manage applications available in your organization. Additionally, you can create site collection app catalogs, where you can deploy applications to specific sites.
+
+Applications that you acquire from the marketplace, you can install only in tenant app catalogs. After installing the application, you can decide whether you want to deploy it globally and make it available to all sites in your tenant or if you want to deploy it only to specific sites.
+
+For more information about managing SharePoint Framework solution in the app catalog visit: [https://docs.microsoft.com/sharepoint/use-app-catalog](https://docs.microsoft.com/sharepoint/use-app-catalog) and [https://docs.microsoft.com/sharepoint/dev/general-development/site-collection-app-catalog](https://docs.microsoft.com/sharepoint/dev/general-development/site-collection-app-catalog).
+
+## Permissions required to install applications from the marketplace
+
+By default, only tenant administrators can install applications from the marketplace. They can however choose to delegate the responsibility to others in your organization by granting them access to the tenant app catalog.
+
+SharePoint Framework applications execute on behalf of the current user and can do whatever the current user can do. Because of this, only tenant app catalog administrators can install applications from the marketplace. Users who are not app catalog administrators can request a specific application to be installed by the app catalog administrator, but they cannot install the application themselves.
+
+## Use auto-generated Microsoft Teams manifest
+
+When building SharePoint Framework web parts, you can choose to [expose them in SharePoint and Microsoft Teams as personal apps or tabs](https://docs.microsoft.com/sharepoint/dev/spfx/integrate-with-teams-introduction). To use your web parts in Teams you can either generate the manifest and the Teams solution package yourself or have the SharePoint Framework generate it for you. Creating the manifest manually gives you more flexibility and allows you to create multi-tab personal apps.
+
+At this moment, the marketplace does not support embedding custom Teams manifests in SharePoint Framework packages. You can expose your web parts in Teams using the manifest auto-generated by SharePoint Framework.
+
+If your web part requires configuration and you expose it as a personal Teams app, you need to implement a custom UI yourself to allow users to configure it.
+
+## Notify users of new versions
+
+As you update your application, you should notify your users when an updated version is available. The marketplace does not offer any version checking mechanism and you should implement it your application so that notifications are meaningful and as unobtrusive as possible. In your code you can for example call a custom API that you own to compare the current version of the application with the latest version available.
+
+Tenant app catalog administrators can update applications acquired from the marketplace directly from the app catalog, by selecting the application in the app catalog and from the ribbon choosing the **Upgrade Store App** option. When the upgrade succeeds, the latest version will be automatically visible to users in all sites where the application has been installed.
+
+## Applications listed in the SharePoint category
+
+All SharePoint Framework applications published in the marketplace are listed in the **SharePoint** category. At this moment, it is not possible to specify a custom category. Also, even if you configured web parts in your application to be exposed in Microsoft Teams, the application will still be listed in the **SharePoint** category.
+
+## Frequently asked questions
+
+### Is it required to configure web parts to be isolated for publishing in the marketplace
+
+No, it is not required to configure web parts to be isolated. It is fully up to you to decide if your web parts should be isolated or not and you can use either mode in the application you publish to the marketplace.
+
+### Can I request additional API permissions for my solution
+
+Yes, if your solution needs additional API permissions to work as intended, then you should request these permissions to be granted in your solution’s manifest. Please note, that the marketplace verification team could ask you to justify access to the permissions that you have requested when verifying your submission.
+
+### Can I expose my web parts in Office add-ins
+
+At this moment exposing SharePoint Framework web parts in Office add-ins is in preview and is not yet supported in solutions published in the marketplace.
+
+### Can I include library components in my solution
+
+Yes, library components are fully supported in solutions published to the marketplace.

docs/spfx/toolchain/sharepoint-framework-toolchain.md

@@ -1,7 +1,7 @@
 ---
 title: SharePoint Framework toolchain
 description: The toolchain is the set of build tools, framework packages, and other items that manage building and deploying your SharePoint Framework client-side projects.
-ms.date: 01/12/2018
+ms.date: 06/16/2020
 ms.prod: sharepoint
 localization_priority: Priority
 ---