Merge pull request #104 from DataRecce/docs/faq

add_update_lack_states

docs/docs/features/state-file.md

@@ -1,5 +1,5 @@
 ---
-title: Recce File
+title: Recce State File
 icon: material/file
 ---
 

docs/docs/recce-cloud/setup-gh-actions.md

@@ -21,7 +21,7 @@ We suggest setting up two GitHub Actions workflows in your GitHub repository. On
 
 ## Prerequisites
 
-1.  **Per-PR Enviornment**: To ensure that each PR has its own isolated environment, it is recommended to put `profile.yml` under source control in the repository and use environment variables to change the schema name. In the workflow, we can generate the corresponding schema name based on the PR number.
+1.  **Per-PR Environment**: To ensure that each PR has its own isolated environment, it is recommended to put `profile.yml` under source control in the repository and use environment variables to change the schema name. In the workflow, we can generate the corresponding schema name based on the PR number.
 
     ```yaml
     myprofile:

docs/docs/recce-cloud/setup-gh-codespaces.md

@@ -7,7 +7,7 @@ icon: octicons/codespaces-16
 
     Recce Cloud is currently in **private alpha** and scheduled for general availability later this year.  [Sign up](../../cloud.md#signup) to the Recce newsletter to be notified, or email [[email protected]](mailto:[email protected]) to join our design partnership program for early access.
 
-GitHub Codespaces is a development environment provided by GitHub that allows developers to have identical and isolated environments for development. The GitHub Codespaces uses VS Code Server technology. We can launch it from a GitHub pull request page, and once it is started, the Recce instance will run and port forwarding will be set up.
+GitHub Codespaces is a development environment provided by GitHub that allows developers to have identical and isolated environments for development. The GitHub Codespaces uses VS Code Server technology. We can launch it from a GitHub pull request page, and once it is started, the Recce instance will run and port forwarding will be set up. 
 
 ## Setup Recce Cloud in GitHub Codespaces
 
@@ -54,35 +54,36 @@ GitHub Codespaces is a development environment provided by GitHub that allows de
     The GitHub token [generated by codespace](https://docs.github.com/en/codespaces/developing-in-a-codespace/default-environment-variables-for-your-codespace) is sufficient for Recce's use. It's not necessary to configure the `GITHUB_TOKEN` separately.
 
 ## How to use
-
-Here, we [use GitHub Codespaces for pull requests](https://docs.github.com/en/codespaces/developing-in-a-codespace/using-github-codespaces-for-pull-requests)
-
-1. Go to the GitHub PR page that is going to be reviewed
-1. Click the **Code** button and create a Codespace on the PR branch
-   ![alt text](../../assets/images/recce-cloud/setup-codespaces-pr.png){: .shadow}
-1. Starting a Codespace instance usually takes one to several minutes.
-1. When the Recce instance starts, an **Open Browser** notification will appear. Click the button to open the Recce web UI in a new tab.
-1. Or you can go to the **PORTS** tab to open the page.
-
-
+Once you complete [Recce Cloud setup](../../recce-cloud/#sign-up-the-recce-cloud), you can launch GitHub Codespaces from Recce Cloud's pull request page, and once it is started, the Recce instance will run and port forwarding will be set up.
+ 
+1. Go to Recce Cloud and click the repository you want to make changes. 
+    ![Recce Cloud Home](../../assets/images/recce-cloud/recce-cloud-home.png){: .shadow}
+2. Click the pull request that you want to use Recce instance.  
+    ![Recce Cloud Open PR](../../assets/images/recce-cloud/recce-cloud-open-pr.png){: .shadow}
+3. Click "Create in GitHub Codespaces."
+    ![Create in GitHub Codespaces](../../assets/images/recce-cloud/create-in-codespace.png){: .shadow}
+4. The Codespaces creation may take 1 to more than 5 mintues depeding on your Codespaces settings. And the Recce instance should take less than 1 minute to launch. 
+    - Please view [FAQ](../../recce-cloud/setup-gh-codespaces/#faq) for how to speed up.
+5. You can see the "State" of the progress; And the Action you can take in each state.
+    - Codespace Queued: the Codespace is creating 
+        ![Codespace Queued](../../assets/images/recce-cloud/codespaces-queued.png){: .shadow}
+    - Codespace Provisioning: the Codespace is provisioning
+    - Codespace Available: the Codespace is ready
+    - Recce launching: Recce instance is launching
+      - Stop: stop launching Recce instance
+    - Recce active: Recce instance is launched successfully. 
+        - Open: open the Recce instance
+        - Stop: stop the Codespace
+        ![Recce active](../../assets/images/recce-cloud/recce-active.png){: .shadow}
+    - Codespace ShuttingDown: the Codespace is shutting down
+    - Stopped: the Codespace is stopped and the Recce instance is closed.
+        - Restart: restart the Codespace 
+        - Delete: delete the Codespace
+            - It’s recommended to delete the Codespace once your PR is merged. 
+
+  
 ## Troubleshooting
 
-When you’ve opened a Codespace but are unable to connect to the Recce instance, you can troubleshoot by following these steps:
-
-1. Enter the Codespace instance
-1. Click on the blue block in the lower left corner of the status bar, which usually shows "Codespaces: instance name"   
-    ![alt text](../../assets/images/recce-cloud/codespace-troubleshoot-1.png)
-1. Select "View creation log"
-1. At this point, you should be able to see the reason why the Recce server failed to start.   
-    ![alt text](../../assets/images/recce-cloud/codespace-troubleshoot-2.png)
-
-Common causes might include:
-
-1. The current branch does not have a corresponding pull request. This usually happens when the Codespace is opened on the main branch or for a closed PR.
-1. The pull request does not have an uploaded Recce state. In review mode, the Recce state must be prepared via CI or locally before proceeding.
-1. The `RECCE_STATE_PASSWORD` mentioned above is not set or the password is incorrect.
-1. Other issues are preventing the Recce server from starting at all.
-
 If this is your first time setting up a Codespace, it’s recommended to first [test locally](./getting-started-recce-cloud.md#review-the-pr) with the following commands:
 
 ```shell
