Fix #5073, #5062, #5099, and part of #1723: Improve Onboarding Documentation

.github/PULL_REQUEST_TEMPLATE.md

@@ -21,4 +21,5 @@ If your PR includes UI-related changes, then:
 - Add screenshots for portrait/landscape for both a tablet & phone of the before & after UI changes
 - For the screenshots above, include both English and pseudo-localized (RTL) screenshots (see [RTL guide](https://github.com/oppia/oppia-android/wiki/RTL-Guidelines))
 - Add a video showing the full UX flow with a screen reader enabled (see [accessibility guide](https://github.com/oppia/oppia-android/wiki/Accessibility-A11y-Guide))
+- For PRs introducing new UI elements or color changes, both light and dark mode screenshots must be included
 - Add a screenshot demonstrating that you ran affected Espresso tests locally & that they're passing

wiki/Bazel-Setup-Instructions-for-Windows.md

@@ -66,6 +66,8 @@ sudo dnf install java-1.8.0-openjdk
 ```
 - Set the default Java version to jdk-8 by running the following command `sudo update-alternatives --config java` and selecting the number with jdk-8.
 
+#### Follow [these instructions](https://www.java.com/en/download/help/path.html) to correctly set up $JAVA_HOME.
+
 **Python 2**
 
 Unfortunately, some of the Bazel build actions in the Android pipeline require Python 2 to be installed:

wiki/Guidance-on-submitting-a-PR.md

@@ -153,6 +153,7 @@ You have successfully created a pull request! Now, wait for your code to get rev
 ### Clarification regarding **Assignees** and **Reviewers** section.
 1. **Reviewers**: This section is generally ignored by anyone who looks at the PR. It will be filled automatically by Oppiabot. Once this section is filled out, it generally should not change throughout the timeline of the PR.  
 2. **Assignees**: The main section to look at is the 'Assignees' field, which indicates the person(s) whom the PR is currently blocked on. Specifically:
+   - When a PR is created, the assignees section is blank. You can assign a reviewer by leaving a comment on the PR mentioning the reviewer, e.g "@Reviewer, PTAL". **Oppiabot** will assign the reviewer for you.
    - Initially, when the PR is submitted, the **Assignees** and **Reviewers** sections should be the same. 
    - Once a reviewer has reviewed the PR, they should de-assign themselves and assign it back to the PR author.
    - Similarly, once the author has made the requested changes, they should assign it back to the appropriate reviewer and de-assign themselves.

wiki/Installing-Oppia-Android.md

@@ -7,22 +7,25 @@ This wiki page explains how to install Oppia Android on your local machine. If y
 - [Prepare developer environment](#prepare-developer-environment)
 - [Install oppia-android](#install-oppia-android)
 - [Run the app from Android Studio](#run-the-app-from-android-studio)
+- [Run the tests](#set-up-and-run-tests)
 
 
 ## Prepare developer environment
 
-1. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 
+1. Download/Install [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 
+
+   **Note**: We recommend installing **Android Studio Bumblebee** because newer versions of Android Studio[ do not support running tests where shared source sets are used](https://issuetracker.google.com/issues/232007221#comment18), a configuration we use at Oppia.
+
+   **Direct download Url**: [Windows](https://redirector.gvt1.com/edgedl/android/studio/install/2021.1.1.23/android-studio-2021.1.1.23-windows.exe) | [Linux](https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2021.1.1.23/android-studio-2021.1.1.23-linux.tar.gz) | [Intel Mac](https://redirector.gvt1.com/edgedl/android/studio/install/2021.1.1.23/android-studio-2021.1.1.23-mac.dmg) | [Apple Silicon Mac](https://redirector.gvt1.com/edgedl/android/studio/install/2021.1.1.23/android-studio-2021.1.1.23-mac_arm.dmg)
 
-2. Download and Install **Java 8** using the links from [the Java website](https://www.java.com/en/download/).
-   - **Note for Windows users:** Make sure to also set up the PATH system variable correctly for `Java`, following [these instructions](https://www.java.com/en/download/help/path.html).
-   - [Instructions](https://www.java.com/en/download/help/linux_install.html) for Linux users.
-   - [Instructions](https://www.java.com/en/download/help/mac_install.html) for Mac users.
+   You can have multiple versions of Android Studio installed on your machine at the same time.
 
-3. In Android Studio, open Tools > SDK Manager.
-   - In the "SDK Platforms" tab (which is the default), select `API Level 28` and also `API Level 31` (for Bazel support).
-   - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 34-rc1" and select 29.0.2 (this is needed for Bazel support).
+2. Configure your Android Studio
+   - In Android Studio, open Tools > SDK Manager.
+     - In the "SDK Platforms" tab (which is the default), select `API Level 28` and also `API Level 31` (for Bazel support).
+     - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 34-rc1" and select 29.0.2 (this is needed for Bazel support).
 
-   Then, click "Apply" to download and install these two SDKs/Tools.
+   - Then, click "Apply" to download and install these two SDKs/Tools.
 
 ## Install oppia-android
 
@@ -32,7 +35,7 @@ Please follow these steps to set up Oppia Android on your local machine.
 
    **Note**: Please keep the folder name as `oppia-android`. Changing the project folder name might lead to future issues with running the pre-push checks on your machine.
 
-2. Run the setup script, which adds some development tools for Oppia Android (ktlint, checkstyle, etc.):
+2. Run the `bash scripts/setup.sh` script, which adds some development tools for Oppia Android (ktlint, checkstyle, etc.): These tools perform pre-push checks to ensure that your code is properly formatted as per Oppia standards.
 
     - For Mac or Linux
        1. Open a terminal and navigate to `opensource/oppia-android/`.
@@ -47,19 +50,25 @@ Please follow these steps to set up Oppia Android on your local machine.
 
     - For Windows
        1. Install [Git Bash Command Line](https://gitforwindows.org/)
+
+          **Note**: When installing Git bash, check the option to add it to powershell, so that you can run bash commands from within powershell. 
        2. Open Git Bash Command Line.
-       3. Navigate to `opensource/oppia-android/`.
+       3. Navigate to `opensource\oppia-android\`.
        4. Run the script `bash scripts/setup.sh`.
-       5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/14005e371803bd52dff429904b354dc3e72638c0/src/main/resources/google_checks.xml) file. To do this, you can simply right-click on the `Raw` button and click on `Save Link as`.
+       5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/14005e371803bd52dff429904b354dc3e72638c0/src/main/resources/google_checks.xml) file. To do this, you can simply right-click on the download button at the top-right of the file.
        6. Copy this file to the directory where Git is installed (usually C:/Program Files/Git/).
 
 3. In Android Studio, select `File > Open`, navigate to `opensource/oppia-android/`, and click `OK` to load the project.
 
-4. Click the elephant icon in the toolbar ("Sync Gradle") to ensure that all the correct dependencies are downloaded. (In general, you'll want to do this step any time you update your dependencies.)
+4. Select the Compile JDK version
+   - Go to Android Studio > Settings > Build, Execution, Deployment > Build Tools > Gradle
+   - Under "**Gradle JDK**", select Android Studio Default JDK 11.
+   - Then, click "Apply" and "OK" to complete your setup.
+5. Click the elephant icon in the toolbar ("Sync Gradle") to ensure that all the correct dependencies are downloaded. (In general, you'll want to do this step any time you update your dependencies.)
 
 ## Run the app from Android Studio
 
-1. Go to Tools > Device manager, click "Create Virtual Device...". Then:
+1. Go to Tools > AVD Manager, click "Create Virtual Device...". Then:
 
    - Select a preferred device definition. In general, any device is fine, but you can use Pixel 3a as a default (if you're developing for phones) or Nexus 7 (if you're developing for tablets). After selecting a device, click "Next" at the bottom right to continue.
    - Select a system image (in general, API Level 28, unless you're an M1 Mac user, in which case use API Level 29). Then click "Next".
@@ -68,3 +77,49 @@ Please follow these steps to set up Oppia Android on your local machine.
 2. To run the app, select the emulator device you want from the dropdown menu to the left of the "Run" button in the toolbar.
 
 3. Finally, click the "Run" button.
+
+## Set up and run tests
+Testing the app is an integral part of our development process. You will need to test all code changes to ensure that the app works correctly, therefore it is important to ensure that your test configuration works.
+
+We run tests in either Espresso(`app` module tests) or Robolectric(non-app module tests), meaning tests will run in either the emulator or on Gradle/Bazel via the terminal.
+
+### Configure Emulator Tests
+1. In Android Studio, open the desired test file, e.g., `HomeActivityTest`.
+2. In the Android Studio toolbar, click on the `Available Devices` option. Select an emulator that has between API 28-30.
+
+   **Note**: If you don't have any available devices in this list, please follow [these instructions](#run-the-app-from-android-studio) to create one.
+3. In the test file, to the left of the class name, click on the orange and green arrow, and select **Run 'HomeActivityTest'**.
+![](https://user-images.githubusercontent.com/59600948/272657131-96e5354b-13a9-4709-969a-b9494a65c30f.png)
+4. An "**Edit Configuration**" dialog will show up, and you should add the following settings under the general tab:
+   - For module, select **oppia-android.app**
+   - For Test, select **Class**
+   - For Instrumentation class, **org.oppia.android.testing.OppiaTestRunner**, will be selected by default.
+   - For target, select the **Use the device/snapshot dropdown** option.
+   - Verify that your setup looks like below:
+   -![](https://user-images.githubusercontent.com/59600948/272657260-2e654891-61be-467a-8ebd-c997aa2abda6.png)
+- Finally, Click the "Apply" and "Okay" buttons.
+- You may need to repeat step (3) above to run the test with the new configuration.
+- Subsequent runs of any app module tests will not require editing the configuration.
+- This configuration will run all the tests in that class.
+5. To run only a specific test in a file:
+   - Search or scroll down to the desired test name, to the left of the test name, click on the run icon and select **Run '`test name`''**.
+
+### Configure Robolectric Tests
+These are tests that are in non-app modules, such as **domain** or **utility**.
+1. In Android Studio, open the desired test file, e.g., `AnalyticsControllerTest`.
+2. In the test file, to the left of the class name, click on the orange and green arrow, and select **Run 'AnalyticsControllerTest'**.
+   - You will notice that the emulator is greyed out, but the run window will open to show the running tests:
+   - ![](https://user-images.githubusercontent.com/59600948/272657015-158117e5-47d2-40fc-a38b-5dee6c347556.png)
+
+### Next Steps
+- Congratulations, you are ready to work on your first issue! Take a look at our [good first issues](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) and leave a comment with your suggested fix. A maintainer will assign you the issue and provide any necessary guidance.
+
+- When you are ready to submit a PR, please follow [these instructions](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) on submitting a PR.
+
+- To learn about how we write tests at oppia-android, please refer to: [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing).
+
+- To get started with Bazel, please see [Oppia-Bazel-Setup-Instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions) and follow the instructions appropriate to your OS.
+
+- If you run into any issues during your setup, search our [discussions](https://github.com/oppia/oppia-android/discussions) forum or start a new discussion.
+
+- Please see  [Troubleshooting-Installation](https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation) for solutions to some common setup issues.

wiki/Oppia-Bazel-Setup-Instructions.md

@@ -12,15 +12,17 @@
 ## Overview
 Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. It uses a human-readable, high-level build language.
 
+**WARNING: We recommend to not use the Android Studio Bazel plugin since it currently has compatibility issues with the project.**
+
 ### Installation
 
-**WARNING: We recommend to not use the Android Studio Bazel plugin since it currently has compatibility issues with the project.**
+1. Download and Install Java 8 using the links from the [Java website](https://www.java.com/en/download/).
 
-**Instructions for setting up Bazel on different Operating Systems:**
+2. **Select your Operating System for instructions on setting up Bazel:**
 
-- [For Windows/Ubuntu/Fedora](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Windows)
-- [For Mac including M1/M2](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Mac)
-- [For Linux](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Linux)
+   - [For Windows/Ubuntu/Fedora](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Windows)
+   - [For Mac including M1/M2](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Mac)
+   - [For Linux](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Linux)
 
 ### Building the app
 

wiki/_Sidebar.md

@@ -15,9 +15,9 @@
     * [Overview of the Oppia Android codebase and architecture](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture)
   * Bazel
     * [Bazel setup instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)
-    * [Bazel Setup Instructions for Linux](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Linux)
-    * [Bazel Setup Instructions for Mac](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Mac)
-    * [Bazel Setup Instructions for Windows](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Windows)
+      * [Bazel Setup Instructions for Linux](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Linux)
+      * [Bazel Setup Instructions for Mac](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Mac)
+      * [Bazel Setup Instructions for Windows](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Windows)
   * Key Workflows
     * [Guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR)
     * [Creating a screenshot](https://github.com/oppia/oppia-android/wiki/Creating-a-screenshot)