created first run at documentation

.gitattributes

@@ -1,2 +1,3 @@
 pac/**/* filter=lfs diff=lfs merge=lfs -text
+/readme-assets/**/* filter=lfs diff=lfs merge=lfs -text
 pac/**/*.* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,18 +1,64 @@
-# Project
+# Power Apps Portals ALM Sample
 
-> This repo has been populated by an initial template to help get you started. Please
-> make sure to update the content to build a great experience for community-building.
+This project provides a starting point for applying ALM best practices to your Power Apps Portals projects. It adopts two major tenets:
 
-As the maintainer of this project, please make a few updates:
+- Establish source control as the definitive source of truth
+- Fully automate commits, builds, and deployments.
 
-- Improving this README.MD file to provide a great experience
-- Updating SUPPORT.MD with content about this project's support experience
-- Understanding the security reporting process in SECURITY.MD
-- Remove this section from the README
+## Prerequisites
+
+- A GitHub account
+- Access to two existing Dataverse environments (one for "development" and one for "production")
+  - **Note:** The environments do not both need to be in the same tenant.
+  - One [Dataverse starter portal](https://docs.microsoft.com/en-us/powerapps/maker/portals/create-portal) provisioned in each environment
+  - One [application user](https://docs.microsoft.com/en-us/power-platform/admin/manage-application-users) with the System Administrator role in each environment
+    - **Note:** You can either use a single application user for both environments (if they are in the same tenant) or a separate application user for each environment.
+- (Optional) [GitHub Enterprise](https://docs.github.com/en/get-started/learning-about-github/githubs-products#github-enterprise)
+
+## Setup
+
+1. Either fork this repository or [use it as a template](https://github.com/microsoft/power-apps-portals-alm/generate).
+   ![Screenshot creating a new public repository using this one as a template](./readme-assets/create-repository-from-template.png)
+   - **Note:** Because this project uses [environments](https://docs.github.com/en/actions/reference/environments), you must create either a public repository or a private repository for GitHub Enterprise.
+2. Set up the environments in your repository (outlined below):
+   1. From your repository home page, click **Settings**.
+   2. Click **Environments**.
+   3. Click **New environment**.
+   4. For the name, type _development_. Click **Configure environment**.
+   5. Under **Environment secrets**, click **Add Secret**.
+   6. For **Name**, type _URL_.
+   7. For **Value**, provide the URL of your development environment, e.g. *https://my-awesome-dev.crm.dynamics.com/*.
+   8. If you are using separate application users for each environment, or if you are using separate tenants, repeat steps 5-7 to create the following secrets:
+      - **APPLICATION_ID**: Application (client) ID of your application user, e.g. _01234567-89ab-cdef-0123-456789abcdef_
+      - **CLIENT_SECRET**: A client secret for your application user, e.g. _1f7~GP48Pi17T-R.4uyIU7_kOiV2NCnH_Q_.
+      - **TENANT_ID**: The Directory (tenant) ID that your development environment is provisioned in, e.g. _fedcba98-7654-3210-fedc-ba9876543210_.
+   9. Repeat steps 1-8 for your production environment.
+3. If you are using a single application user for both environments, add its information to your repository as secrets (outlined below):
+   1. In the left-hand navigation of your repository's Settings page, click **Secrets**.
+   2. Click **New repository secret**.
+   3. For **Name**, type _APPLICATION_ID_.
+   4. For **Value**, provide the application (client) ID of your application user, e.g. _01234567-89ab-cdef-0123-456789abcdef_.
+   5. Repeat steps 2-4 to create the following secrets:
+      - **CLIENT_SECRET**: A client secret for your application user, e.g. _1f7~GP48Pi17T-R.4uyIU7_kOiV2NCnH_Q_.
+      - **TENANT_ID**: The Directory (tenant) ID that your development environment is provisioned in, e.g. _fedcba98-7654-3210-fedc-ba9876543210_.
+
+When you're finished with steps 2-3, your Secrets page should look like one of the following:
+
+- If you are using a single application user for both environments:
+  ![Screenshot of Secrets page with two environment secrets and three repository secrets](./readme-assets/one-application-user-secrets.png)
+- If you are using one application user per environment:
+  ![Screenshot of Secrets page with eight environment secrest and no repository secrets](./readme-assets/two-application-users-secrets.png)
+
+4. Run the **Provision Dev** workflow (outlined below):
+    1. Click **Actions**.
+    2. Click **Provision Dev**.
+    3. Click **Run workflow** > **Run workflow**.
+
+5. (Optional) Using the same steps outlined in step 4, run the **CI/CD** workflow.
 
 ## Contributing
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+This project welcomes contributions and suggestions. Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
 the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
 
@@ -26,8 +72,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 
 ## Trademarks
 
-This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
-trademarks or logos is subject to and must follow 
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
+trademarks or logos is subject to and must follow
 [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
 Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
 Any use of third-party trademarks or logos are subject to those third-party's policies.

SUPPORT.md

@@ -1,25 +1,13 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/spot](https://aka.ms/spot). CSS will work with/help you to determine next steps. More details also available at [aka.ms/onboardsupport](https://aka.ms/onboardsupport).
-- **Not sure?** Fill out a SPOT intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
-## How to file issues and get help  
+## How to file issues and get help
 
-This project uses GitHub Issues to track bugs and feature requests. Please search the existing 
-issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
+This project uses GitHub Issues to track bugs and feature requests. Please search the existing
+issues before filing new issues to avoid duplicates. For new issues, file your bug or
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
+For help and questions about using this project, please contact [Melody Hogsett](mailto:mhogsett@microsoft.com).
 
-## Microsoft Support Policy  
+## Microsoft Support Policy
 
-Support for this **PROJECT or PRODUCT** is limited to the resources listed above.
+Support for this project is limited to the resources listed above.

readme-assets/create-repository-from-template.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2816a98fe99ea7ba037ccd22ffcf9d7e68318d7352538e0c429f36cde048e3ce
+size 130878

readme-assets/one-application-user-secrets.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f433a1071ae70d50cdb3aac96923fa1ab302ba271e0a94150dfb69bac77ecedd
+size 88866

readme-assets/two-application-users-secrets.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:54f66339ee651353a25aafb3d4f2c1a9d1ab8360497ab1fff9c740a66d2a86f4
+size 179406