@@ -94,17 +95,40 @@ recce server --cloud --review
 
 Ensure it runs correctly locally. If it does, then the remaining issues within the Codespace are likely related to its configuration.
 
+If your Codespace configration is correct, other common causes might include:
+
+1. The current branch does not have a corresponding pull request. This usually happens if you launch Codespace directly form GitHub main branch. Recce instance cannot assoicate with the main branch. 
+2. The pull request does not have an uploaded [Recce state file](../../features/state-file/). In review mode, the state file must be prepared via CI or locally before proceeding.
+3. The `RECCE_STATE_PASSWORD` mentioned above is not set or the password is incorrect.
+4. Other issues are preventing the Recce server from starting at all.
+
+When you’ve opened a Codespace but are unable to connect to the Recce instance, you can troubleshoot by following these steps:
+
+1. Check Codespace instance in GitHub. 
+    ![Check Codespace in GitHub](../../assets/images/recce-cloud/check-codespace-in-github.png){: .shadow}
+2. If the Codesapce you created from Recce Cloud is active, click "Open in Browser". 
+    ![Open Codespace in Browser](../../assets/images/recce-cloud/open-codespace-in-browser.png){: .shadow}
+3. Click on the blue block in the lower left corner of the status bar, which usually shows "Codespaces: instance name"   
+    ![Codespace status bar](../../assets/images/recce-cloud/codespace-troubleshoot-1.png)
+4. Select "View creation log" or ppen the VS Code Command Palette and type `Codespaces: View Creation Log`. 
+5. At this point, you should be able to see the reason why the Recce server failed to start.   
+    ![alt text](../../assets/images/recce-cloud/codespace-troubleshoot-2.png)
+6. If you cannot find any issue from the Codespace creation log, and belive your Codespace configration is correct. Please stop the Codespace and launch Recce instance again. 
+7. If you still have problem, please contact us via [slack](https://getdbt.slack.com/archives/C05C28V7CPP) or email [[email protected]](mailto:[email protected]). We are happy to help.
+
+
 ## FAQ
 
 **Q: How long does Codespace generally take to start?**
 
-The typical startup time is around 1 to 2 minutes. However, this depends on how your Dockerfile is configured. Codespace builds your image every time it starts, so if your Dockerfile includes multiple pip install <packages>, it may take longer.
+The typical startup time is around 1 to 2 minutes if you have prebuid. If not, it may take more than 5 mintues. However, this depends on how your Dockerfile is configured. Codespace builds your image every time it starts, so if your Dockerfile includes multiple pip install <packages>, it may take longer.
 
 Once your Codespace instance is already running, you won’t need to wait again when you return to it.
 
 **Q: Is there a way to optimize the startup speed?**
 
-Codespace offers a [prebuild](https://docs.github.com/en/codespaces/prebuilding-your-codespaces) feature, which can significantly improve startup speed. However, you need to ensure that the image is up-to-date. To strike a balance between speed and update frequency, you can consider scheduling a weekly image rebuild.
+Codespace offers a [prebuild](https://docs.github.com/en/codespaces/prebuilding-your-codespaces) feature, which can significantly improve startup speed. In our sample project, we found it's helpful to reduce prebuild when we set prebuild available to only sepecific regions. However, you need to ensure that the image is up-to-date. To strike a balance between speed and update frequency, you can consider scheduling a weekly image rebuild.
+![set prebuild in only specific retion](../../assets/images/recce-cloud/set-prebuild-specific-regions.png)
 
 **Q: Can a Codespace environment be shared? Can different people access the same Codespace instance?**
 
@@ -121,10 +145,18 @@ For more details on billing, please refer to the official [CodeSpace billing doc
 
 **Q: How to configure codespaces?**
 
-Codespace utilizes VSCode Dev Containers technology, which can be executed either locally (via Docker) or in the cloud (via GitHub Codespace). The configuration above provided are primarily recommendations for the recce cloud setup. For more advanced configuration options, you can refer to the [VSCode dev containers](https://code.visualstudio.com/docs/devcontainers/containers) or the [containers.dev](https://containers.dev/) documentation.
+Codespace utilizes VSCode Dev Containers technology, which can be executed either locally (via Docker) or in the cloud (via GitHub Codespace). The configuration above provided are primarily recommendations for the Recce Cloud setup. For more advanced configuration options, you can refer to the [VSCode dev containers](https://code.visualstudio.com/docs/devcontainers/containers) or the [containers.dev](https://containers.dev/) documentation.
 
 The default configuration for GitHub Codespace is explained in the [documentation](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers). If you're looking to set up a development environment for dbt/Recce, you can also refer to the [Python project configuration documentation](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/setting-up-your-python-project-for-codespaces).
 
 **Q: Can I have multiple devcontainer configurations? Which one is selected by default?**
 
-Yes, you can. Please refer to the [Codespaces documentation](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration) for more details. Recce Cloud will prioritize `.devcontainer/recce/devcontainer.json` if it is available. If not, it will default to `.devcontainer/devcontainer.json`, and then any other available configurations.
+Yes, you can. Please refer to the [Codespaces documentation](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/adding-a-dev-container-configuration/introduction-to-dev-containers#creating-a-custom-dev-container-configuration) for more details. Recce Cloud will prioritize `.devcontainer/recce/devcontainer.json` if it is available. If not, it will default to `.devcontainer/devcontainer.json`, and then any other available configurations.
+
+**Q: Should I delete Codespace after PR merged?**
+
+Yes. When you merged a PR, you'll see the Delete codespace message. You can delete the Codespace to save the free usage. 
+![Delete Codespace after PR merged](../../assets/images/recce-cloud/branch-merged-delete-codespace.png){: .shadow}
+
+You can also delete Codespace in your GitHub main branch or in Recce Cloud PR page. 
+![Delete Codespace in your GitHub](../../assets/images/recce-cloud/delete-codespace-in-github.png){: .shadow}