+
+### Possible solution to fix it
+
+1. Change the fixed width to wrap_content and set minWidth. In this case, we can’t directly change the width into a wrap_content as all thumbnail images won’t have consistent width which leads to a problem as mentioned in issue [#4684](https://github.com/oppia/oppia-android/issues/4684). You can see the below screenshot for reference.
+
+
+
+2. As directly we can’t use wrap_content for width, another possible solution is to use scalable width i.e. instead of setting fixed width in dp we can set the width in sp. This will increase the container size every time we increase the font size, so the scaled text can fit inside the container. In this approach, accessibility scanner will still show suggestion to improve text scaling but from a UI perspective this approach works. For reference you can look at PR [#4695](https://github.com/oppia/oppia-android/pull/4695)
+
+3. Another approach would be to design such that we don’t have to fit a text inside a fixed width container as shown below in the reference image.
+
+
+
+We can set the full width to the cards i.e. match_parent (with appropriate margins) which will remove the issue of accessibility. We can also show the dots at bottom which represent the number + position of items.
+
+
+
+For sighted users
+- The banners will be cyclic i.e. item-0, item1, item2, item0 and repeat.
+
+For talkback users
+- The cyclic nature will stop.
+- The screen reader will start from item-0, item-1, item-2, and next it will go out of list.
+
+
diff --git a/wiki/Background-Processing.md b/wiki/Background-Processing.md
new file mode 100644
index 00000000000..c7a4aecb665
--- /dev/null
+++ b/wiki/Background-Processing.md
@@ -0,0 +1,46 @@
+## Overview
+
+This page aims to provide some context around:
+- What constitutes background processing/when something should be background processed, and why we care
+- How background processing is done in the Android app
+- Best practices to follow when managing background or expensive tasks
+- Existing utilities to simplify using DataProviders
+- How to safely pass data to the UI
+
+## Background
+
+Performing asynchronous tasks or background processing in a multi-threaded environment is hard: most developers are unaware of the nuances of cross-thread development (e.g. properly utilizing critical sections without introducing deadlocks, sharing mutable state across thread boundaries with correctly applied memory fences, critical sections, or atomics, properly using concurrent data structures, and more). This problem is exacerbated in Android since:
+1. Android requires all user-facing operations to be run on the main thread (requiring communication to/from the main thread)
+2. Android UI objects are very [lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle)-sensitive (meaning haphazard management of Android state can at best leak memory or at worst crash when communicating back from a background thread--a common crash in Android apps)
+3. The Android UI thread is sensitive to even medium-length operations when on slow devices (which can lead to app [ANR](https://developer.android.com/topic/performance/vitals/anr)s)
+
+The team has a number of carefully considered solutions to ensure concurrency is easier to manage, safer, and performant.
+
+### Definition of background processing & when to use it
+
+All features in the codebase can be represented as a data pipeline. In some cases, data is created transiently and in other cases it needs to be loaded from somewhere (e.g. a file or network). Further, we sometimes need to do a lot of processing on this data before it can be presented to the UI (the app's [architecture](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture#app-architecture) is specifically designed to encourage data processing logic to live outside the UI).
+
+To keep things simple, we consider everything the following to be worth executing on a background thread instead of the UI thread:
+- Any logic operation (e.g. something requiring an if statement or loop) which is more complicated than just copying data
+- Any file I/O operations (e.g. reading from a file)
+- Any networking operations (e.g. calling into Retrofit)
+- Complex state management (such as [ExplorationProgressController](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/domain/src/main/java/org/oppia/android/domain/exploration/ExplorationProgressController.kt#L34))
+
+Similarly, the following operations must happen on a UI thread for lifecycle safety reasons:
+- Any interactions with the UI (e.g. activities, fragments, or views)
+- Any interactions with ViewModel state (which is designed to only be mutated on the main thread)
+- Any interactions with other Android services which require main thread access
+
+### Why we care
+
+Oppia Android is aiming to provide an effective education experience to the most underprivileged communities in the world, and this particularly requires excellent performance on low-end devices. We have a thin performance margin to operate in, and we can't afford ANRs or poor performance. Further, reducing crashes is important to ensure an uninterrupted learning experience (especially for children who might not understand how to recover the app from a crash).
+
+That being said, the difficulty in writing correct & performant concurrent code is quite high. We want to make sure we achieve that with a lower barrier-to-entry so that team members don't have to manage especially complex code.
+
+## Background processing & concurrency in Oppia Android
+
+To ensure the team is meeting the goals of reducing concurrency complexity while not sacrificing performance or correctness, we require that all code utilize the patterns & best practices outlined in this section.
+
+- [Kotlin Coroutines](https://github.com/oppia/oppia-android/wiki/Kotlin-Coroutines)
+- [DataProvider & LiveData](https://github.com/oppia/oppia-android/wiki/DataProvider-&-LiveData)
+- [PersistentCacheStore & In Memory Blocking Cache](https://github.com/oppia/oppia-android/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache)
\ No newline at end of file
diff --git a/wiki/Bazel-Setup-Instructions-for-Windows.md b/wiki/Bazel-Setup-Instructions-for-Windows.md
new file mode 100644
index 00000000000..4425a088cee
--- /dev/null
+++ b/wiki/Bazel-Setup-Instructions-for-Windows.md
@@ -0,0 +1,167 @@
+## Overview & Disclaimer
+
+This page outlines one way to allow Bazel to be used in CLI form on Windows. Please note that **this support is currently experimental**. You may run into some problems--we suggest that you [file an issue](https://github.com/oppia/oppia-android/issues/new/choose) ior contact us at [gitter](https://gitter.im/oppia/oppia-android).
+
+Unlike Unix-based systems where Bazel runs natively without issue, the current solution on Windows is to install an Ubuntu-based subsystem. Windows currently only supports a terminal experience in this subsystem (though there is a prerelease version of the software with GUI support) which means Android Studio will not be supported. You will need to continue using the Windows version of Android Studio and only use the Linux subsystem for building & running Robolectric or JUnit-based tests.
+
+## Instructions
+
+**Main prerequisites**:
+- Windows 10: These instructions are geared towards users of Windows 10 (older versions will not be compatible). If you're in using an older version of Windows, please follow up with a comment on [this issue](https://github.com/oppia/oppia-android/issues/3371).
+- At least 4GB of free local disk storage space (for Linux & needed dependencies), but more will probably help when building the app
+
+Also, note that these instructions *replace* the standard Oppia Bazel [set-up instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions) since different steps are required for Windows with an Ubuntu subsystem.
+
+At a high-level, the steps to make Bazel work on Windows are:
+1. Install the Ubuntu subsystem
+2. Install prerequisite debian packages
+3. Install the Android SDK
+4. Install Bazel
+5. Set up the environment to be able to build Oppia Android
+6. Verify that the build is working
+7. Run Bazel commands as needed during development
+
+### 1. Install Ubuntu subsystem
+
+Please follow Microsoft's [setup instructions](https://docs.microsoft.com/en-us/windows/wsl/install-win10) to set up the Linux subsystem on Windows 10. From there, you should install **Ubuntu** (the instructions below are based on the apt package manager on Ubuntu; other Linux distributions & package managers may work but they are untested by the team).
+
+Once installed, open the Ubuntu terminal from the start menu.
+
+### 2. Prerequisite debian packages
+
+From within the Ubuntu terminal, start by ensuring all packages are up-to-date:
+
+```sh
+sudo apt update && sudo apt upgrade
+```
+
+After that, follow each of the subsections below as needed to install prerequisite dependencies:
+
+**Java**
+
+JDK 8 is required for the Android build tools, and we suggest installing OpenJDK:
+
+```sh
+sudo apt install openjdk-8-jdk-headless
+```
+
+**Python 2**
+
+Unfortunately, some of the Bazel build actions in the Android pipeline require Python 2 to be installed:
+
+```sh
+sudo apt install python
+```
+
+### 3. Installing the Android SDK
+
+We need to be able to run Linux-compatible Android utilities which requires installing a Linux version of the Android SDK. Since we can't install Android Studio in the subsystem, we need to do this via CLI commands. The steps below are extracted from [this article](https://proandroiddev.com/how-to-setup-android-sdk-without-android-studio-6d60d0f2812a).
+
+First, prepare the environment for the SDK by creating the default directory to hold the SDK (from within Ubuntu terminal):
+
+```sh
+mkdir -p $HOME/Android/Sdk
+```
+
+Second, navigate to https://developer.android.com/studio#command-tools in a web browser (in Windows) and select to download the latest **Linux** command tools (even though you're using Windows, the Linux commandline tools are needed--the Windows version will not work with these instructions). Once downloaded, copy the zip file to the new SDK location (note that the ``/c/mnt/...`` path is based on ``C:\Users\+**Note: Currently, Buf is not available for windows.** + +## Commands + +* Check the version of the buf. As of now on GitHub Actions, we are using `0.37.1`.
+`../oppia-android-tools/YOUR_BUF_FILE_NAME --version` +* Lint check
+`buf lint --config buf.yaml` + +## Configuration File + +We have a configuration file `buf.yaml` at the root of the project. Following is the list of things we are checking and the list of things we are excluding from our check. + +#### Checking: +* `DIRECTORY_SAME_PACKAGE` checks that all files in a given directory are in the same package. + * All proto files should be in the same package + +* `PACKAGE_SAME_DIRECTORY` checks that all files with a given package are in the same directory. + * All proto files with the same package name should be in the same directory + +* `PACKAGE_SAME_JAVA_MULTIPLE_FILES` checks that all files with a given package have the same value for the java_multiple_files option. + * All proto files should have the same value `option java_multiple_files = true;` + +* `PACKAGE_SAME_JAVA_PACKAGE` checks that all files with a given package have the same value for the java_package option. + * All proto files should have the same value `option java_package = "path.to.your.proto.directory";` + +* `ENUM_NO_ALLOW_ALIAS` checks that enums do not have the allow_alias option set. + * Should not allows multiple enum values to have the same number. + +* `FIELD_NO_DESCRIPTOR` checks that field names are not named capitalization of "descriptor" with any number of prefix or suffix underscores. + * No `descriptor` field name should be there, example - `descriptor`, `Descriptor`, `descRiptor`, `_descriptor`, `descriptor_`, `__descriptor__` + +* `IMPORT_NO_PUBLIC` checks that imports are not public. + * Import should not be declared as `public`, example - `import public "x.y.proto"` + +* `IMPORT_NO_WEAK` checks that imports are not weak. + * Import should not be declared as `weak`, example - `import weak "x.y.proto"` + +* `PACKAGE_DEFINED` checks that all files have a package defined. + * All proto files must have a package name specify in it, for example - `package model;` + +* `ENUM_PASCAL_CASE` checks that enums are PascalCase. + * Enum name should be in pascal case, example - `AudioLanguage` + +* `ENUM_VALUE_UPPER_SNAKE_CASE` checks that enum values are UPPER_SNAKE_CASE. + * Enum value should be in upper snake case + +* `FIELD_LOWER_SNAKE_CASE` checks that field names are lower_snake_case. + * Field name should be in lower snake case + +* `MESSAGE_PASCAL_CASE` checks that messages are PascalCase. + * Message should be in Pascal case, example - `ProfileAvatar` + +* `ONEOF_LOWER_SNAKE_CASE` checks that oneof names are lower_snake_case. + * Oneof should be a lower snake case + +* `PACKAGE_LOWER_SNAKE_CASE` checks that packages are lower_snake.case. + * Package should be lower snake case, example - `model` + +* `ENUM_ZERO_VALUE_SUFFIX` checks that enum zero values are suffixed with `_UNSPECIFIED` (the suffix is configurable). + * All the enum whose value is zero should be suffixed with `_UNSPECIFIED`, example - `AUDIO_LANGUAGE_UNSPECIFIED = 0;` + +* `FILE_LOWER_SNAKE_CASE` checks that filenames are lower_snake_case. + * All the proto file names are should be in lower snake case, for example - `topic.proto` + +#### Excluding: +* `PACKAGE_DIRECTORY_MATCH` checks that all files are in a directory that matches their package name. + * this verifies that all files that declare a given package foo.bar.baz.v1 is in the directory foo/bar/baz/v1 relative to the root + +* `ENUM_VALUE_PREFIX` checks that enum values are prefixed with `ENUM_NAME_UPPER_SNAKE_CASE`. + * `enum Foo { FOO_ONE = 0; }` + +* `PACKAGE_VERSION_SUFFIX` checks that the last component of all packages is a version of the form v\d+, v\d+test.*, v\d+(alpha|beta)\d+, or v\d+p\d+(alpha|beta)\d+, where numbers are >=1. + * `foo.v1` , `foo.bar.v1alpha1` , `foo.bar.v1beta1` , `foo.bar.v1test` diff --git a/wiki/Coding-style-guide.md b/wiki/Coding-style-guide.md new file mode 100644 index 00000000000..37773d4305e --- /dev/null +++ b/wiki/Coding-style-guide.md @@ -0,0 +1,79 @@ +Please follow the following style rules when writing code, in order to minimize unnecessary back-and-forth during code review. + +## General +- We follow the [Kotlin Android style guide](https://developer.android.com/kotlin/style-guide). +- Use 2 spaces for indentation and 4 spaces for continuation, per https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation. (This should be configured at the project level for Kotlin. Ensure that you're using the project configuration for Kotlin in your IDE, so that you can reformat the code via the IDE if needed.) +- Never commit a PR which includes commented-out code. +- Ensure that your code looks consistent with the code surrounding it. +- Ensure that the indentation of your code is correct. +- In general, avoid leaving multiple consecutive blank lines. Collapse them into a single one. +- The last character in each file should always be a newline. (If it's not, you'll see a red symbol at the end of the file when you look at the "Files Changed" tab in GitHub.) +- Make sure to remove temporary code (e.g. log statements or toasts to help with local debugging) before pushing to GitHub. +- Do not check any build artifacts into GitHub. + +## Code Formatting +Reformat all edited files automatically in android studio using the following command. +- Windows: `Ctrl + Alt + L` +- Linux: `Ctrl + Shift + Alt + L` +- macOS: `Option + Command + L` +- Ubuntu users might face issue because `Ctrl + Alt + L` locks the screen by default nature. Refer to this [stackoverflow-link](https://stackoverflow.com/questions/16580171/code-formatting-shortcut-in-android-studio) on how to solve this. + +Alternatively, you can also use the in-built Android Studio option to reformat by selecting to `Code -> Reformat Code/File`. + +
+
+NOTE: This does not guarantee 100% formatting of code as per guidelines but will be very helpful in indentation and extra spaces.
+
+## Comments
+- Ensure that comments have correct grammar, spelling and capitalization.
+- Vertically align the `*`s on the left side of a multi-line comment.
+- Wrap Javadoc comments to the 120 character limit.
+- Put new lines between Javadoc paragraphs.
+- Do not leave any spaces between a Javadoc and the class/method/field that it's documenting.
+- When writing TODOs, refer to an issue number on the GitHub issue tracker. E.g. `TODO(#1234): Do X, Y and Z.`
+
+## XML files
+- Do not declare values directly in the XML file. Declare them in the corresponding resource file and use that variable.
+
+For example:
+- For a dimension, declare it in dimens.xml file.
+- For a string, declare it in strings.xml file.
+- For a color, declare it in colors.xml file.
+
+In general, avoid using hard-coded strings.
+
+## Java/Kotlin files
+- Separate adjacent functions or blocks of code by a single blank line.
+- Do not use "magic numbers" in code. Declare constants instead (typically at the module level).
+- Order imports alphabetically. Remove unused imports. You can make use of the in-built Android Studio option to optimise imports by selecting `Code -> Optimise Imports`.
+
+
+
+
+## Layout files
+- Each layout file should be named according to how they are used, where all layouts fall in the following buckets:
+ - Activities: _screen\_name\_activity.xml_ (all end with ``_activity.xml``)
+ - Fragments: _subscreen\_name\_fragment.xml_ (all end with ``_fragment.xml``)
+ - Custom views: _custom\_widget\_name\_view.xml_ (all end with ``_view.xml``)
+ - RecyclerView items: _element\_name\_item.xml_ (all end with ``_item.xml``)
+ - Toolbars: _screen\_location\_toolbar.xml_ (all end with ``_toolbar.xml``)
+- Any layouts not associated with the above that should be shared across multiple layouts should instead be associated with a custom view (including a corresponding Kotlin file). This means the ``include`` directive won't be included in any layouts.
+- Since widget IDs within layout files are global scoped, they should be named based on their location, value, and widget type.
+ - The general format for this is: _
+
+
.
+
+
+
+* Click on that and Android studio will take a screenshot and open up a Screenshot Editor.
+
+
+
+* Optionally change the image:
+> * **Recapture**: Take a new screenshot.
+> * **Rotate Left**: Rotate the image 90 degrees counter-clockwise.
+> * **Rotate Right**: Rotate the image 90 degrees clockwise.
+> * **Frame Screenshot**: Choose a device to wrap your screenshot with real device artwork.
+* Click Save, specify the location and filename, and then click OK to save the screenshot.
+
+
+For more details, see the [Android documentation](https://developer.android.com/studio/debug/am-screenshot)
+
+## Using an ADB command
+If you would like to take a screenshot but cannot use Android Studio, you can instead capture a screenshot using an ADB command.
+* Run the following command: `adb shell screencap -p /sdcard/screenshot.png`
+* This creates a screenshot called screenshot.png and stores it on your Android device.
+* To pull it on to your computer, you can run `adb pull /sdcard/screenshot.png`. This will copy the image from the device to your local machine (on the path in which you ran the command).
+* You can now upload the image on to Github.
\ No newline at end of file
diff --git a/wiki/Dagger.md b/wiki/Dagger.md
new file mode 100644
index 00000000000..c92830d9366
--- /dev/null
+++ b/wiki/Dagger.md
@@ -0,0 +1,132 @@
+# What is Dagger?
+Dagger is a fully static and compile-time [dependency injection](https://github.com/oppia/oppia-android/wiki/Dependency-Injection) framework. Compile-time means that issues in the dependency graph (such as cycles or missing providers) are caught during build-time.
+
+## Components & Subcomponents
+Dagger creates the dependency graph using components and subcomponents
+- Components are top-level containers of providers that are pulled from modules that component is configured to include
+- Subcomponents are also containers, and may contain other subcomponents
+- Subcomponents automatically inherit all the dependencies from their parent components
+- Components/subcomponents can automatically collect dependencies for which they are scoped
+
+## Scopes
+Scopes are compile-time annotations associated both with a component/subcomponent and either injectable objects or providers of objects
+
+## Injectables & Providers
+Dagger supports two types of injections: field and constructors
+- All objects that are injected need to have an @Inject-declared constructor
+- Any parameters passed into an @Inject-declared constructor will be retrieved from the dependency graph
+- Fields can be marked as @Inject-able, but a separate inject() method in a component needs to be added for that class to initialize those fields, and the class must call this method
+
+Note: Classes can have their providers inferred just by being qualified and having an @Inject-able constructor--no need for a Dagger module
+
+## Modules
+Dagger modules are defined in separate classes annotated with the @Module tag
+- Modules can provide an implementation with @Provides
+- Modules can bind one type to another type using @Binds
+
+# Its Usage in Oppia Android
+ - Dagger object lifetimes need to be compatible with Android object lifecycles
+ - Prefer constructor injection over field injection to encourage encapsulation
+ - Result are activity/fragment/view presenter classes that are field-injected into their corresponding Android objects, but themselves support constructor injection
+
+
+ There's an Android-specific dependency hierarchy:
+
|
+
+ 
+ |
+
+ This file should strictly contain actual color names (irrespective of their intended use) with their hex color code declaration.
+ example:
+ > Don't + ```xml +
+ There are two versions for this file (day/night variations). The purpose of this file is to split the colors for them to be later referenced by `component_colors.xml`. The color declarations in this should have a generic name and should not contain any name tied to the intended component like toolbar, edittext, textview, etec. to be used on. Also, colors should **not** contain "feature" based name (like *add_profile_background_color*). + The declarations in this file should only reference `color_defs.xml`. + >Don't: + ```xml +
+ This file contains the highest level of color declarations. The declarations in this file should only reference `color_palette.xml`. It uses UI component specific names. Component colors should be shared very little outside of their respective views/fragments/activities. *All the layouts/views should only reference this file for colors.*
+ examples:
+ ```xml +
+ This file contains color declarations which are supposed to be in color_defs.xml but has not been renamed yet to have actual color name instead of names linked to their use and components. This is a temporary measure to make sure other 4 color files follows the convention decided for them. + This file should be deleted after all colors have been shifted to `color_defs.xml`.
+ +_Note:_ +- *All color names should strictly follow `snake_case` naming convention.*
+- *All colors in `component_colors.xml` and `color_palette.xml` should have `_color` as suffix and just the opposite for `color_defs.xml`*
+- *All color declaration must have their parent file name as prefix of their name, i.e. "`
+
+ +- Replace all the generic colors in the layout with something more specific to the component by defining it in the `component_colors.xml`, generally it should be named in the format *`component_color_
+ +Some other skins of android might force their own version of dark mode to screens not having dark mode support yet. diff --git a/wiki/DataProvider-&-LiveData.md b/wiki/DataProvider-&-LiveData.md new file mode 100644 index 00000000000..a3da67cef61 --- /dev/null +++ b/wiki/DataProvider-&-LiveData.md @@ -0,0 +1,47 @@ +### DataProviders + +[DataProvider](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/utility/src/main/java/org/oppia/android/util/data/DataProvider.kt#L10)s are gateways to safely receiving an asynchronous result from an operation. They support notifications for when the DataProvider has new data to be retrieved, force usage of suspend functions to encourage coroutine use, have utilities for simplifying their usage, and provide an easy way to pass data to the UI via LiveData. + +You should generally never need to create a new DataProvider since there are existing bridges for most asynchronous operations, but if you do make sure to follow other DataProviders for a reference to make sure you're implementing it correctly. + + +### Transferring data to UI via LiveData + +[``LiveData``](https://developer.android.com/topic/libraries/architecture/livedata) is a lifecycle-aware stateful concurrency primitive that was added to Android Jetpack. The team prefers using ``LiveData`` for a few reasons: +1. It supports receiving data from a background thread via an Android ``Handler`` post +2. It's lifecycle-aware (e.g. it ensures that the background data passed from (1) does not trigger logic for an activity that's being torn down due to the user exiting it or a configuration change) +3. It integrates trivially with Android [databinding](https://developer.android.com/topic/libraries/data-binding) which the team uses to simplify UI development + +All ``DataProvider``s are convertible to ``LiveData`` using an extension function: [``toLiveData()``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/utility/src/main/java/org/oppia/android/util/data/DataProviders.kt#L158). + +### Best practices/antipractices + +- Prefer to start with a ``DataProvider`` (e.g. in-memory, file-provided, or network-provided) and then transform/combine it as needed rather than creating new dispatchers +- Never use coroutines outside of the domain layer +- Never perform any multi-threading operations outside of coroutines (except when unavoidable--see the 'other cases for background processing' section) +- Never use locks within coroutines +- Prefer using concurrent data structures over atomics +- Never send data to the UI without using a ``DataProvider`` + ``LiveData`` +- **Do** make use of ``TestCoroutineDispatchers`` when writing tests to ensure proper synchronization +- When integrating a new library that has asynchronous support, make sure it's configurable and that its executors/dispatchers are set up to use the common dispatchers +- Prefer using existing ``DataProvider``s rather than creating new ones +- Never use ``observeForever`` on a ``LiveData`` in the UI, and in cases when it's used elsewhere make sure the observer is removed +- Prefer conducting transformations in ``DataProvider``s rather than ``LiveData``, except when impossible (e.g. extracting values from the final ``AsyncResult`` passed from the data provider) +- Never combine data through ``LiveData`` (e.g. using ``MediatorLiveData``); prefer combining data through ``DataProvider``s instead and convert to ``LiveData`` at the end +- Never use ``SharedPreferences``--use ``PersistentCacheStore`` instead since it never blocks the main thread + +## DataProvider simplifications + +There are a number of preexisting ``DataProvider``s & utilities to simplify development. + +### DataProviders utility + +[``DataProviders``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/utility/src/main/java/org/oppia/android/util/data/DataProviders.kt#L24) is an injectable class that provides a number of helpful functions: +- Transforming data providers (e.g. converting their type into a new type, or performing some operation once data is available) +- Combining two or more data providers together (which will block on all data providers being ready) +- Converting data providers to ``LiveData`` +- Creating an in-memory data provider (to, for example, start a data provider chain) + +### LiveData transformations + +``LiveData`` supports [``Transformations``](https://developer.android.com/reference/androidx/lifecycle/Transformations) & other utilities (like ``MediatorLiveData``) which can be used to transform and/or combine ``LiveData`` objects similarly to ``DataProvider``s. The team generally makes use of transformations to perform boundary error checking/value retrieval from ``AsyncResult``, but otherwise prefers to leverage ``DataProvider``s for more complex combines/transformations. ``LiveData``'s utilities have some shortcomings and are fairly easy to get wrong, so prefer to use ``DataProvider``s when possible. diff --git a/wiki/Dependency-Injection.md b/wiki/Dependency-Injection.md new file mode 100644 index 00000000000..313d7a885f6 --- /dev/null +++ b/wiki/Dependency-Injection.md @@ -0,0 +1,52 @@ +# What is Dependency Injection? +- It's a mechanism to automatically provide dependencies that an object depends on +- It requires the object receiving dependencies to also be injectable for other dependencies +- The dependency injection (DI) framework is responsible for object lifetimes +- Modules are classes responsible for providing providers +- Providers act like factories that create new instances of a dependency +- The result is a graph of dependencies and providers +- This graph must be acyclic, otherwise it cannot be formed (e.g. dependency A cannot inject B if B depends on C and C depends on A) + +# Why do we need it? +Consider this scenario for typical dependency situation + +- In this example, creating a UserAppHistoryController requires creating a PersistentCacheStore factory +- Creating the factory requires a context object +- Why should users of the controller care about factories and contexts? +- This situation is simpler than real situations typically are +- Wouldn't it be nice if those dependencies could just magically show up? + +``` +class UserAppHistoryController(cacheStoreFactory: PersistentCacheStore.Factory) { + // Use cacheStoreFactory... +} + +class PersistentCacheStore private constructor() { + class Factory(private val context: Context) { + // Use context... + } +} +``` + +Now if we would have introduced dependency injection + +- We just need to inject UserAppHistoryController wherever we want it, and not care about dependencies +- However, using one injected dependency requires using another object that's injected, and so on +- With a DI framework, essentially the entire app needs to have injected dependencies + +``` +@Singleton +class UserAppHistoryController @Inject constructor( + cacheStoreFactory: PersistentCacheStore.Factory +) { + // Use cacheStoreFactory... +} + +class PersistentCacheStore private constructor() { + class Factory @Inject constructor (private val context: Context) { + // Use context... + } +} +``` + +Hence this calls for a framework that can help us with Dependency Injection in Android and Dagger seems the most favourable choice. [ReadMore](https://github.com/oppia/oppia-android/wiki/Dagger) \ No newline at end of file diff --git a/wiki/Developing-skills.md b/wiki/Developing-skills.md new file mode 100644 index 00000000000..562b07e321e --- /dev/null +++ b/wiki/Developing-skills.md @@ -0,0 +1,20 @@ +In general, it's easier to contribute to the Oppia codebase if you have some knowledge of git, as well as at least one of Kotlin or Android. You don't need to know all of this before you start, though! Many of our contributors have picked these skills up concurrently while tackling their first issues. + +That said, we strongly recommend that you be open to learning new things. If you need to brush up on some of the technologies used in Oppia, here are some resources that may help: + + - Git and Github are used to make changes to the repository, so it's good to know how to use them to do basic stuff like branching, merging, pulling, pushing, and committing. + - For beginners: + - [Learning Branching Git](https://learngitbranching.js.org/) helps explain how git works. Try the levels below: + - Levels 1, 2, and 3 from the Introduction sequence. + - Levels 1, 2, 3, 4, 5, and 6 from Push and Pull Git Remotes. + - [Introduction to GitHub](https://lab.github.com/githubtraining/introduction-to-github) covers how to use GitHub. + - More advanced: + - The other levels from [Learn Branching Git](https://learngitbranching.js.org/) cover git in more depth. + - You may find this [git visualizer](https://git-school.github.io/visualizing-git/) helpful for understanding more advanced git operations. It can be helpful for simple ones too! + - GitHub's [managing merge conflicts page](https://lab.github.com/githubtraining/managing-merge-conflicts) explains how to address merge conflicts. + - Kotlin is used for Android in oppia. You can learn the basics of kotlin from Udacity -- [Kotlin bootcamp for programmers](https://www.udacity.com/course/kotlin-bootcamp-for-programmers--ud9011) by Google. + - Learn the basics of android to understand the project structure and the libraries that are used in most common apps from the Udacity -- [Developing Android Apps with Kotlin](https://www.udacity.com/course/developing-android-apps-with-kotlin--ud9012) course. + - To learn the advanced topics like Dependency Injection and Testing in Android check out Udacity -- [Advanced Android with Kotlin](https://www.udacity.com/course/advanced-android-with-kotlin--ud940) course. + + +All the learning resources mentioned are free. If you find a useful learning resource that isn't listed here, please add it to help other new contributors! diff --git a/wiki/End-to-End-Testing-Guide.md b/wiki/End-to-End-Testing-Guide.md new file mode 100644 index 00000000000..63e86fcf831 --- /dev/null +++ b/wiki/End-to-End-Testing-Guide.md @@ -0,0 +1,111 @@ +## Overview + +End-to-End tests test the app from an end user’s experience by simulating the real user scenario and validating the system under test and its components for integration and data integrity. + +These tests play a major role in publishing the app. They run on a real or emulated device to make sure that our code interacts with the Android environment as expected, providing confidence in the final application or a feature when it's finished. + +End-to-End tests in Oppia-android are written using [UiAutomator](https://developer.android.com/training/testing/ui-automator). +These tests are written under the instrumentation module and don’t have Gradle support. + +``` +instrumentation/ -- android test binaries for each test suite. +`-- src + |-- java + | `-- org + | `-- oppia + | `-- android + | `-- instrumentation + | `-- application -- Test application and modules + `-- javatests + `-- org + `-- oppia + `-- android + `-- instrumentation -- Test suites for each part of the app + +``` + +These tests are run using [Bazel](https://bazel.build/) and [ADB](https://developer.android.com/studio/command-line/adb). +Each test suite tests a particular part of the app, each test suite has its own [kt_android_library](https://bazelbuild.github.io/rules_kotlin/kotlin#kt_android_library), [android_binary](https://docs.bazel.build/versions/main/be/android.html#android_binary) and [android_instrumentation_test](https://docs.bazel.build/versions/main/be/android.html#android_instrumentation_test). + +Note: android_instrumentation_test target is not supported yet ([#3617](https://github.com/oppia/oppia-android/issues/3617) for details). + +### How it works. +The android_binary of a test suite generates a test apk with the same name as the class of the test suite. This test apk is installed along with the original apk in the emulator. We use the adb [am instrument](https://developer.android.com/studio/test/command-line#AMSyntax) command to run the test on the target device or emulator. + +### How to run an End-to-End test + +#### Prerequisites: +1. [Set up Bazel for Oppia](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions#installation) +2. Add adb to the environment (platform-tools) i.e, add the following line to the .bashrc or the file path (note that this is platform dependent): + ``` + export PATH=/home/
+
+### Crashlytics
+* Scroll down the left nav bar and select Crashlytics. You will see the following dashboard :
+> 
+* A --> Filter Option : You can filter out crashes and non-fatal exceptions through it.
+* B --> Crash-free stats : Give you an insight to the amount of users which are experiencing crash free experience.
+* C --> Event trends : Give you the information regarding the reported exceptions and the users affected by them.
+* D --> Issues : Similar reported exceptions are clubbed together to form issues which can be marked as solved once fixed. Once we click on any one of these issues, it leads us to the following :
+> 
+* A --> Events by version : This segment tells the user about the day-wise number of event occurrences in form of a graph. This graph may have multiple lines based on the number of versions of the application.
+* B --> Device Info : It tells us about the devices in which that exception has occurred. Multiple devices are differentiated on the basis of the number of event occurrences. Other info like the OS and the device states are also available.
+* C --> Session Summary : This segment contains the crash reports of each occurrence of the event. Things like stack traces and device data are present which tell us a lot about the crashes. Keys and Logs are only available if we log them through APIs.
+
+### Analytics
+* Scroll down the nav bar a bit more and select Dashboard under the Analytics Section. You will see :
+> 
+* The dashboard consists of the following segments :
+1. Daily active users
+1. Users in last 30 mins
+1. Daily user engagement
+1. Key events
+1. Stability statistics
+1. Audience statistics
+1. User retention stats
+* We can filter out the results that is displayed on the dashboard by using the filter option on the top left. We can filter the values using user properties like device model, OS, app-version, etc.
+* We can also view these things under their own specific dashboards. For example the event dashboard looks like:
+> 
+* This dashboard consists of all the predefined events along with the custom logged events as you can see in the image above. We can see detailed stats related to an event by clicking on its event name.
+
+### DebugView
+* DebugView enables you to see the raw event data logged by your app on development devices in near real-time.
+> 
+* _To run this, you must have ADB set up in your system._
+* To enable DebugView, write `adb shell setprop debug.firebase.analytics.app org.oppia.android` in your command line while the app runs on your emulator/device.
+* Now as you play around with the app you'll see various events being logged to the console. To get more details about an event, just click on it and you'll see something like this :
+> 
+* In the above case, we can see that the logged event : `OPEN_LESSONS_TAB` has custom parameters like `priority`, `timestamp` and `topicId` along with predefined Firebase event parameters.
+* To get more specific details about the logged event, you can click on its parameters and see their values as well.
+* To disable DebugView, write `adb shell setprop debug.firebase.analytics.app .none.` in your command line.
+
+### Funnels
+* They are used to visualize and optimize the completion rate of a series of steps (events) in the app.
+> 
+* You can filter out the results (from the top) on the basis of user properties like app-version, device model, OS-version, etc.
+* To set up funnels, follow these steps :
+1. In Analytics, navigate to your app.
+1. Click Funnels.
+1. Click NEW FUNNEL.
+1. Enter a name and description for the funnel.
+1. Select the first two events you want to use as steps in the funnel.
+1. Click ADD ANOTHER EVENT for each additional step, and select an event.
+1. Click CREATE.
+> 
+
+### Adding Custom Parameters
+* Go to the Events section of Analytics and pick an event you want to add custom parameters for.
+* Move the cursor to the right hand side of that event and click on the three dots and then select 'Edit Parameter Reporting'.
+* You will be shown a dialog box like this :
+> 
+* Click ADD on any of the parameters that you want to add --> select if you want it to be a text based or a number based parameter and click SAVE. Voila! You just added a custom parameter.
+* It may be noted that for custom events, we can provide custom parameters via code and then integrate them here.
+
+### Conversions
+* In Analytics, the most important events are known as Conversions.
+* We can mark any of the event as a conversion event just by going to the Events -> toggling on the conversion button on the right side of the event that you want to mark as conversion.
+* A summary of conversion events are shown on the main Analytics Dashboard, while other details are available in the Conversions sub-section.
+
+## Your own Firebase Project
+
+### Setting it up
+* Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account -> Click on "Add Project"
+* Enter your project name -> Enable/Disabe Google Analytics and move forward.
+* If you enabled Google Analytics then accept the terms and select a project location and click create project.
+* If you disabled Google Analytics then simply click on create project.
+* Click continue on completion of the progress bar and the Project Console (like the one shown above) will open.
+
+### App Registration
+* Once your Project Console opens up, click on 'Add an App' from the centre. This will open up :
+> 
+* Add the required info and click on Register App.
+* Then in the next step you would be required to add a config file to your repo. In our case we have to add it under our app module.
+* Then click next, add the said plugins (if not already added).
+* In the next step build & run the app so that the Firebase servers sync to it and click on Go to Console.
+* You can check the details of your project and the apps registered to it by clicking on the settings button (present on the top of the nav bar) and then selecting 'Project settings' from it. A new page will open up with all the necessary details.
+
+## View events in the Android Studio debug log
+
+You can enable verbose logging to monitor logging of events by the SDK to help verify that events are being logged properly. This includes both automatically and manually logged events.
+
+You can enable verbose logging with a series of adb commands:
+* `adb shell setprop log.tag.FA VERBOSE`
+* `adb shell setprop log.tag.FA-SVC VERBOSE`
+* `adb logcat -v time -s FA FA-SVC`
+
+This command displays your events in the Android Studio logcat, helping you immediately verify that events are being sent.
\ No newline at end of file
diff --git a/wiki/Fork-and-Clone-Oppia-Android.md b/wiki/Fork-and-Clone-Oppia-Android.md
new file mode 100644
index 00000000000..dc0d9237e35
--- /dev/null
+++ b/wiki/Fork-and-Clone-Oppia-Android.md
@@ -0,0 +1,41 @@
+
+_For a detailed explanation of the fork-and-clone process, please see this [GitHub help page](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#platform-linux)._
+
+## Fork and clone the Oppia Android repository
+
+To make code changes, please follow the following instructions
+- [Using the terminal](https://gist.github.com/MaskedCarrot/ea0933311b95a108f99e3c6c106ea101#using-the-terminal)
+- [Using android studio's UI based github workflow](https://gist.github.com/MaskedCarrot/ea0933311b95a108f99e3c6c106ea101#using-android-studios-ui-based-github-workflow)
+
+### Using the terminal
+
+1. Make sure that you are in the `opensource/` folder on your local machine.
+
+2. Click on the "Fork" button on the top-right corner (at the same level as the oppia/oppia-android repository name):
+
+
+3. You can now see Oppia-Android under [your repositories](https://github.com/). It will be marked as forked from `oppia/oppia-android`
+
+
+4. Clone this repository to your local computer by running `git clone https://github.com/USERNAME/oppia-android.git` in a terminal.
+
+5. To keep your local repository, forked repository and main oppia-android repository in sync, configure your remote repositories by running the following two commands in a terminal:
+ - `git remote -v` (this lists your current remote repositories)
+ - `git remote add upstream https://github.com/oppia/oppia-android` (this adds oppia/oppia-android as an upstream repo)
+
+### Using android studio's UI based GitHub workflow
+1. Navigate to your fork, e.g. ``https://github.com/
+
+2. Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git**
+
+
+
+3. Log in GitHub with your credentials.
+
+4. Paste the **URL** and click on **Clone** button.
+Wait for a few minutes until Gradle build completes.
+
+
\ No newline at end of file
diff --git a/wiki/Frequent-Errors-and-Solutions.md b/wiki/Frequent-Errors-and-Solutions.md
new file mode 100644
index 00000000000..dac1bd3240c
--- /dev/null
+++ b/wiki/Frequent-Errors-and-Solutions.md
@@ -0,0 +1,49 @@
+## Dagger Unresolved reference
+**Error**: Unresolved reference `DaggerXXTest_TestApplicationComponent`
+
+**Solution**: Don't worry this is not an error. Just run the test file and it will solve the error. For running tests, you can see [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) document.
+
+## Crashing layout tags in tablet
+**Error**: java.lang.IllegalArgumentException: The tag for topic_lessons_title is invalid. Received: layout-sw600dp-port/topic_lessons_title_0
+**Solutions**: This error occurs when we remove any xml file which is related to tablet devices
+To solve this
+1. Uninstall the app from tablet
+2. Rebuild the app.
+3. Run the app again.
+
+## Push failed
+**Error**: Failed to push some refs to `git@github.com:
+
+If there is an error with any of the lint failures it will be detailed in the command line itself.
+
+## Facing error while debugging code
+Whenever you are debugging a problem, you may find it useful to keep a record of your debugging process. We often do this already in issues. Issues usually begin with a detailed description of the problem, which is followed by discussion, reports of attempted debugging steps, and what root cause was identified. However, issues' linear comment structure makes them more amenable to communication among team members than organizing your thoughts. Debugging docs, on the other hand, serve primarily to organize your thoughts.
+
+### Benefits
+Primarily, debugging docs help keep your thoughts organized. When you have written down the steps you've already tried and the results of your investigations, you don't have to worry about forgetting your earlier work. Further, when you document your work, you force yourself to reflect on what you've already tried. Debugging docs also make it easy for you to bring someone else up to speed on your bug.
+
+### How to Write a Debugging Doc
+
+#### 1. Begin with Describing What Goes Wrong
+Your description should include:
+ - Context: What branch or PR is the bug happening on? If this is happening locally, what system are you running, and what code changes have you made?
+ - How the Bug Manifests: This might include error logs that you pasted into the document, screenshots, or links to a test run on a PR. If you provide a link, copy the relevant part of the page you are linking to. This keeps the document self-contained so we can search them. It also makes the doc easier for people to read.
+
+#### 2. Describe Your Investigations
+What did you try, and what happened when you tried it? You want to include enough detail so that someone could reproduce your investigation to see if they get the same results.
+
+#### 3. Document Your Guesses and Testing
+After some investigation, you might have some ideas for what might be going wrong. Document your guesses and describe how you go about testing them. Report the results of that testing and describe whether you think your guess was right. What's your reasoning?
+
+#### 4. Continue/Review from Mentor
+Keep going! Continue documenting your investigations, guesses, and tests of those guesses. You can share your debugging doc with your assigned onboarding mentor to review and help you in finding the root cause of the issue or the solution.
+
+#### 5. Document Your Solution
+Once you figure out what the problem was, write that down too! Include an analysis of how the root cause you identify caused the errors you described at the top. Often, this will take the form of one of your suspected solutions.
+
+#### Get Started
+Ready to get started with your own debugging doc? You can make a copy of [this template](https://docs.google.com/document/d/1OBAio60bchrNCpIrPBY2ResjeR11ekcN0w5kNJ0DHw8/edit?usp=sharing) to get started.
\ No newline at end of file
diff --git a/wiki/Get-Help.md b/wiki/Get-Help.md
new file mode 100644
index 00000000000..a40f9c589bb
--- /dev/null
+++ b/wiki/Get-Help.md
@@ -0,0 +1,158 @@
+## Table of Contents
+
+* [Communication channels](#communication-channels)
+ * [Email](#email)
+ * [GitHub Discussions](#github-discussions)
+ * [Google Chat or Hangouts](#google-chat-or-hangouts)
+ * [GitHub](#github)
+* [How to Ask Good Questions](#how-to-ask-good-questions)
+ * [Setup-related questions](#setup-related-questions)
+ * [Before you ask a setup question](#before-you-ask-a-setup-question)
+ * [How to ask a setup question](#how-to-ask-a-setup-question)
+* [General questions](#general-questions)
+ * [Before you ask a general question](#before-you-ask-a-general-question)
+ * [How to ask a general question](#how-to-ask-a-general-question)
+ * [Important points](#important-points)
+
+Here we document Oppia's main communication channels and how to ask good questions.
+
+## Communication channels
+
+If you need help, there are a few communication channels you can use. Developers usually respond within 24 hours so long as you use a channel they actually check.
+
+### Email
+
+We have several mailing lists in the form of Google Groups that you can join:
+
+* [oppia-announce](https://groups.google.com/forum/#!forum/oppia-announce) is for announcements of new releases or blog posts. It's not for asking questions though.
+* [oppia-android-dev](https://groups.google.com/g/oppia-android-dev) is the main mailing list for communication between developers and for technical questions. You can post to it even if you're not a member of the group. This is where you can ask questions, solicit feedback, or make developer-specific announcements (e.g. a temporary GitHub outage).
+
+You can also email your mentor with any questions. If you don't have a mentor, complete the steps on the [wiki page for contributing code to Oppia](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android) and you'll be assigned one.
+
+### GitHub Discussions
+
+If you have questions regarding Oppia Android, you can create a discussion on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/) where other developers will assist you in resolving the issue. Oppia's Welfare team monitors this chat to help out new contributors, so it's the best place to ask questions about Oppia or getting started. You can create a discussion in any of the following categories based on the question:
+
+* Developer announcements: All announcements that affect developers for the Oppia repository will be announced here.
+* Q&A: Any questions that developers have (related to setup, navigating the codebase, or anything else).
+* General Discussion: General forum for any topics that aren't Q&A.
+
+Feel free to drop in and [say hi](https://github.com/oppia/oppia-android/discussions/4788)! You can also refer to [this guide](https://docs.github.com/en/discussions/quickstart#creating-a-new-discussion) on how to create a new discussion.
+
+### Google Chat or Hangouts
+
+Most Oppia developers and teams use Google Chat as their primary means of communication, and they usually respond quickly. However, invites often get lost in spam folders, and some developers use a non-public email address for Google Chat. You can ask your mentor to put you in touch with a developer if you don't know their address or if they haven't acted on your invite.
+
+### GitHub
+
+If you have a question about a pull request or issue, you can also reach out to developers by at-mentioning them (e.g. `@developer-username`) in a comment and assigning them to the issue. Be sure you both at-mention and assign them! Some developers only look at their GitHub notifications (which at-mentions trigger), while others only look at what they're assigned to.
+
+You can even mention whole teams of people! For example, if you find an issue that is destabilizing the project, you could notify all the core maintainers by including `@oppia/core-maintainers` in your issue. The teams are all listed [here](https://github.com/orgs/oppia/teams).
+
+## How to Ask Good Questions
+
+At Oppia we don’t care how silly your question is! Just ensure your question is clear, and provide us with enough information to help us resolve it faster. We've divided the questions into 2 categories - Setup-related and General questions. You can start following the sections below to understand how you can ask each of them.
+
+### Setup-related questions
+
+#### Before you ask a setup question
+
+1. You can setup/install oppia-android by visiting [this page](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android). Make sure you follow **all** the mentioned instructions from the beginning in a step-by-step manner.
+
+2. Make sure each step succeeds (verify it with the expected behavior if mentioned in the wiki).
+
+3. In case of any unexpected behavior/errors at any step, make sure you check out our wiki on [troubleshoot installation](https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation).
+
+If you are still not able to fix your error, start following the section below to raise your question on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/categories/setup-issues).
+
+#### How to ask a setup question
+
+**Note**: If you are stuck at Step X, we will assume all previous steps through X-1 were successful for you. In case there were any previously failed steps, kindly mention those too with their error logs.
+
+Please follow the template given below (mark x inside checkboxes to tick them) for creating a GitHub Discussions.
+
+```md
+**Checklist**
+- [ ] I have followed the [Before you ask a setup question](https://github.com/oppia/oppia-android/wiki/Get-help#before-you-ask-a-setup-question) section of the wiki.
+
+**System Information**
+- OS: (Be specific Ex: Ubuntu 20.04 or Ubuntu 20.04 VM on MacOS 11.2.1)
+
+**Steps followed**
+
+// If you encountered this error while following a wiki page, provide a link to the page and specify which step failed. Otherwise, list what steps caused the error. These should be detailed enough for someone else to follow them.
+
+**Error log**
+
+//paste error log here
+
+or
+
+paste a screenshot
+
+**Approaches already used to resolve the issue**
+
+(eg: Link to a Stack Overflow answer or any solution that you have tried)
+- enter any additional description
+```
+
+## General questions
+
+### Before you ask a general question
+
+* We expect that you have already **set up Oppia on your machine**, and it is successfully running. (If not, kindly do that first!)
+* Prepare a debugging doc following [this template](https://docs.google.com/document/d/1OBAio60bchrNCpIrPBY2ResjeR11ekcN0w5kNJ0DHw8). For more information on how to use debugging docs, see [this link](https://github.com/oppia/oppia/wiki/Debugging-Docs).
+* If there are **checks** on your PR, and you haven’t done any changes in that direction, kindly understand that sometimes they just fail due to flakiness. You should request for a re-run of those only when it’s preventing your PR from getting merged.
+
+### How to ask a general question
+
+Follow the template below for asking questions (fill in the values inside {{}} brackets and mark x inside checkboxes to tick them) to leave a comment on a pull request. Adapt the template as needed if you are using another channel.
+
+```md
+@{{PR reviewer or Mentor username}} PTAL!
+
+**Checklist**
+- [ ] I have filled the [CLA](https://goo.gl/forms/AttNH80OV0) and the [Oppia Contributor Survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3)
+- [ ] I have followed to install oppia-android mentioned [here](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android)
+- [ ] I have worked through the [Before you ask a setup question](https://github.com/oppia/oppia/wiki/Get-help#before-you-ask-a-setup-question) section of the wiki.
+
+**System Information**
+- OS: (Be specific Ex: Ubuntu 20.04)
+- [ ] Virtual machine
+
+**About the issue**
+- {{Describe the problem}} (eg. Failing robolectric tests: "The test has been
+ failing repeatedly since {{x}} previous runs, and I haven’t done any
+ changes related to it. Requesting a re-run.")
+
+**Approaches already used to resolve the issue**
+
+(eg: Link to a Stack Overflow answer or any solution that you have tried)
+- #{{Link to the debugging doc}}
+- enter any additional description
+```
+
+### Important points
+
+* If you are unable to push changes due to some reason, you can create a [patch file](https://docs.gitlab.com/omnibus/development/creating-patches.html) and share it with the person you're asking for help.
+
+* If you are facing issues in completing the assigned task, you can create a PR on your fork of the oppia-android repository, troubleshoot your problem on that pull request with help from your mentor, and then create a new PR on the original oppia-android repository.
+
+* If you have not made a PR yet, because you are not sure:
+
+ * what the issue is about, or
+ * which files have to be modified, or
+ * if your approach towards the solution is correct
+
+ Then ask for help by commenting with your doubt/suggested approach on the issue page itself. If you don’t get any response within **24 hours**, please leave a note on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/categories/q-a-contacting-folks) so that the developer workflow team is aware and can help you.
+
+* If you want to have a discussion on your approach, but aren’t ready to make a PR yet, you can create a [public gist](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists) and include the link to it in your question. It’s always better to see the code you are talking about!
+
+* **Avoid asking for help from people via emails or direct messaging.** We encourage everyone to ask for help on a common channel so that whoever sees your query first can help you or guide you how to take your query forward. Note that directing questions to your mentor is fine.
+
+ * Comment on the issue page or the PR if your question is very specific.
+
+ * Use [GitHub Discussions](https://github.com/oppia/oppia-android/discussions) if your question is not issue-specific.
+
+### Welfare Team
+If you still feel blocked even after following the above steps or are unsure who to contact, you can reach out to the welfare team. You can also ping the welfare team by at-mentioning the welfare team: @oppia/android-welfare-team
diff --git a/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md b/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md
new file mode 100644
index 00000000000..98ff63f4278
--- /dev/null
+++ b/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md
@@ -0,0 +1,61 @@
+The following document explains best practices & provides support for the Gradle to Bazel migration. For more information on setting up Bazel, read [Oppia Bazel Setup Instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions).
+
+This is a living document that will grow as more questions get asked and answered.
+
+## What are we doing?
+
+Currently, the libraries in a module's BUILD.bazel file contain most of their dependencies as files in srcs dependencies. We are going to break out smaller pieces of these source files into their own libraries. Eventually, the module libraries will depend on a smaller set of these libraries as its direct dependencies.
+
+In the following example, we have a set of dependencies that are specific to a KotlinFile.kt file. We have an ExampleLibrary that has both the Kotlin file as srcs dependency and the underlying deps dependencies as its own direct deps dependencies.
+
+
+
+When we create a new library, we can move this set of dependencies to the new library.
+
+
+
+This is not always possible, since there might be other files relying on the same dependencies so in our transition phase we can end up with something like this:
+
+
+
+## General tips
+
+- Build early and build often. This will help you catch issues and Bazel can also suggest dependencies to add to your library in some cases.
+- Look at other BUILD.bazel files in the codebase for an idea on how to lay out packages.
+- Migrating files will always involve introducing new libraries, and then hooking those up to the top-level module libraries. There are ways of making this a bit easier:
+ - While performing the migration, focus on making sure the new library builds first, e.g.: ``bazel build //
+
+2. **Create a new branch with a descriptive name.** On the bottom right side of your Android Studio screen, you will find your branch name. Click on **branch_name** > **develop** > **New Branch from Selected** > _Enter your new branch name_ > **OK**.
+
+ Then, create a new branch. In this example the branch is named `github`. The branch name should be lowercase and hyphen-separated, e.g. `fuzzy-rules`. Make sure that your branch name doesn’t start with `develop`, `release` or `test.`
+
+ 
+
+ If you want to go back to "develop" or any other branch/"check-out any branch" you may right-click and find options for that:
+
+ 
+
+3. **Make commits locally to your feature branch.** Now, when you create a new activity, it will be unversioned and therefore displayed with a reddish-brown colour file name. To add the files to Git/version Select files and click the "Add" button.
+
+ 
+
+ New/modified files will be displayed in green /blue colour respectively in the project window. (select file/folder/directory Ctrl+Alt|+A to manually version an unversioned file/files)
+
+ 
+
+ Click on the green tick symbol to commit your files.
+
+ 
+
+ Now click on commit(This will save the reference of your changes for pushing to Git). If there are errors or warnings, review the code change and fix them before committing.
+
+ 
+
+4. **Push changes to your GitHub fork.** We need to push the code changes to local branch (origin) and upstream (remote). Right click **app > Git > Repository > Push**:
+
+ 
+
+ Your new branch needs to be added to both origin and upstream remote. Once you push a branch to Git, you won't be able to rename it, so be sure about the naming before pushing:
+
+ 
+
+
+## Step 2: Create a PR on GitHub
+
+Once your feature is ready, you can open a pull request (PR)! Here is how to do so:
+
+- Go to your fork on GitHub, select your branch from the dropdown menu, and click "pull request". Ensure that the base repository is oppia/oppia-android and that the base branch is develop. The head repository should be your fork, and the head branch should be your branch. If you don't see the repository, click the link to compare across forks.
+- On this page, you can also see your commits and your changes. Read these changes carefully to make sure that the changes are correct. This is a good way to catch obvious errors that would otherwise lead to delays in the review process.
+- Click "Create pull request".
+
+You have successfully created a pull request! Now, wait for your code to get reviewed! While you're waiting, it's totally fine to start work on a new PR if you like. Just follow these instructions again from the beginning.
+
+**Note:** After a while, check your pull request to see whether the CI checks have passed. If not, follow our [instructions](https://github.com/oppia/oppia-android/wiki/Interpreting-CI-Results) to diagnose PR failures.
+
+### Important Points to Keep in Mind
+
+1. **UI related issue/bug fix**: If your PR introduces changes to the UI/UX part of the app, do the following:
+ - Include "before" and "after" screenshots (and possibly a video if needed).
+ - Test the UI/UX with [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en). _(Tip: All your dimensions should be in multiples of 4dp.)_
+2. **Bug fixes**: While fixing an issue labelled **Bug**, make sure to write test cases which actually catch that bug.
+3. **Self Review**: Always self-review your PR first before assigning it to anyone else, so that you can fix nit changes at very early stage. This makes the review process faster.
+4. **Undo unnecessary changes**: Sometimes, Android Studio automatically makes changes to files based on your local studio configuration. Mostly these changes are from `.idea` folder. You can revert these unnecessary changes by following these steps:
+ - Once your PR is created, go to the `Files changed` section available on top of your pull request. For example:
+ 
+ - Then, check all the files in this section and if you see any change which was not done by you, revert it locally and commit again to the pull request. The `Files changed` section should contain only those changes which were done by you.
+
+
+### 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:
+ - 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.
+
+
+
+## Step 3: Address review comments until all reviewers give LGTM
+
+When your reviewer has reviewed the code, you'll get an email. You'll need to respond both to the comments and within the code:
+
+1. Make a new commit addressing the comments you agree with, and push it to the same branch. (Continue to use descriptive commit messages. If your commit addresses lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".)
+
+ - **Always make commits locally, and then push to GitHub.** Don't make changes using the online GitHub editor -- this bypasses lint/presubmit checks, and will cause the code on GitHub to diverge from the code on your machine.
+
+ - **Never force-push changes to GitHub, especially after reviews have started.** This is disallowed and may result in your PR being closed, because it overwrites history on GitHub and makes the incremental changes harder to review.
+
+ - If you encounter merge conflicts, make sure to resolve them using [the terminal](#Resolving-merge-conflicts-using-the-terminal) or [Android Studio](#Resolving-merge-conflicts-using-Android-Studio). (Click the links for more details on how to do this.)
+
+2. **Reply to each comment** via the Files Changed tab, choosing the “Start a review” option for the first comment. Each reply should be either “Done” or a response explaining why the corresponding suggestion wasn’t implemented.
+
+3. When you’ve responded to all comments, submit the review to add all your messages to the main thread. **All comments must be responded to** and fully addressed before LGTM can be given. You can use the green button in the top right of the "Files Changed" tab to submit any pending comments.
+
+ - If you would like the reviewer to take another look, (a) write a top-level comment** explicitly asking the reviewer to take another look (e.g. "@XXX PTAL"), and (b) set them as the assignee for the PR.
+
+At the end, the reviewer will merge the pull request. Note however PRs will only be merged if there are no more requested changes, and all conversation threads have been brought to a conclusion.
+
+### Tips for getting your PR submitted
+1. Keep track of the **Assignees** section, and make sure it's always up to date -- it should always reflect the "next person(s)" who have actionable items left on the PR. If you're ever the assignee, do whatever is currently needed on your end so that you can take yourself off the list (usually, this means addressing open review comments).
+2. Make sure to **address all comments** before sending a PR back to a reviewer. Each comment thread should have a reply from you before you send the PR back. This can be either "Done", a follow-up clarifying question, or an explanation for why you don't think a suggestion should be implemented. Don't forget to actually submit your replies (using the green button at the top right of the "Files Changed" tab), otherwise reviewers won't be able to see them!
+3. Do not "resolve" a thread conversation if you didn't open it. Just re-assign the PR to the reviewer once you address all of the comments. This helps with keeping track of which comments are still "in play".
+4. Once the PR is ready to merge, add a top-level comment confirming the merge decision, and merge the PR. If any issues need to be filed subsequently, file them and refer to them in the PR via a comment.
+
+
+### Appendix: Resolving merge conflicts using the terminal
+
+To resolve conflicts between ‘new-branch-name’ (in your fork) and ‘develop’ (in the oppia repository), run:
+
+```
+git checkout new-branch-name
+git fetch upstream
+git merge upstream/develop
+git commit -a
+git push origin new-branch-name
+ ```
+
+### Appendix: Resolving merge conflicts using Android Studio
+
+Usually Git is able to automatically merge files when pulling changes from another branch. But sometimes a conflict arises when two separate branches have made edits to the same line in a file, or when a file has been deleted in one branch but edited in the other.
+
+You can use Android Studio to resolve merge conflicts through its UI-based Git features. Here's how to do it:
+
+- Go to VCS > Git > Pull (set the remote to be upstream and branch to be develop). Or, use VCS > Git > Resolve Conflicts if you have already pulled the changes but haven’t resolved the conflicts.
+
+ 
+
+- Usually, this will automatically merge the files. However, in the case of conflicts, it will prompt you to tell it what to do with those files.
+
+ 
+
+- You can either directly accept the changes from develop (discarding your local changes) or keep your own changes (discarding the changes from develop) based on the situation but it is suggested to go through each file line by line using the merge button in the prompt.
+
+ 
+
+ The file on the left shows changes from your local working branch and the file on the right shows the changes from the develop branch while the centre file being the final state of it. You can decide accordingly which change (or both) you want to keep for each conflict one by one using the arrows and cross sign on those highlighted lines. Once the conflicts are successfully resolved you can then commit and push your changes to your working branch.
+
+
+## Step 4: Tidy up and celebrate! :confetti_ball:
+After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository. Congratulations, you have contributed to the Oppia Android project!
+
+If you have already completed 2 pull requests and been added as a collaborator to the project, you should also add a changelog label. If you are a new contributor, you don't have permission to do this. Don't worry! Oppiabot will automatically ask someone to do it for you.
+
diff --git a/wiki/Home.md b/wiki/Home.md
new file mode 100644
index 00000000000..3b915b6cc45
--- /dev/null
+++ b/wiki/Home.md
@@ -0,0 +1,13 @@
+Thanks for your interest in contributing to the Oppia project and making it easier for students to learn online effectively and enjoyably!
+
+There are many ways to help out and become an Oppia contributor, from joining our team of lesson creators to fixing a bug in the [codebase](https://github.com/oppia/oppia-android/). Don't worry if you're new to "open source" or still a student -- many of our contributors are too, and we'd be happy to provide mentorship and support if this is your first time contributing to an open-source project. The main thing is that you care deeply about helping people worldwide learn something better and that you're responsible and reliable.
+
+To make it easier to get started, we've catalogued some different ways to help out. Please feel free to take a look through them and see if any interest you:
+
+ * [Coders](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android)
+
+If you are interested in working on Oppia's web repository, you should also look at the [oppia/oppia repository](https://github.com/oppia/oppia).
+
+If you run into any problems, you can ask questions on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions). You can also check out the [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-android-dev).
+
+Finally, if, after reading the above links, you'd like to help but aren't sure how -- don't worry! The Oppia project is very multi-faceted, and we'd be glad to help you find something to do that matches your interests and skills. Just fill out [this form](https://forms.gle/jEytndtgdsx7BrnV6) to let us know what you'd like to help with, or write to us at [volunteer@oppia.org](mailto:volunteer@oppia.org) and tell us a bit about yourself and what you'd like to do. We'll do our best to help you get started!
diff --git a/wiki/Installing-Oppia-Android.md b/wiki/Installing-Oppia-Android.md
new file mode 100644
index 00000000000..5fb0aea95d9
--- /dev/null
+++ b/wiki/Installing-Oppia-Android.md
@@ -0,0 +1,68 @@
+This wiki page explains how to install Oppia Android on your local machine. If you run into any issues with the installation process, please feel free to ask on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/categories/q-a-installation), so that we can help you while also making these instructions better for other developers. Thanks!
+
+## Table of Contents
+
+- [Prepare developer environment](#prepare-developer-environment)
+- [Install oppia-android](#install-oppia-android)
+- [Run the app from Android Studio](#run-the-app-from-android-studio)
+
+
+## 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).
+
+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.
+
+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).
+
+ Then, click "Apply" to download and install these two SDKs/Tools.
+
+## Install oppia-android
+
+Please follow these steps to set up Oppia Android on your local machine.
+
+1. Create a new, empty folder called `opensource/` within your home folder. Navigate to it (`cd opensource`), then [fork and clone](https://github.com/oppia/oppia-android/wiki/Fork-and-Clone-Oppia-Android) the Oppia-Android repo. This will create a new folder named `opensource/oppia-android`. Note that contributors who have write access to the repository may either create branches directly on oppia/oppia-android or use a fork.
+
+ **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.):
+
+ - For Mac or Linux
+ 1. Open a terminal and navigate to `opensource/oppia-android/`.
+ 2. Run the script `bash scripts/setup.sh`.
+
+ - For Mac with Apple M1 chip
+ 1. Locate Terminal in Finder.
+ 2. Right-click and create a duplicate Terminal (and rename it accordingly, say Terminal x86, to avoid confusion).
+ 3. In the Terminal x86, right-click and click "Get info", and check the option "Open using Rosetta".
+ 4. Navigate to `opensource/oppia-android/` in Rosetta.
+ 5. Finally, run `bash scripts/setup.sh` in Terminal x86 and all the required files should be generated. (You should see messages like `Ktlint file downloaded`, etc.)
+
+ - For Windows
+ 1. Install [Git Bash Command Line](https://gitforwindows.org/)
+ 2. Open Git Bash Command Line.
+ 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`.
+ 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.)
+
+## Run the app from Android Studio
+
+1. Go to Tools > Device 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".
+ - Click "Finish" to complete setup.
+
+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.
\ No newline at end of file
diff --git a/wiki/Instructions-for-making-a-code-change.md b/wiki/Instructions-for-making-a-code-change.md
new file mode 100644
index 00000000000..ca91ee920ff
--- /dev/null
+++ b/wiki/Instructions-for-making-a-code-change.md
@@ -0,0 +1,79 @@
+**Important:** Please read the [Oppia Android coding style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide) before making any code changes.
+
+**Working on your first Pull Request?** You can learn how from this free series: [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
+
+*If your change isn't trivial, please [talk to us](https://gitter.im/oppia/oppia-android) before you start working on it -- this helps avoid duplication of effort, and allows us to offer advice and suggestions. For larger changes, it may be better to first create a short doc outlining a suggested implementation plan, and send it to the Android dev team for feedback.*
+
+The following instructions describe how to make a one-off code change using a feature branch. (In case you're interested, we mainly use the [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow).) Please follow them carefully, otherwise your code review may be delayed.
+
+You might also find this reference for the [Android Studio UI-based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) helpful.
+
+1. **Choose a descriptive branch name.** It should be lowercase and hyphen-separated, such as `splash-screen`. Also, it shouldn't start with `hotfix` or `release`.
+2. **Before coding anything, create a new branch with this name, starting from 'develop'.** I.e., run:
+
+ ```
+ git fetch upstream
+ git checkout develop
+ git merge upstream/develop
+ git checkout -b your-branch-name
+ ```
+
+3. **Make commit(s) to your feature branch.** Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made. However, **do not write "Fix #ISSUE_NUMBER"** (e.g. Fix #99999) in your commit messages, as this will cause Github to close the original issue automatically. You can rename your commit messages using `git commit --amend`.
+
+ * Before making the commit, do some sanity-checks:
+ * Start up a local instance of Oppia and do some manual testing in order to check that you haven't broken anything!
+ * Ensure that your code follows the [style rules](https://github.com/oppia/oppia-android/wiki/Coding-style-guide) and that it is well-tested.
+ * Ensure that the code has no [lint errors](https://github.com/oppia/oppia-android/wiki/Ktlint-Guide) and passes all automated tests (which will automatically run when you create your pull request).
+ * Use a tool like `git diff` or `meld` to check that the changes you've made are exactly what you want them to be, and that you haven't left in anything spurious. Make sure to do this _before_ you push.
+
+ * To actually make the commit and push it to your GitHub fork, run:
+
+ ```
+ git commit -a -m "{{YOUR COMMIT MESSAGE HERE}}"
+ git push origin {{YOUR BRANCH NAME}}
+ ```
+
+ Make sure to do this from the command line (and not GitHub's Desktop client), since this also runs some important presubmit checks before your code gets uploaded to GitHub. **If any of these checks fail, the push will be interrupted**. If this happens, fix the issues that the tests tell you about and **repeat the instructions above** ('commit' and then 'push').
+
+4. **When your feature is ready to merge, create a pull request.**
+ * Go to your fork on GitHub, select your branch from the dropdown menu, and click "pull request". Ensure that the 'base' repository is the main oppia repo (not your fork) and that the 'base' branch is 'develop'.
+ * Add a descriptive title explaining the purpose of the PR (e.g. "Fix issue #bugnum: add a warning when the user leaves a page in the middle of an exploration.").
+ * If the PR resolves an issue on the issue tracker, the title must start with **"Fix #bugnum: "**. This will be the case for most PRs.
+ * However, if your PR fixes part of a bigger issue (e.g. the first-contributor-issues listed above), please use **"Fix part of #bugnum: "** instead. Otherwise, GitHub will close the entire issue automatically when your PR is merged.
+ * Fill out the PR checklist (this shows up in the body of the PR when you create it), ensuring that your PR description includes the issue number (e.g. "This PR fixes issue #bugnum" or "This PR fixes part of issue #bugnum").
+ * Click "Create pull request", then **immediately** check the "Files changed" tab on your PR on GitHub and read it carefully to make sure that the changes are correct (e.g., that you haven't left out important files that should be part of the PR. (If not, please fix this by making additional commits, or by closing this PR and submitting a new one, before requesting a review.) This is a good way to catch obvious errors that would otherwise lead to delays in the review process.
+ * Request a review from the issue's "owner" **and** also set them as the PR assignee.
+ * Leave a top-level comment on your PR saying "@{{reviewer}} PTAL", where {{reviewer}} is the GitHub username of your reviewer. ("PTAL" means "Please take a look".)
+ * Then, wait for your code to get reviewed! While you're doing so, it's totally fine to start work on a new PR if you like. Just make sure to **checkout the develop branch** and sync to HEAD before you check out a new branch, so that each of your feature branches is based off the main trunk.
+
+5. #### **Address review comments until all reviewers give LGTM ('looks good to me').**
+ * When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways:
+ * Make a new commit addressing the comments you agree with, and push it to the same branch. (Continue to use descriptive commit messages. If your commit addresses lots of disparate review comments, it's fine to refer to the original commit message and add something like "(address review comments)".)
+ * **Always make commits locally, and then push to GitHub.** Don't make changes using the online GitHub editor -- this bypasses lint/presubmit checks, and will cause the code on GitHub to diverge from the code on your machine.
+ * **Never force-push changes to GitHub, especially after reviews have started.** This will delay your review, because it overwrites history on GitHub and makes the incremental changes harder to review.
+ * In addition, reply to each comment via the Files Changed tab, choosing the "Start a review" option for the first comment. Each reply should be either "Done" or a response explaining why the corresponding suggestion wasn't implemented. When you've responded to all comments, submit the review to add all your messages to the main thread. All comments must be responded to and resolved before LGTM can be given.
+ * Resolve any merge conflicts that arise. To resolve conflicts between 'new-branch-name' (in your fork) and 'develop' (in the oppia repository), run:
+
+ ```
+ git checkout new-branch-name
+ git fetch upstream
+ git merge upstream/develop
+ ...[fix the conflicts -- see https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line]...
+ ...[make sure the tests pass before committing]...
+ git commit -a
+ git push origin new-branch-name
+ ```
+ * Once you've finished addressing everything, and would like the reviewer to take another look:
+ * Start a dev server in order to make sure that everything still works.
+ * Check that the changes in the "Files Changed" tab are what you intend them to be.
+ * **Write a top-level comment** explicitly asking the reviewer to take another look (e.g. "@XXX PTAL"), and set them as the assignee for the PR.
+ * At the end, the reviewer will merge the pull request.
+
+6. **Tidy up!** After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository:
+
+ ```
+ git branch -D new-branch-name
+ git push origin --delete new-branch-name
+ ```
+
+7. **Celebrate.** Congratulations, you have contributed to the Oppia Android project!
diff --git a/wiki/Internationalization.md b/wiki/Internationalization.md
new file mode 100644
index 00000000000..be7164ef4f4
--- /dev/null
+++ b/wiki/Internationalization.md
@@ -0,0 +1,39 @@
+We are grateful for the support of [Translatewiki](https://translatewiki.net/w/i.php?title=Special:Translate&group=oppia-android-app&filter=%21translated&action=translate) in contributing internationalized platform strings for the Oppia Android app! (Note that Translatewiki only provides support for translations of platform UI strings; content string translations are handled via the Contributor Dashboard on the Oppia.org website.)
+
+## Helping out with translations
+
+If you would like to help out with translations, you can do so by visiting the [Translatewiki dashboard](https://translatewiki.net/w/i.php?title=Special:Translate&group=oppia-android-app&filter=%21translated&action=translate) and picking a supported language from the dropdown menu on the right.
+
+## Minimal set of topics
+
+In addition to platform translations, we need the Oppia lessons themselves to be sufficiently translated before we can offer the app in a given language.
+
+Currently, we define "sufficiently translated" to mean that the **minimal set** of topics are fully translated. This minimal set covers 6 topics: Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios.
+
+## Policy for enabling new languages
+
+Note that we only enable a select set of languages for Translatewiki, since releasing the lessons on the Android app is gated by the lessons themselves needing to be translated (see above). Therefore, in order not to waste translators' efforts, the policy for enabling languages for translation on Translatewiki is as follows:
+
+ - The translations for all topics in the [minimal set](https://github.com/oppia/oppia-android/wiki/Internationalization#minimal-set-of-topics) on Oppia.org should be complete, or very close to complete.
+
+And the policy for enabling a language in the Android app is as follows:
+
+ - The translations for all topics in the [minimal set](https://github.com/oppia/oppia-android/wiki/Internationalization#minimal-set-of-topics) on Oppia.org should be complete.
+ - All oppia-android-app translations for that language are completed in Translatewiki.
+
+## Procedure for enabling new languages
+
+### To enable a new language in Translatewiki
+
+Please do the following steps:
+
+ 1. Verify that translations for all lessons in the [minimal set](https://github.com/oppia/oppia-android/wiki/Internationalization#minimal-set-of-topics) on Oppia.org are complete (or very close to complete) in that language, by going to the Contributor Dashboard and checking that there are no (or very few) translations left to do.
+ 2. Contact Ben/Sean and ask them to add the language to the oppia-android-app project. (They will do this by contacting translatewiki@translatewiki.net .)
+
+### To enable a new language in the Android app
+
+Please do the following steps:
+
+ 1. Verify that translations for all lessons in the [minimal set](https://github.com/oppia/oppia-android/wiki/Internationalization#minimal-set-of-topics) on Oppia.org are complete in that language, by going to the Contributor Dashboard and checking that there are no translations left to do.
+ 2. Verify that the translations on [Translatewiki](https://translatewiki.net/w/i.php?title=Special:Translate&group=oppia-android-app&filter=%21translated&action=translate) for the Oppia Android app are complete in that language.
+ 3. In consultation with Ben, make a PR adding support for that language ([here](https://github.com/oppia/oppia-android/pull/4307/files) is an example for Swahili).
\ No newline at end of file
diff --git a/wiki/Interpreting-CI-Results.md b/wiki/Interpreting-CI-Results.md
new file mode 100644
index 00000000000..b0135d27293
--- /dev/null
+++ b/wiki/Interpreting-CI-Results.md
@@ -0,0 +1,16 @@
+## How to find error message for Failing CI checks
+
+Creating a pr or updating a pr runs all the CI checks, which can sometimes fail if the code changes have affected some other part of the app or if the code changes don’t need some reformatting and docs. In these cases understanding the error and fixing it requires how to find the error.
+
+
+
+
+All the checks of the latest commit in the pull request are displayed at the bottom of the pr. Scroll to all the checks and open details for the failing checks which display logs of each check.
+
+Each check contains multiple jobs and now select the job with the failure.
+Example in the below check the second job has some error or failure
+
+
+
+
+Navigate to logs or search the keyword ‘error’ to find the error message to understand what might have caused the failure in the checks.
diff --git a/wiki/Kotlin-Coroutines.md b/wiki/Kotlin-Coroutines.md
new file mode 100644
index 00000000000..6173dc5bd53
--- /dev/null
+++ b/wiki/Kotlin-Coroutines.md
@@ -0,0 +1,18 @@
+### Kotlin coroutines
+
+The team leverages [Kotlin coroutines](https://kotlinlang.org/docs/coroutines-overview.html) for background processing, however we never launch a new dispatcher or use any of the built-in dispatchers. Instead, we use one of our existing dispatchers:
+- [BackgroundDispatcher](https://github.com/oppia/oppia-android/blob/141511329ea0249ff225a469c70658c3b2123238/utility/src/main/java/org/oppia/android/util/threading/BackgroundDispatcher.kt#L6): for executing expensive operations
+- [BlockingDispatcher](https://github.com/oppia/oppia-android/blob/141511329ea0249ff225a469c70658c3b2123238/utility/src/main/java/org/oppia/android/util/threading/BlockingDispatcher.kt#L6): for executing operations that need to be done in parallel (generally, don't use this--prefer InMemoryBlockingCache, instead)
+
+New operations should create a separate scope using one of the existing dispatchers & perform their execution using that. Note that failures in operations will cause the scope itself to enter a failed state, so scopes shouldn't be kept long-term for correctness.
+
+### Synchronizing state in tests
+
+One major benefit in consolidating all execution on the same coroutine dispatchers is that facilitates easy thread synchronization boundaries in tests. [TestCoroutineDispatchers](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt#L30) is a test-injectable utility with a number of useful API functions:
+- [``(un)registerIdlingResource``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt#L49): ensures background operations finish automatically before performing Espresso UI interactions
+- [``runCurrent``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt#L65): run all background tasks that can be completed now without advancing the clock (Robolectric tests run with a fake clock that has to be manually advanced)
+- [``advanceTimeBy``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt#L80) / [``advanceUntilIdle``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt#L93): functions for running tasks scheduled in the future
+
+Generally, registering an idling resource for shared Espresso/Robolectric tests and calling ``runCurrent`` after performing any operations in the bodies of tests is sufficient to guarantee no test flakes for nearly all scenarios. There are many examples of using both throughout the codebase.
+
+``advanceTimeBy``/``advanceUntilIdle`` should only be used in cases where they are specifically needed (prefer ``runCurrent`` where possible since ``advanceUntilIdle`` is more of a "sledgehammer" solution and should rarely be necessary).
diff --git a/wiki/Ktlint-Guide.md b/wiki/Ktlint-Guide.md
new file mode 100644
index 00000000000..aedd09d9933
--- /dev/null
+++ b/wiki/Ktlint-Guide.md
@@ -0,0 +1,53 @@
+# Installation
+Once you had completed all the [installation steps](https://github.com/oppia/oppia-android/wiki#prerequisites), you will be having a `ktlint` file in your `opensource/oppia-android-tools` folder.
+
+# Commands
+
+**Note: Keep your terminal or command line to `opensource/oppia-android` path while running below commands.**
+
+* Check the version of your ktlint. As of now on GitHub Actions, we are using `0.37.1`.+`../oppia-android-tools/ktlint --version`
+ +* Android Kotlin Style Guide using `--android`
+`../oppia-android-tools/ktlint --android "path/of/your/kotlin/file"` + + * Examples
+ * Specific File
`../oppia-android-tools/ktlint --android app/src/sharedTest/java/org/oppia/android/app/walkthrough/WalkthroughWelcomeFragmentTest.kt`
+ * Specific Directory
`../oppia-android-tools/ktlint --android "utility/src/**/*.kt"` + +* Android Kotlin Style Guide using `--android` with Ktlint Auto Formatter `-F`. This will fix some of the issues automatically.
+`../oppia-android-tools/ktlint -F --android "path/of/your/kotlin/file"` + + * Examples
+ * Specific File
`../oppia-android-tools/ktlint -F --android app/src/sharedTest/java/org/oppia/android/app/walkthrough/WalkthroughWelcomeFragmentTest.kt`
+ * Specific Directory
`../oppia-android-tools/ktlint -F --android "utility/src/**/*.kt"` + +# Macros +In Android Studio we have a feature called Macros which helps you convert multiple tasks in one shortcut. + +There are two major tasks when we talk about style formatting, One is the `Reformat Code` and another one is `Optimize imports`. + +* `Reformat Code` - this will reformat your code with proper indentation and newlines wherever needed. +* `Optimize imports` - this will remove all the unused import from your file. Also, this will rearrange your imports in lexicographical order and all those imports which are starting with `java`, `javax` or `Kotlin` will get shifted at the end of the import list which is a correct order. + +### Steps to create a macro: +1. Double shift +2. Search for "macros" +3. Click on "Macros" +4. Click on "start macro reading" +5. Menu Toolbar -> Code -> Reformat Code -> Menu Toolbar -> Code -> Optimize Import -> click on stop macro reading at bottom +6. Now you can give whatever shortcut you want and these above two steps will get performed + +# How to fix the most common issues? +* `Wildcard Imports` - If you had imported anything which directs to just the package `import java.util.*`, it will give you an error saying there should not be any wildcard imports. So, you had to use the path completely for what you need in your file. + + * Example - `import java.util.Date` or `import java.util.Locale` + +* `Exceeding 100 char limit` - This means that there is a line of code which is more than 100 char in one line. You must have noticed a grey line in the editor area, the code should not cross that line. + + There are some cases like the name of the tests where the code crosses that line and we cannot rearrange it as it is the name of the function. This does not apply to comments. There you should put a ktlint comment using which ktlint disable the check for 100 char limit. `// ktlint-disable max-line-length` + + * Example -
+ * `fun testWalkthroughWelcomeFragment_recyclerViewIndex1_topicSelected_clickNoButton_worksCorrectly() { // ktlint-disable max-line-length` + +**Note: We don't recommend the use of `// ktlint-disable max-line-length` to disable the ktlint check unless the line of code cannot be broken into multiple lines to prevent disabling ktlint check.** \ No newline at end of file diff --git a/wiki/Oppia-Android-Testing.md b/wiki/Oppia-Android-Testing.md new file mode 100644 index 00000000000..c110bdb925d --- /dev/null +++ b/wiki/Oppia-Android-Testing.md @@ -0,0 +1,343 @@ +# Overview +Testing the app is an integral part of an app development process. By running tests against the app consistently, you can verify your app's correctness, functional behavior, and usability before you release it publicly. + +In Oppia we are considering: +* Robolectric testing +* JUnit testing +* Integration/Screenshot tests using Espresso +* Performance tests +* LeakCanary +* Hermetic end-to-end testing using Espresso + some way to run the Oppia developer backend (or maybe better: drive using UIAutomator using a real production Oppia backend set up for testing purposes) + +# Learning how to write good tests +[This presentation](https://docs.google.com/presentation/d/1jPyrVafvlCCaT0qY2r1Z1PYKL6MaklXo2QaO5FiJSKo/edit?usp=sharing) provides an overview on testing as a whole, and explains what makes a good test. We suggest that you familiarize yourself with the concepts introduced in that presentation before writing any tests in Oppia Android. + +# Guidelines for testing +## Naming Convention +Test names should read like a sentence, and be consistent with other nearby test names to facilitate easily coming up with new tests. Consider using a format similar to the following for naming test functions: + +_`testAction_withOneCondition_withSecondCondition_hasExpectedOutcome`_ + +where _`testAction`_, _`withCondition`_ and _`hasExpectedOutcome`_ are replaced with appropriate descriptions in camelCase. Put the outcome at the end of the name, so that you and others can easily compare consecutive tests of the same method that have slightly different conditions with divergent outcomes. + +For Example: +* `testProfileChooserFragment_initializeProfiles_checkProfilesAreShown` +* `testSplashActivity_initialOpen_routesToHomeActivity` + +## assertThat() vs. assertEqual(), assertTrue() / assertFalse() +Use `assertThat()` instead of `assertEqual()`, `assertTrue()` / `assertFalse()` + +The first benefit is that `assertThat()` is more readable than the other assert methods. For example, take a look at the following `assertEquals()`: +```kotlin +assertEquals(expected, actual) +``` + +In the `assertEquals()`, you can easily get confused and interchange the actual and expected argument position. +``` kotlin +assertThat(actual).isEqualTo(expected) +``` + +The first thing to notice is that it’s the other way around (actual first, expected second), which is a big advantage. It also reads more like a sentence: “Assert that the actual value is equal to the expected value.” As another, better example of readability, compare how to check for not equals, first the old way: +``` +assertFalse(expected.equals(actual)) +``` + +Since there is no **assertNotEquals** (unless it’s custom coded) we have to use assertFalse and do an equals on the two variables. Here’s the much more readable new way with `assertThat()`: +```kotlin +assertThat(actual).isNotEqualTo(expected) +``` + +If we want to verify that two values are not equal, we have to write our assertion by invoking the isNotEqualTo() method. + +Some simple methods exist for truth testing: +```kotlin +assertThat(logicalCondition).isTrue() +assertThat(logicalCondition).isFalse() +``` +Hence assertThat should be the preferred method over the other methods. + +## Testing private methods/functions +Tests should only be written to verify the behaviour of public methods/functions. Private functions should not be used in behavioural tests. Here are some suggestions for what to do in specific cases (if this doesn't help for your particular case and you're not sure what to do, please talk to @BenHenning): +* If you want to test code execution of a private method/function, test it through the public interface, or move it to a utility (if it's general-purpose) where it becomes public. Avoid testing private APIs since that may lead to brittle test in unexpected situations (such as when the implementation of the API changes, but the behaviour remains the same). +* If you’re trying to access hidden information, consider getting that information from one level below instead (e.g. datastore). + +# Oppia project organization for tests + +The following is the default directory structure for Oppia application and test code: +* app/src/main/java- for the source code of the Oppia application build +* app/src/test/java- for any unit test which can run on the JVM +* app/src/androidTest/java- for any test which should run on an Android device + +If you follow this conversion, the Android build system runs your tests on the correct target (JVM or Android device). + +## Robolectric +With [Robolectric](https://github.com/robolectric/robolectric) you can write tests like this: +```java +@RunWith(AndroidJUnit4.class) +public class MyActivityTest { + + @Test + public void clickingButton_shouldChangeResultsViewText() throws Exception { + Activity activity = Robolectric.setupActivity(MyActivity.class); + + Button button = (Button) activity.findViewById(R.id.press_me_button); + TextView results = (TextView) activity.findViewById(R.id.results_text_view); + + button.performClick(); + assertThat(results.getText().toString()).isEqualTo("Testing!")); + } +} +``` + +### Running Robolectric tests +1. Go to **Edit Configuration** in Android Studio +
+
+2. Add **Android JUnit**
+
+
+3. Enter following information - (a.) **Name** (Normally class name) (b.)**Use classpath of module** (c.) **Class**
+
+
+
+4. Press `OK` to run the test cases in robolectric.
+
+## Espresso
+
+Use [Espresso](https://developer.android.com/training/testing/espresso) to write concise, beautiful, and reliable Android UI tests.
+Example JUnit4 test using Rules:
+
+```kotlin
+@RunWith(AndroidJUnit4::class)
+class PinPasswordActivityTest {
+
+ @Before
+ fun setUp() {
+ Intents.init()
+ }
+
+ @Test
+ fun testPinPasswordActivityWithAdmin_inputCorrectPin_checkOpensHomeActivity() {
+ ActivityScenario.launch+ - Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
+ - macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` + - **Make sure you have the system environment variable set up** for ``ANDROID_HOME`` as you might have issues getting properly set up if not. If it isn’t set up (on Linux you can check by using ``echo $ANDROID_HOME`` in a new terminal; it should output the correct path to your Android SDK), on Linux you can move the ``export`` from above to your ``~/.bashrc`` file to make it permanent (you can apply the change immediately using ``source ~/.bashrc``). + +5. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). + + +#### Building the app + +After the installation, completes you can build the app using Bazel. + +**Move your command line head to the `~/opensource/oppia-android`**, then run the below bazel command: + +``` +bazel build //:oppia +``` + +#### Building + installing the app + +``` +bazel build //:oppia && adb install -r bazel-bin/oppia.apk +``` + +#### Running specific module (app) Robolectric tests + +``` +bazel test //app/... +``` + +#### Running all Robolectric tests (slow) + +``` +bazel test //... +``` + +## Known Issues and Troubleshooting + +See our [troubleshooting wiki page](https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation#bazel-issues) for some known issues with Bazel, and the corresponding troubleshooting steps. + + +## Concepts and Terminology +**[Workspace](https://github.com/oppia/oppia-android/blob/develop/WORKSPACE)**
+A workspace is a directory where we add targeted SDK version, all the required dependencies and there required Rules. The directory containing the WORKSPACE file is the root of the main repository, which in our case is the `oppia-android` root directory is the main directory. + +**[Packages](https://github.com/oppia/oppia-android/tree/develop/app)**
+A package is defined as a directory containing a file named BUILD or BUILD.bazel. + +**[Binary rules](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/BUILD.bazel#L3)**
+A rule specifies the relationship between inputs and outputs, and the steps to build the outputs. +In Android, rules are defined using `android_binary`. Android rules for testing are `android_instrumentation_test` and `android_local_test`. + +**[BUILD files](https://github.com/oppia/oppia-android/blob/develop/app/BUILD.bazel)**
+Every package contains a BUILD file. This file is written in Starlark Language. In this Build file for module-level, we generally define `android_library`, `kt_android_library` to build our package files as per the requirement. + +**[Dependencies](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/BUILD.bazel#L16)**
+A target A depends upon a target B if B is needed by A at build. `A -> B`
+``` +deps = [ "//app",] +``` +Here, `deps` is used to define the dependencies which is a type of dependencies called `deps dependencies` and it includes the files/directory/target which are dependent. From the above example the dependency is the `app` target which is defined in the [Build file of app package](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L616). + +Example of Dependencies +1. [srcs dependencies](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L617) +2. [deps dependencies](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L622) + +**[Loading an extension](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L13)**
+Bazel extensions are files ending in .bzl. Use the load statement to import a symbol from an extension.
+``` +load("@io_bazel_rules_kotlin//kotlin:kotlin.bzl", "kt_android_library") +``` +Here, we are loading `kotlin.bzl` and we are going to use it with a symbol name `kt_android_library`. +Arguments to the load function must be string literals. load statements must appear at top-level in the file. + +**[Visibility of a file target](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L621)**
+With the example from our codebase, target `app` whose visibility is public.
+ - `visibility = ["//visibility:public"],` - Anyone can use this target.
+ - `"//visibility:private"` - Only targets in this package can use this target. + +**[Testing](https://github.com/oppia/oppia-android/blob/ba8d914480251e4a8543feb63a93b6c91e0a5a2f/app/BUILD.bazel#L719)**
+when we want to run test cases on Bazel build environment, we usually pass arguments related to test which `app_test.bazl` required to run our test. +``` +app_test( + name = "HomeActivityLocalTest", + srcs = ["src/test/java/org/oppia/android/app/home/HomeActivityLocalTest.kt"], + test_class = "org.oppia.android.app.home.HomeActivityLocalTest", + deps = TEST_DEPS, +) +``` + diff --git a/wiki/Our-Mission.md b/wiki/Our-Mission.md new file mode 100644 index 00000000000..dd6959ef733 --- /dev/null +++ b/wiki/Our-Mission.md @@ -0,0 +1,25 @@ +# Oppia’s Mission +The Oppia Foundation’s mission is to **provide high quality education to those who lack access to it**. We do this through the creation and maintenance of the [Oppia platform](https://www.oppia.org/) which enables the creation and distribution of high-quality scalable online lessons that are constructed according to established educational principles. We also support this mission through the empowerment and coordination of our volunteer community, and the development of critical partnerships with NGOs in the communities we aim to serve. + +# Vision +To work towards this mission, the following steps are needed: (i) creating lessons, (ii) ensuring that they are effective in increasing students’ mastery, (iii) ensuring that they retain students, (iv) ensuring that they are universally accessible, and (v) marketing them. The following sections briefly give an overview of existing progress for each of these, and outline the work that remains to be done. + +### (i) Creation of lessons +We are working towards a full curriculum for Basic Mathematics as a first step, and have developed a lesson creation process that creators have successfully used to build several sets of high-quality lessons. To empower others to create effective lessons on any topic where help is needed, we hope to make this process more self-service and granular via site interface accommodations (including avenues for contributing images and translations, as well as channels for continuously improving existing lessons), as well as make it easier for volunteers around the world to help out with the overall effort. + +### (ii) Effectiveness of lessons +We’ve verified the effectiveness of our first few Fractions lessons with a randomized controlled trial (RCT). On completion of our initial basic math curriculum and supporting infrastructure (e.g. questions), we plan to conduct more RCTs with lessons in this curriculum to ensure that they continue to be effective, and will also try and set up some long-term analysis of effects of exposure to the lessons on students. In addition, we will enter a phase of improving the lessons, including developing a standardized framework to measure effectiveness. This will make it possible to analyze which changes in lessons lead to student skill improvement, and ensure that the resulting findings make their way into the lessons through the aforementioned channels for lesson improvement. + +### (iii) Retention of students +We have found a way to write engaging lessons that situate what’s being taught in the context of meaningful real-life stories and situations. We plan to measure the success of this effort through student interviews and analysis of retention metrics. This goal also relies on the learner experience being bug-free. + +### (iv) Universally accessible lessons +Oppia’s infrastructure for creating lessons currently supports mobile usage, audio subtitles, and affordances for flaky connections (in that, once a lesson is loaded, it stays playable even if the connection subsequently drops). We plan to extend the audio subtitles program and make it easier for translators and voiceover artists to add subtitles to lessons. We also plan to build functionality for lessons to be downloaded for offline use, and to partner with other nonprofits to enable them to use the lessons in a way that is contextually appropriate for their existing programs and students. In addition, we will add support to ensure that Oppia learner-facing functionality works well in poor network conditions. + +### (v) Marketing and Growth +Once we have created a Basic Mathematics curriculum, we need to market the lessons in order to ensure that students know about them and can use them! We plan to work together with partners in various countries to distribute the lessons to students who need them, as well as provide smooth “getting started” pathways for NGOs, parents and teachers with instructions on how to use the lessons most effectively in their particular context. + +*** + +For all the above, we will conduct careful planning in order to operate sustainably so that the members of our open source and volunteer communities have a fulfilling and enjoyable experience. In particular, prioritization is necessary for helping us focus on the things that are most critical for success, since taking on too many projects at a time is a recipe for overload and burnout. We are fully committed to enabling and supporting our volunteer community, and providing meaningful opportunities for people around the world who want to contribute to a beneficial cause with strong social impact. + diff --git a/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md new file mode 100644 index 00000000000..86c3c9f0445 --- /dev/null +++ b/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -0,0 +1,186 @@ +The Oppia Android codebase makes use of Kotlin and XML and can be built using Android Studio. The Oppia app follows a layered architecture that combines parts of [MVP](https://medium.com/upday-devs/android-architecture-patterns-part-2-model-view-presenter-8a6faaae14a5) (Model-View-Presenter), [MVC](https://medium.com/@joespinelli_6190/mvc-model-view-controller-ef878e2fd6f5) (Model-View-Controller), and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). + +## Directory Structure + +
+
+
+The Oppia project follows a standard Gradle project layout with five modules. Each subdirectory in a module contains files that are specific to a particular feature or purpose.
+
+#### 1. app
+
+This module contains all the activities and fragments, as well as the view, view model, and presenter layers. It also contains Robolectric test cases and integration tests using Espresso. Here are the contents of some of its main subdirectories:
+
+- **app/activity** - Basic [Dagger](https://github.com/google/dagger) code for activity implementation.
+- **app/application** - Dagger code for the application, with different module declarations.
+- **app/customview** - Custom UI items used by the application.
+- **app/databinding** - Different BindingAdapters which can be used in any layout file.
+- **app/fragment** - Basic Dagger code for fragment implementation.
+- **app/player** - Everything related to the exploration player (e.g. audio, state, etc.).
+- **app/story** - Fragments, activities, view models, adapters, presenters and interfaces related to the Story screen.
+- **app/testing** - All dummy test activities and fragments that are needed to test the Android functionality correctly. These help with writing test cases.
+- **app/topic** - Fragments, activities, view models, adapters, presenters and interfaces related to the Topic screen and its four tabs.
+- **app/translation** - UI utilities for managing languages & locales.
+- **app/utility** - Any code which can be used centrally, e.g. date-time getter-setter, keyboard controller, etc .
+- **app/view** - Basic Dagger code for View implementation.
+- **app/viewmodel** - Basic Dagger code for ViewModel implementation.
+
+In addition to the above-mentioned subdirectories, this module also contains other subdirectories that contain activities, fragments, interfaces and view models for various screens in the app. These subdirectories follow the naming convention **app/
+
+
+The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Model-View-ViewModel), where different Android components fulfil requirements for each piece:
+
+1. Android Fragments are presenters: they hold the majority of business logic and can optionally have a view but are otherwise responsible for arranging the UI layout and binding view models to Views.
+
+2. Android Views are classic views: they perform no logic and are simply responsible for displaying data from view models (via Android data-binding).
+
+3. View models are Android ViewModels that listen for and expose changes from the model layer.
+
+4. The model layer is defined by a combination of protobuf and Kotlin data objects provided from the controller layer using LiveData. Managers are responsible for maintaining the state in this layer.
+
+5. The controller layer interacts with the database and network. It provides data via a custom data source mechanism.
+
+6. Android Activities should only perform high-level fragment transaction logic and are responsible for initialising Dagger components and performing routing.
+
+## Codebase Walkthrough
+
+Here is an example of how to traverse the codebase. (Note that the examples below are not real tasks/features and should not be implemented.)
+
+### Example 1
+
+
+**Task:**
+
+Add a button in Info Tab to open an already existing activity (e.g. SplashActivity).
+
+**Walkthrough:**
+
+1. Based on the above subdirectory details, we know that app/topic contains all files related to Topic and its tabs.
+
+2. Inside this folder, there is another directory app/topic/info, which should contain information related to the already-existing TopicInfo Tab. In this subdirectory, we see 3 files, TopicInfoFragment, TopicInfoFragmentPresenter and TopicInfoViewModel.
+
+3. Now, let’s first open TopicInfoFragment. This extends InjectableFragment, and we can see that it just calls the TopicInfoFragmentPresenter.
+
+4. Inside TopicInfoFragmentPresenter, we can see that an XML layout inflates using [DataBinding](https://developer.android.com/topic/libraries/data-binding). You can see this via this line:
+
+
+
+ ```
+ val binding = TopicInfoFragmentBinding.inflate(
+ inflater,
+ container,
+ /* attachToRoot= */ false
+ )
+ ```
+
+
+5. From this, we know that the corresponding XML file name is **topic_info_fragment.xml**.
+
+6. Now, open the **topic_info_fragment.xml** file and create a button inside it.
+
+7. The button click can be handled by data-binding a function (clickDummyButton) to the XML. That function will be created in the **TopicInfoViewModel**. We know from the App Architecture section that the ViewModel does not handle the logic, and the presenter is responsible for the logic part.
+
+8. The ViewModel doesn't have access to the presenter directly and instead needs to go through either the fragment or the activity hosting the view via a listener that can be called down into the presenter to perform necessary logic. So we have to get access to the **TopicInfoViewModel** in T**opicInfoFragmentPresenter**.
+
+9. So, now that we have access to the ViewModel in the presenter, we will create another function (goToSplashActivity) inside the TopicInfoFragmentPresenter. We can then call this function inside clickDummyButton which was present in TopicInfoViewModel.
+
+
+Following these steps would lead to completing the entire task with all the code blocks in the correct files.
+
+### Example 2
+
+**Task:**
+
+Finding code from a string ( e g., topic description under topic info tab) that you see in UI when running the app all the way to the UI components, domain controllers and the tests ultimately behind that text appearing.
+
+
+
+**Walkthrough:**
+
+**Finding the UI component (topic description)**
+
+1. The first step is to identify the id of the UI component that is responsible for displaying the text. We can do this by using the layout inspector of the android studio.
+
+2. To do this, run the app on an emulator. Now navigate to the screen that displays the UI component, i.e. the topic info tab.
+
+3. Next, open the layout inspector from the android studio, and click on the UI component displaying the topic description. Now all the attributes of this UI component are displayed on the right side of the layout inspector. Here, you can see this UI component's id, i.e. topic_description text_view.
+
+
+
+4. Now we have to find the file with a UI component with this id. We can do this by pressing double shift and then typing the id. Doing this, we see the id is the id of a text view present in the file topic_info_fragment.xml.
+
+5. Now that we know that the text view is present in topic_info_fragment.xml, according to the app architecture, we know that the name of this fragment is TopicInfoFragment. The files responsible for displaying this fragment are TopicInfoFragment.kt and TopicInfoFragmentPresenter.kt.
+
+6. Looking at the XML code for topic_description_text_view, we can see that TopicInfoViewModel sets the text in the text view using databinding.
+
+**Finding the business logic for the UI component, i.e. domain controllers**
+
+1. Following the app architecture used by Oppia, TopicInfoViewModel should be initialized in the TopicInfoFragmentPresenter.
+
+2. Here we can see that the topic description is being updated in the viewModel by the TopicController. Therefore the business logic for getting the topic description will be present in the file TopicController.
+
+**Finding the tests**
+
+There are two sets of tests:
+- Tests to test the UI component
+- Tests to test the business logic of the UI component
+
+Since the UI component is present in the TopicInfoFramgnet, the UI component tests are present in the file TopicInfoFragmentTest.
+
+Similarly, since the business logic is present in the file TopicController, the tests for this controller can be found in the file TopicControllerTest.
+
+## Dependency Injection
+
+Oppia Android uses Dagger 2 for dependency injection. For an overview of how DI works in general, and specifically how it’s set up in Oppia Android, see [these presentation slides](https://docs.google.com/presentation/d/1lLLjWRJB-mqDuNlhX5LoL87yBj5Tes0UUlvsLsbwH30/edit?usp=sharing).
\ No newline at end of file
diff --git a/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md b/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md
new file mode 100644
index 00000000000..f7c70dfad05
--- /dev/null
+++ b/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md
@@ -0,0 +1,16 @@
+### PersistentCacheStore
+
+[``PersistentCacheStore``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/data/src/main/java/org/oppia/android/data/persistence/PersistentCacheStore.kt#L34) is the team's replacement to ``SharedPreferences`` except it:
+1. Never blocks the main thread
+2. Forces using [protocol buffers](https://developers.google.com/protocol-buffers) for the underlying storage structure to encourage background & forward compatibility
+3. Is a ``DataProvider`` which means it can be easily interoped with the codebase's other ``DataProvider``s
+
+*Note as of 8 April 2021*: ``PersistentCacheStore`` was created before [``DataStore``](https://developer.android.com/topic/libraries/architecture/datastore) from Android Jetpack was available for production use. The team may eventually migrate to this solution, but it's not currently planned.
+
+### In-Memory blocking cache
+
+While not a ``DataProvider``, [``InMemoryBlockingCache``](https://github.com/oppia/oppia-android/blob/a85399c2b0a2b9cf214881ce8c70d9b487f1e0b8/utility/src/main/java/org/oppia/android/util/data/InMemoryBlockingCache.kt#L19) is a concurrency primitive the team built to ensure single-threaded access to a single variable in-memory where the cache itself can be safely accessed from multiple threads, and no locking mechanism is needed. This is a coroutine-only utility that is meant to improve cross-thread state sharing performance, and is generally only used in cases where state must be synchronized across multiple threads.
+
+## Other cases of background processing
+
+There are other cases of background processing and concurrency that come up on the team, but don't yet have established best practices. One such example is triggering logic from Android's work manager (example: [``FirebaseLogUploader``](https://github.com/oppia/oppia-android/blob/141511329ea0249ff225a469c70658c3b2123238/utility/src/main/java/org/oppia/android/util/logging/firebase/FirebaseLogUploader.kt#L13)). Note that while these approaches aren't fully documented yet, the same best practices & principles above should be observed and enforced to ensure a good experience is provided both to end users and developers maintaining the app.
\ No newline at end of file
diff --git a/wiki/Platform-Parameters-&-Feature-Flags.md b/wiki/Platform-Parameters-&-Feature-Flags.md
new file mode 100644
index 00000000000..0ce92cb7d10
--- /dev/null
+++ b/wiki/Platform-Parameters-&-Feature-Flags.md
@@ -0,0 +1,152 @@
+## Introduction
+With a large scale system like Oppia, we sometimes have features that contain several points of integration in the codebase, and/or require additional data priming or migrations ahead of the feature being released. These features often span multiple releases and thus require feature flags to gate integration points to ensure that the feature is not partially released ahead of schedule. Moreover, these features often require migrations which need to be run in specific releases due to new versions being made in irreversible data structures (e.g. explorations).
+
+In order to release these types of features in a smooth manner, we need to be able to put these features behind feature flags that are enabled in specific builds (compile-time) and can be enabled dynamically (at runtime). Thus it actually involves introducing what are called platform parameters. These are parameters that can be one of several data types (e.g. strings, integers, booleans). We use boolean types for gating features as described above, but the other parameters are essential in order to ensure the app is reasonably configurable for many different circumstances (include deprecations).
+
+## How to create a Platform Parameter
+1. Create the Constants
+ - If the Platform Parameter you intend to create is related to a particular feature, so first check that do there exist a file in the `utility\src\main\java\org\oppia\android\util\platformparameter` which contains other Platform Parameters related to the same feature. If there is no such then create a new Kotlin file along with its name corresponding to the feature.
+ - After searching/making a "constants" file related to a feature, we need to define three things:
+ 1. Qualifier Annotation which will help us to distinguish our Platform Parameter from others.
+
+ + + ``` + /** + * Qualifier for the platform parameter that defines the time period in hours, after which the + * [PlatformParameterSyncUpWorker] will run again. + */ + @Qualifier + annotation class SyncUpWorkerTimePeriodInHours + ``` + + 2. The name of the Platform Parameter in String format + +
+ + ``` + /** + * Name of the platform parameter that defines the time period in hours, after which the + * [PlatformParameterSyncUpWorker] will run again. + */ + const val SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS = "sync_up_worker_time_period" + ``` + + 3. The default value for the Platform Parameter. For eg - here we define a `SyncUpTimePeriodInHours` platform parameter and its constants. + +
+ + ``` + /** + * Default value of the platform parameter that defines the time period in hours, after which the + * [PlatformParameterSyncUpWorker] will run again. + */ + const val SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE = 12 + ``` + +2. Provide your Platform Parameter + - For providing your Platform Parameter in the App, we need to first make a @Provides annotated method in the `PlatformParameterModule(domain\src\main\java\org\oppia\android\domain\platformparameter\PlatformParameterModule.kt)` + - The return type for this @Provides annotated method will be equal to either `PlatformPrameterValue\
+ + ``` + /* Dagger module that provides values for individual Platform Parameters. */ + @Module + class PlatformParameterModule { + ... + @Provides + @SyncUpWorkerTimePeriodInHours + fun provideSyncUpWorkerTimePeriod(platformParameterSingleton: PlatformParameterSingleton): PlatformParameterValue
+
+# Reference Documentation
+* [Oppia-Android RTL Issues](https://docs.google.com/document/d/1Fl1ar5vcdLvay7ZIJLUFQro1wEf1yUEicwF-CKcvwJ0/edit#)
+* [RTL Support Milestone](https://github.com/oppia/oppia-android/milestone/40)
+* [Guidelines for RTL](https://material.io/design/usability/bidirectionality.html)
diff --git a/wiki/Revert-&-regression-policy.md b/wiki/Revert-&-regression-policy.md
new file mode 100644
index 00000000000..ebaa813b506
--- /dev/null
+++ b/wiki/Revert-&-regression-policy.md
@@ -0,0 +1,35 @@
+When you find yourself in a situation where something seems newly broken in the app, it's important to:
+1. Isolate the problem & [file an issue](https://github.com/oppia/oppia-android/issues/new?assignees=&labels=Type%3A+Improvement%2C+Status%3A+Not+started&template=feature_request.md&title=) for it
+2. Identify the commit which introduced the regression (see below section)
+3. [Revert the PR](https://github.blog/2014-06-24-introducing-the-revert-button/) associated with the commit & send it as a PR for review (the bug you filed in (1) should be marked as fixed by this PR)
+4. Once the revert commit is submitted, reopen any issues fixed by the original PR that was reverted
+
+If you get stuck along the way, please mention in the issue that you filed in (1) that you are unable to locate commit introducing the regression.
+
+## Why do we revert PRs rather than just fix them?
+
+Leaving problems checked in can result in the following two situations:
+1. As the known issues are fixed, others go unnoticed or are discovered later (potentially by users)
+2. The original commit may become non-revertible without manual conflict resolution as more changes are checked in on top of that
+
+For this reason, the team's policy is to quickly revert regressions when they're found. This immediately unblocks team members and provides time for the original PR author to more carefully investigate the underlying issue & potential edge cases.
+
+## How to find the offending commit
+
+1. Always checkout an unchanged, up-to-date copy of develop & verify that the issue is still occurring. Note this commit hash.
+ - If you can't repro the issue, double check that it isn't flaky (try a few times). If you still can't, it's likely the issue has been resolved. Please still file an issue and leave notes for what you tried so that the team can triage accordingly.
+2. Go back to an earlier commit on develop that doesn't repro this issue (if you're unsure, try something at the bottom of [this page](https://github.com/oppia/oppia-android/commits/develop) or earlier, if the regression was introduced a while ago).
+3. Perform a binary search until you find the commit that introduced the issue. Specifically:
+ - Open up a text editor and list all of the commit hashes on develop between the one that you found is reproing the regression and the commit not reproing the issue
+ - Pick the middle hash of the list, check out that commit, and verify whether the issue regresses. If it does, this becomes your new lower bound. If it doesn't, this becomes your new upper bound. Like standard [binary search](https://en.wikipedia.org/wiki/Binary_search_algorithm), the number of commits you're considering is cut in half during each check.
+
+## What do I do if I caused a regression?
+
+If it hasn't been reverted, please follow the steps above to revert. Once your PR is reverted, follow these steps:
+1. Ensure you can repro the issue fully. If you can't, talk to the original author to better understand how to repro the issue.
+2. Make sure you fully understand _why_ your change caused the observed regression(s)--without this step, no progress can actually be made. Remember: fix issues not symptoms. We don't want the observed problem to just go away, we want the underlying root cause to be understood & addressed.
+3. Once you understand the root cause, think through potential edge cases that may break other aspects of the app. It's quite likely that the observed regression was just one of several broken behaviors caused by the underlying issue.
+4. Turn the behaviors from (3) into tests. Verify that these tests fail without a fix, and pass with a fix to the original regression.
+5. Submit a new PR with your original changes + the fixes and tests from (4). Make sure to detail the investigation in this new PR, and reference the original issue that tracked the regression.
+
+Finally, be aware that everyone causes regressions. While we have a lot checks in place to try and avoid regressions from being checked in, they _will_ still happen. Focus on learning from the situation rather focusing on the fact that a regression happened.
\ No newline at end of file
diff --git a/wiki/SLoP-2020.md b/wiki/SLoP-2020.md
new file mode 100644
index 00000000000..f7eab62b416
--- /dev/null
+++ b/wiki/SLoP-2020.md
@@ -0,0 +1,73 @@
+**_Note: For details about the programme have a look at [Oppia-SLoP](https://github.com/oppia/oppia/wiki/SLoP-2020)._**
+
+# Instructions for students
+### How do I get started?
+1. Register as a student on the SLoP [website](https://slop.dscdaiict.in/).
+2. Follow the instructions on the [Getting Started page](https://github.com/oppia/oppia-android/wiki). **Please note, when filling up the contributor survey please indicate that you are taking part in SLoP.**
+3. Once you have submitted the CLA and New Contributor Survey, you will be contacted by your on-boarding mentor (mostly within 24 hours) who will help you make your first contributions to Oppia-Android. But while you wait for the mentor to contact you, feel free to take a look at following resources:
+ - [Oppia-android codebase and architecture](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture)
+ - [Guidance on submitting PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR)
+ - [Oppia-Android testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing)
+ - [Working on UI](https://github.com/oppia/oppia-android/wiki/Working-on-UI)
+ - You can also have a look at the issues with the following labels: ”good first issue”, “good second issue”, “[SLoP 2020](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22SLoP+2020%22+no%3Aassignee)” android to pick an issue that suits your skills and interests.
+4. Your onboarding mentor will suggest starter issues for you to work on. These issues will have score labels of the form “**SLoP-\+ +
+
+
+
Development flow without static analysis
+
+
++ +
+
+
+
Development flow with static analysis
+
+
++ +We can see how a static analysis tool (in this case a linter) simplified the flow and saved the time of both the developer and the reviewer which was wasted earlier in correcting the lint errors. + +This page outlines the static analysis checks implemented in Oppia Android, instructions for how to utilize & maintain them, and instructions for introducing new checks to help enforce best practices as the codebase continues to scale. + +# Static analysis checks in Oppia Android + +## RegexPatternValidation Check + +### Generic regex pattern matching against file names +This check ensures that there are no prohibited file path patterns present in the repository. + +#### Purpose & adding new patterns +This check is needed so as to prevent a particular type of file from being added into a wrong directory. + +For example: If we want to prevent activities from being added into the any directory except testing and app, then we have to add its regex pattern in the [scripts/assets/filename_pattern_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/filename_pattern_validation_checks.textproto) file like this: + +``` +filename_checks { + prohibited_filename_regex: "^((?!(app|testing)).)+/src/main/.+?Activity.kt" + failure_message: "Activities cannot be placed outside the app or testing module" +} +``` + +#### Fixing failures +In general, failures for this check should be fixed by moving the file to the correct directory. In cases where that can’t happen or the check is wrong, please: + +1. Add the file as an exemption in [scripts/assets/filename_pattern_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/filename_pattern_validation_checks.textproto) for the corresponding failing check in
+ +2. If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and the [environment path variable](https://www.java.com/en/download/help/path.html) is also set up correctly. + +3. If you find any error related to Kotlin or Java/Checkstyle while pushing the code, please check [this link](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures). + +4. If you see the error + + ``` + Could not resolve protoc-3.8.0-osx-aarch_64.exe (`com.google.protobuf:protoc:3.8.0`) + ``` + + then please follow the 2nd step mentioned in [this wiki](https://github.com/oppia/oppia-android/wiki/Installing-Oppia-Android#install-oppia-android) for Mac with Apple silicon(M1/M2) chips. + +5. If you see the error + + ``` + Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0. + ``` + + then it's fine to ignore it. The message just appears to be a warning. We don't use Gradle 7.0, so this warning is fine to ignore. + +6. If you see the error + + ``` + Error `Class 'org.oppia.android.app.profile.PinPasswordActivityTest' not found in module 'oppia-android.app'` + ``` + + or `Module not specified` while running Unit Tests, try to downgrade Android Studio to [Bumblebee (Patch 3)](https://developer.android.com/studio/archive). That should resolve this issue. + + +### Bazel issues + +1. No matching toolchains (sdk_toolchain_type) + ``` + ERROR: While resolving toolchains for target //:oppia: no matching toolchains found for types + @bazel_tools//tools/android:sdk_toolchain_type + ERROR: Analysis of target '//:oppia' failed; build aborted: no matching toolchains found for types + @bazel_tools//tools/android:sdk_toolchain_type + INFO: Elapsed time: 12.805s + INFO: 0 processes. + FAILED: Build did NOT complete successfully (13 packages loaded, 51 targets configured) + ``` + [Steps](https://docs.bazel.build/versions/main/tutorial/android-app.html#integrate-with-the-android-sdk) to add ANDROID_HOME environment variable. + +2. If you encounter the following: + + ``` + ERROR: While parsing option --override_repository=android_tools=~/oppia-bazel/android_tools: Repository + override directory must be an absolute path + ``` + + Try to delete the `.bazelrc` file to solve the above error. + +3. **java.lang.ClassNotFoundException: com.android.tools.r8.compatdx.CompatDx** + + If, when building the app binary, you encounter a failure that indicates that the CompatDx file cannot be found, this is likely due to you using a newer version of the Android build tools. You can manually downgrade to an older version of build-tools (particularly 29.0.2). Unfortunately, this can't be done through Android Studio but it can be done over a terminal. Follow the instructions listed [here](https://github.com/oppia/oppia-android/issues/3024#issuecomment-884513455) to downgrade your build tools & then try to build the app again. + + +### Can’t find a particular issue? + +If the error you get is not in the Troubleshooting section above, please create an issue providing all the necessary information and assign it to **@MohitGupta121**. diff --git a/wiki/Updating-Maven-Dependencies.md b/wiki/Updating-Maven-Dependencies.md new file mode 100644 index 00000000000..cb08415d296 --- /dev/null +++ b/wiki/Updating-Maven-Dependencies.md @@ -0,0 +1,140 @@ +All the third-party Maven dependencies used in Oppia-Android along with their versions are mentioned in the [versions.bzl](https://github.com/oppia/oppia-android/blob/develop/third_party/versions.bzl) file that resides in the `third_party` package. To add/delete/update any dependency in `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` or `MAVEN_TEST_DEPENDENCY_VERSIONS` dictionaries, please follow the below steps. + +## Updating `maven_install.json` + +1. Ensure that after making changes in the list of dependencies, the final list is always lexicographically sorted. +2. After updating the dependencies, run the following command. +``` +REPIN=1 bazel run @unpinned_maven//:pin +``` + +## Updating `maven_dependencies.textproto` +You will also need to run the [GenerateMavenDependenciesList.kt](https://github.com/oppia/oppia-android/blob/develop/scripts/src/java/org/oppia/android/scripts/maven/GenerateMavenDependenciesList.kt) script to update the [maven_dependencies.textproto](https://github.com/oppia/oppia-android/blob/develop/scripts/assets/maven_dependencies.textproto) file. This text proto file contains the license links for all the maven third-party dependencies on which Oppia Android depends. Please make sure that before running the script, you have successfully updated [maven_install.json](https://github.com/oppia/oppia-android/blob/develop/third_party/maven_install.json) by following the above-mentioned [guide](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies#updating-maven_installjson). +To run this script, run the following commands. + +``` +cd ~/opensource/oppia-android +``` +The above command ensures that the terminal points to the root directory `oppia-android` repository. Note that if you have configured a different path to the `oppia-android` repository then you should modify the above command accordingly ( `cd ~/
+
+Once you have selected the second icon, you will see a menu on right as below:
+
+
+
+This menu contains details about the screen width, colors, fonts, etc. Also, please note that the screen width in the mocks is **360 px**.
+
+# Gathering information about each view
+You can click on any item in mock to know more details about that view. For example, in image shown below you can see that as the **Administrator Authorization Required** text is selected, the right side menu displays properties of the textview like font, size, color, transparency, etc. Also, the pink color lines/values in mock displays the margin/padding of that item with respect to other items which helps to set margin/padding in android code.
+
+
+
+***
+
+# Important Points
+### Fonts
+Mocks uses Roboto fonts which are similar to sans-serif font in the android code. For example, if mock show font-style as `Roboto, Medium`, then android code for that would be `android:fontFamily="sans-serif-medium"`
+
+### Padding/Margin/View Dimensions
+Mocks might contain padding values like 32.5px or 15px but make sure that you use padding/margin and view dimensions in multiple of 4 in android. So 32.5px will get converted to 32dp and 15px will get converted to 16dp.
+
+### Color Code
+Before introducing any new color code in android check if that color code is already present in the `colors.xml` file or not. Also, 8-character hex code on mocks uses **RGBA** convention and 8-character hex code in android is written as **ARGB** where **A** means alpha/transparency and **R**, **G**, **B** stands for red, green, blue color respectively.
+For example, if mock contains **#33445566** then in this last two characters are for transparency and first siz are for RGB. So in android it will be written as **#66334455**.
+
+### Opacity
+Do not forget to check the opacity value in mocks. For example you find Opacity value `20%` then in that case you can follow two approaches to use that in code:
+1. Use `android:alpha="0.2"` which means 20% opacity in android.
+2. Add two more characters at the start of color code of that view, for example if the item color code was `#999999` with 20% opacity value then the color code for that will be `#33999999`. Check [this](https://gist.github.com/lopspower/03fb1cc0ac9f32ef38f4) link for converting percentage to hex value.
+
+### Blur effect
+Currently, we are using blur effect only over the locked chapters of an exploration. So if the mock item does have a blur value then in that case optimise the android code in such a way that it does look almost like the mock without using the blur effect.
+
+### ImageView Aspect Ratio
+ImageView in android code uses aspect ratio of `4:3` or `16:9` mostly, though in some special cases it can be different. So based on the dimensions in mock, calculate the aspect ratio (we can calculate that by getting the width and height from UI and just calculate the ratio which becomes the aspect ratio) and use it accordingly in the code.
+
+### Bottom Margin in scrollable screens
+Almost in all scrollable screens there is bottom margin, make sure that your mock includes that as per mock.
+
+### TextViews
+In all textviews, make sure that proper `android:maxLines` and `android:ellipsize` values are introduced.
+
+***
+
+# Testing UI
+For UI testing you can do the following things:
+### Manual testing
+For this, you can turn on the `Show Layout Bounds` in your mobile **Settings/Developer Mode**. This helps mainly in identifying the boundaries of items and to check if there is any overlapping between the items.
+
+### Accessibility Scanner
+[Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) can help you identify opportunities to improve your app for users.
+
+Accessibility Scanner scans your screen and provides suggestions to improve the accessibility of your app, based on the following:
+
+* Content labels
+* Touch target size
+* Clickable items
+* Text and image contrast
+
+You can know more about Accessibility in Oppia-Android [here](https://github.com/oppia/oppia-android/wiki/Accessibility-A11y-Guide)
diff --git a/wiki/Writing-design-docs.md b/wiki/Writing-design-docs.md
new file mode 100644
index 00000000000..7207300dc9c
--- /dev/null
+++ b/wiki/Writing-design-docs.md
@@ -0,0 +1,49 @@
+## Instructions
+When writing design docs at Oppia, please use this [design doc template](https://docs.google.com/document/d/1mnz8f708DZIa6BpUyRmbb0gCT6EKO3wIvWa_3rOEOYs/edit#). This will ensure that all the necessary information for the project is documented in a central location, and enable project reviews to be done effectively.
+
+More specifically, here’s how to get started:
+
+1. Make a copy of [this document](https://docs.google.com/document/d/1mnz8f708DZIa6BpUyRmbb0gCT6EKO3wIvWa_3rOEOYs/edit#).
+2. Fill in the sections with details pertaining to your feature/project, following the instructions in the document template.
+3. Proofread what you've written before asking reviewers to take a look.
+
+## How to respond to doc reviews
+
+When you're responding to a reviewer's comments in a doc, we recommend that you treat it like [responding to a code review](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#tips-for-getting-your-pr-merged-after-submission).
+
+More specifically:
+- Feel free to accept (or reject!) suggestions. If you reject a suggestion, that's fine, but say why.
+- In general, treat comments similarly to how you would treat comments in a standard code review. In other words:
+ - Before asking for a follow-up review, make sure to reply to each comment (maybe with "Done") and update the doc as needed, but **don't resolve the comment thread**. Let the reviewer handle that, so that they can keep track of which comments still need to be addressed. Sometimes, more follow-up might be needed when the reviewer looks at the updated version of the doc.
+ - If you have any questions about the reviewer's comments, feel free to ask them for clarification.
+
+## Why we write design documents
+Design documents provide team members with the opportunity to review the future implementation of a project before the code has been fully written. A good design document:
+
+1. Outlines the technical goals of a feature or project that needs to be implemented
+2. Describes the architectural changes in the codebase that the project will include
+3. Describes how the project will be implemented (specific details of what you plan to build, but not the actual code)
+4. Provides a break-down of tasks that will be completed
+5. Provides time estimates for each task & how they will fit within defined milestones
+6. Considers other aspects of the project, including privacy, security, accessibility, and others
+
+## Tips when writing design documents
+
+- Make sure that you understand the high-level goals of the project before going into increasingly lower-level details.
+- Use dependency graphs, flow diagrams, and bullet lists when communicating the high-level architectural changes of the project.
+- When considering additional options that go beyond the initial goals of the project, consider whether these are essential. If they aren't, add them to a "future work" section that could be worked on alongside or after the project (but not as part of the project itself). If it is essential, make sure you factor that into the implementation plan.
+- When breaking down a project, determine all of the tasks that need to be completed for the project. A task is either performing a migration, adding/updating documentation, or creating a PR (each PR should correspond to a single task).
+- When estimating how long a task will take for a project, assume it will take longer than you expect. Engineers often have a tendency of assuming implementation will go perfectly, but they sometimes don't and it's difficult to anticipate the things that could go wrong (e.g. bugs are found, a chosen library won't work, etc.). Suggest always multiplying your time estimates by 1.5x or 2x based on past experience (we call this a "fudge factor"). Consider also going back to old projects and comparing how much time you spent versus your estimates--this can help you figure out a good "fudge factor" to use when providing time estimates for future projects.
+- If you're unsure how to approach the implementation, start by writing a basic hacked-together prototype to help solve specific questions of the implementation that you're unsure of. Look at other similar features for how they're laid out to compare. You should avoid implementing too much of the project in advance: the main purpose of a design document is to get feedback for a project before spending the large amount of time implementing it. For that reason, the document should take much less time than the project to create.
+- If you're unsure about specific parts of the project: call these out as open questions so that other team members can weigh in and provide suggestions or resources that can help you resolve the open questions.
+- If there's something you don't fully understand when writing any part of the design document, ask more questions. Sometimes we make mistakes in how we explain things, and that can lead to projects being taken in a direction we didn't anticipate. Other times, we see contributors make assumptions about one particular technical area (such as testing) and describe something other than what we expect. More questions can help bridge any missing knowledge, and can result in changes to our document templates or project goals.
+- Use related artifacts when coming up with designs. We have lots of past design docs that can provide more detail on the types of things we value as a team, and how to describe those things. Things that follow established patterns are easier to understand since they minimize the amount of context needed to comprehend it. One way to evaluate how much a particular design document or proposal minimizes context is by considering how much easier/harder it is to understand when compared with other documents describing a project of similar complexity.
+
+### Additional tips for large projects
+
+The following tips correspond to projects that span 3+ months:
+- Use milestones to organize tasks & specify expected completion times to communicate expectations with the team
+- When creating milestones, consider the high-level "deliverables" of a project: what can you demonstrate to someone else after a set of tasks are completed that move Oppia toward the finished result of your project?
+- When estimating a milestone, first estimate how much time each task takes and then fit as many tasks as you can within a milestone. Don't change your time estimates based on the milestone (just because something is expected to get done within a certain timeframe doesn't mean it can). If the milestones don't provide enough time to finish the project, that may indicate that the project needs to be rescoped.
+- If the project has multiple developers, ensure tasks and milestones have clear owners assigned to them.
+
diff --git a/wiki/_Footer.md b/wiki/_Footer.md
new file mode 100644
index 00000000000..f3e4b194762
--- /dev/null
+++ b/wiki/_Footer.md
@@ -0,0 +1 @@
+Have an idea for how to improve the wiki? Please help make our documentation better by following our [instructions for contributing to the wiki.](https://github.com/oppia/oppia-android/wiki/Wiki#contributing-to-the-wiki)
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
new file mode 100644
index 00000000000..a3f7c429b7b
--- /dev/null
+++ b/wiki/_Sidebar.md
@@ -0,0 +1,55 @@
+**Core documentation**
+ * [Oppia's mission](https://github.com/oppia/oppia-android/wiki/Our-Mission)
+ * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md)
+ * **[Get involved!](https://github.com/oppia/oppia-android/wiki/home)**
+ * [Coders](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android)
+ * [Teams at Oppia Android](https://github.com/oppia/oppia-android/wiki/Teams-at-oppia-android)
+
+---
+**Developing Oppia**
+ * Contributing to Oppia Android
+ * [Getting Started](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-Android)
+ * [Installing Oppia-Android](https://github.com/oppia/oppia-android/wiki/Installing-Oppia-Android)
+ * [Troubleshooting Installation](https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation)
+ * [How to Get Help ]( https://github.com/oppia/oppia-android/wiki/Get-Help)
+ * [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 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)
+ * [Interpreting CI Results](https://github.com/oppia/oppia-android/wiki/Interpreting-CI-Results)
+ * Testing
+ * [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing)
+ * [End to End Testing Guide](https://github.com/oppia/oppia-android/wiki/End-to-End-Testing-Guide)
+ * [Developing Skills](https://github.com/oppia/oppia-android/wiki/Developing-skills)
+ * [Frequent Errors and Solutions](https://github.com/oppia/oppia-android/wiki/Frequent-Errors-and-Solutions)
+ * [RTL Guidelines](https://github.com/oppia/oppia-android/wiki/RTL-Guidelines)
+ * [Working on UI](https://github.com/oppia/oppia-android/wiki/Working-on-UI)
+ * [Writing Design Docs](https://github.com/oppia/oppia-android/wiki/Writing-design-docs)
+---
+**Developer Reference**
+ * Code style
+ * [Coding style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide)
+ * [Ktlint Guide](https://github.com/oppia/oppia-android/wiki/Ktlint-Guide)
+ * [Static Analysis Checks](https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks)
+ * [Accessibility Guide](https://github.com/oppia/oppia-android/wiki/Accessibility-A11y-Guide)
+ * [Background Processing](https://github.com/oppia/oppia-android/wiki/Background-Processing)
+ * [Kotlin Coroutines](https://github.com/oppia/oppia-android/wiki/Kotlin-Coroutines)
+ * [DataProvider & LiveData](https://github.com/oppia/oppia-android/wiki/DataProvider-&-LiveData)
+ * [PersistentCacheStore & In Memory Blocking Cache](https://github.com/oppia/oppia-android/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache)
+ * [Dark mode](https://github.com/oppia/oppia-android/wiki/Dark-Mode)
+ * [Buf Guide](https://github.com/oppia/oppia-android/wiki/Buf-Guide)
+ * [Firebase Console Guide](https://github.com/oppia/oppia-android/wiki/Firebase-Console-Guide)
+ * [Platform Parameters & Feature Flags](https://github.com/oppia/oppia-android/wiki/Platform-Parameters-&-Feature-Flags)
+ * [Work Manager](https://github.com/oppia/oppia-android/wiki/Work-Manager)
+ * [Dependency Injection](https://github.com/oppia/oppia-android/wiki/Dependency-Injection) with [Dagger](https://github.com/oppia/oppia-android/wiki/Dagger)
+ * [Revert & regression policy](https://github.com/oppia/oppia-android/wiki/Revert-&-regression-policy)
+ * Bazel
+ * [Gradle Bazel Migration Best Practices and FAQ](https://github.com/oppia/oppia-android/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ)
+ * [Updating Maven Dependencies](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies)
+ * [Internationalization](https://github.com/oppia/oppia-android/wiki/Internationalization)
+ * Past Events
+ * Google Summer of Code (note: links are to oppia/oppia): [2021](https://github.com/oppia/oppia/wiki/Google-Summer-of-Code-2021), [2020](https://github.com/oppia/oppia/wiki/Google-Summer-of-Code-2020)
+ * [SLoP 2020](https://github.com/oppia/oppia-android/wiki/SLoP-2020)
\ No newline at end of file