From d1815d132af2d02c03bc33232a003940ad67affd Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sun, 4 Aug 2019 01:53:23 -0700 Subject: [PATCH 001/374] Initial Home page --- Home.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 00000000000..52be265b2c0 --- /dev/null +++ b/Home.md @@ -0,0 +1,10 @@ +Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! + +We're still working on setting up the basics of the Android project, but we are starting to welcome new contributors who'd like to help out. For now, if you're interested in contributing, please follow the following steps: + +1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). +1. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) Make sure to indicate prominently that you are interested in helping out with Android. +1. Check out the oppia-android codebase to become familiar with the project! +1. While the Android project infrastructure is getting set up, consider contributing to the [Oppia web app repository](https://github.com/oppia/oppia) in the meantime -- this is a good way to get familiar with our review process and some of the basic constructs in Oppia. + +(As the project develops, we'll update the above instructions and reach out to active contributors when the Android project is in a sufficiently-good state to allow more participation in its development.) \ No newline at end of file From cc78107f6afa3941ffe9a8ab436f7b33c0f003b9 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 5 Sep 2019 01:12:12 -0700 Subject: [PATCH 002/374] Updated Home (markdown) --- Home.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 112 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 52be265b2c0..18a2e2dedc1 100644 --- a/Home.md +++ b/Home.md @@ -7,4 +7,115 @@ We're still working on setting up the basics of the Android project, but we are 1. Check out the oppia-android codebase to become familiar with the project! 1. While the Android project infrastructure is getting set up, consider contributing to the [Oppia web app repository](https://github.com/oppia/oppia) in the meantime -- this is a good way to get familiar with our review process and some of the basic constructs in Oppia. -(As the project develops, we'll update the above instructions and reach out to active contributors when the Android project is in a sufficiently-good state to allow more participation in its development.) \ No newline at end of file +(As the project develops, we'll update the above instructions and reach out to active contributors when the Android project is in a sufficiently-good state to allow more participation in its development.) + +## Instructions for making a code change + +**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. + +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 **[TBD]** and that it is well-tested. + * Ensure that the code has no lint errors and passes all automated tests by running the presubmit script **[TBD]**. + * 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 **[TBD]**, 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".) + * After a while, check your PR to see whether the Travis checks have passed. If not, follow the instructions at "[If your build fails...](https://github.com/oppia/oppia/wiki/If-your-build-fails)". **[TBD]** + * 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! + +### Notes + +* Our central development branch is `develop`, which should be clean and ready for release at any time. All changes should be done in feature branches based off of `develop`. + +* To find the author of a particular change in a file, run this command: + + ``` + git blame file-name + ``` + The output will show the latest commit SHA, author, date, and time of commit for each line. + + To confine the search of an author between particular lines in a file, you can use: + + ``` + git blame -L 40,60 file-name + ``` + The output will then show lines 40 to 60 of the particular file. + + For more `git blame` options, you can visit the [git blame documentation](https://git-scm.com/docs/git-blame). + +* If your PR includes changing the location of the file, if you simply move the file by cut and paste method, then the git will track it as a new file. So to prevent this, use: + ``` + git mv old_file_path new_file_path + ``` + By using this command git will detect the file as a renamed file. + +## Communication channels + +### Mailing lists + +We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! From 60c57c61b1584b6282c78f1bcccc5089cb039f45 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 5 Sep 2019 15:58:03 -0700 Subject: [PATCH 003/374] Created Coding style guide (markdown) --- Coding-style-guide.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 Coding-style-guide.md diff --git a/Coding-style-guide.md b/Coding-style-guide.md new file mode 100644 index 00000000000..4e1d6cf0d0b --- /dev/null +++ b/Coding-style-guide.md @@ -0,0 +1,31 @@ +Please follow the following style rules when writing code, in order to minimize unnecessary back-and-forth during code review. + +** General +- We follow a hybrid of [JetBrain's Kotlin style guide](https://developer.android.com/kotlin/style-guide) and [Google's Java style guide](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation). +- 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 to help with local debugging) before pushing to GitHub. +- Do not check any build artifacts into GitHub. + +** 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; use e.g. a dimens.xml file instead. In general, avoid using hard-coded strings. + +** Java/Kotlin files +- Separate adjacent functions or blocks of code by a single blank line. +- Order imports alphabetically. Remove unused imports. +- Do not use "magic numbers" in code. Declare constants instead (typically at the module level). + +** build.gradle file +- Arrange lists in alphabetical order unless there's a good reason not to. \ No newline at end of file From a7555514b4d1586ed4487867d5cab6c3a5b93d2e Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 5 Sep 2019 15:58:34 -0700 Subject: [PATCH 004/374] Updated Coding style guide (markdown) --- Coding-style-guide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index 4e1d6cf0d0b..bbadda87b9c 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -1,6 +1,6 @@ Please follow the following style rules when writing code, in order to minimize unnecessary back-and-forth during code review. -** General +## General - We follow a hybrid of [JetBrain's Kotlin style guide](https://developer.android.com/kotlin/style-guide) and [Google's Java style guide](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation). - 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. @@ -11,7 +11,7 @@ Please follow the following style rules when writing code, in order to minimize - Make sure to remove temporary code (e.g. log statements to help with local debugging) before pushing to GitHub. - Do not check any build artifacts into GitHub. -** Comments +## 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. @@ -19,13 +19,13 @@ Please follow the following style rules when writing code, in order to minimize - 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 +## XML files - Do not declare values directly in the XML file; use e.g. a dimens.xml file instead. In general, avoid using hard-coded strings. -** Java/Kotlin files +## Java/Kotlin files - Separate adjacent functions or blocks of code by a single blank line. - Order imports alphabetically. Remove unused imports. - Do not use "magic numbers" in code. Declare constants instead (typically at the module level). -** build.gradle file +## build.gradle file - Arrange lists in alphabetical order unless there's a good reason not to. \ No newline at end of file From 598a07b194cde67a76d854d3fe53b946595a999a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 5 Sep 2019 16:14:55 -0700 Subject: [PATCH 005/374] Updated Home (markdown) --- Home.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Home.md b/Home.md index 18a2e2dedc1..64f52116203 100644 --- a/Home.md +++ b/Home.md @@ -5,9 +5,9 @@ We're still working on setting up the basics of the Android project, but we are 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). 1. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) Make sure to indicate prominently that you are interested in helping out with Android. 1. Check out the oppia-android codebase to become familiar with the project! -1. While the Android project infrastructure is getting set up, consider contributing to the [Oppia web app repository](https://github.com/oppia/oppia) in the meantime -- this is a good way to get familiar with our review process and some of the basic constructs in Oppia. +1. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. +1. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide -(As the project develops, we'll update the above instructions and reach out to active contributors when the Android project is in a sufficiently-good state to allow more participation in its development.) ## Instructions for making a code change From 395f4e7652ca8326dab695f748725bab41330248 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 6 Sep 2019 09:32:42 +0530 Subject: [PATCH 006/374] Developer do use `Toasts` while debugginng and it is worth noting that they should remove that before the final push. --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index bbadda87b9c..02ef2d9f3a7 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -8,7 +8,7 @@ Please follow the following style rules when writing code, in order to minimize - 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 to help with local debugging) before pushing to 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. ## Comments From 326086e02d3893c7575481a0c28de5a01cb8cd8f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 6 Sep 2019 09:34:40 +0530 Subject: [PATCH 007/374] Updated Coding style guide (markdown) --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index 02ef2d9f3a7..d258262c4d3 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -20,7 +20,7 @@ Please follow the following style rules when writing code, in order to minimize - 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; use e.g. a dimens.xml file instead. In general, avoid using hard-coded strings. +- Do not declare values directly in the XML file; use e.g. a dimens.xml file instead. In general, avoid using hard-coded strings. Similar case for colors and strings ## Java/Kotlin files - Separate adjacent functions or blocks of code by a single blank line. From 17c718be3b9865666f51d02737e6bbdde77ff47d Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 6 Sep 2019 09:38:18 +0530 Subject: [PATCH 008/374] Added description in build.gradle file --- Coding-style-guide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index d258262c4d3..9765aa0dc1e 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -28,4 +28,5 @@ Please follow the following style rules when writing code, in order to minimize - Do not use "magic numbers" in code. Declare constants instead (typically at the module level). ## build.gradle file -- Arrange lists in alphabetical order unless there's a good reason not to. \ No newline at end of file +- Arrange lists in alphabetical order unless there's a good reason not to. +- Combine `implementation`, `androidTestImplementation` and `testImplementation` to declare all similar dependencies in one block. \ No newline at end of file From 3ea647743500fd22281e8e4c2b9bcf36b37901dd Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 6 Sep 2019 09:53:42 +0530 Subject: [PATCH 009/374] Introduced Code Formatting section --- Coding-style-guide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index 9765aa0dc1e..6ef02b54ff9 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -11,6 +11,15 @@ Please follow the following style rules when writing code, in order to minimize - 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. + +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. From 264df0c25f7bad27a0f03b6af7ab9ff09f8d1043 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 10 Sep 2019 21:31:43 -0700 Subject: [PATCH 010/374] Updated Coding style guide (markdown) --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index 6ef02b54ff9..b5ef803806e 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -1,7 +1,7 @@ Please follow the following style rules when writing code, in order to minimize unnecessary back-and-forth during code review. ## General -- We follow a hybrid of [JetBrain's Kotlin style guide](https://developer.android.com/kotlin/style-guide) and [Google's Java style guide](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation). +- In general, we follow [Google's Java style guide](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation) (but please look at it from a Kotlin perspective). - 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. From 0a760bd75fca58fd53e6a741e21d303ae667f709 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:37:32 +0530 Subject: [PATCH 011/374] Created Before-After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 Before-After-you-submit-a-PR.md diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md new file mode 100644 index 00000000000..b6a4247cbe4 --- /dev/null +++ b/Before-After-you-submit-a-PR.md @@ -0,0 +1,30 @@ +The following instructions will help you submit a PR effectively and in a much more clear way. +Please going through this document you need knowledge from [Home-Page](https://github.com/oppia/oppia-android/wiki). + +## Important Points + +1. **UI related issue/bug fix**: If your PR introduces changes to the UI/UX part of the android app then make sure you include before and after screenshot. Maybe be include 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 multiple of of 4dp.)_ +2. **Bug fixes**: While fixing an issue which is labelled as **Bug**, make sure to write test cases which actually catches 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. + +##Clarification regarding **Assignees** and **Reviewers** section. +1. **Reviewers**: Add reviewers in this section who should review this PR, there can be multiple reviewers too. Once this section is filled out it would mostly not change throughout the timeline of that PR. +2. **Assignees**: Assignees indicate who all needs to currently check that PR. For the first time while submitting the PR, the **Assignees** and **Reviewers** section will be same. Now, once a reviewer has reviewed the PR, they will de-assign themselves and assign it back to you. And similarly the code-owner will make the request-changes and assign it back to the appropriate reviewer and de-assign themselves. That way this section will keep on changing, always point to people who need to check that PR currently. + +## Checklist before submitting a PR + +Note: This checklist should be embedded in your every PR explanation with appropriate ticks. Please tick the relevant boxes by putting an "x" in them +- [ ] The PR title starts with "Fix #bugnum: ", followed by a short, clear summary of the changes. (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) +- [ ] The PR explanation includes the words "Fixes #bugnum: ..." (or "Fixes part of #bugnum" if the PR only partially fixes an issue). +- [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). +- [ ] The PR does not contain any unnecessary auto-generated code or unnecessary files from Android Studio. +- [ ] The PR is made from a branch that's **not** called "develop". +- [ ] The PR's branch is based on "develop" and **not** on any other branch. +- [ ] The PR is **assigned** to an appropriate reviewer in **Assignees** as well as **Reviewers** section. + + +## After PR submission +1. Keep track of **Assignees** section and reply to comments in the PR itself. +2. PR should not be merged if there are any requested changes. +3. Make sure to resolve all conversations with appropriate comments and replies, **no** conversation should be resolved without having a proper end to the conversation**. +4. Once everything is ready for merge, add a high-level comment regarding merge description and merge the PR. From 146fddc8c8e3e0aafef412e49803879db44e9eff Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:37:46 +0530 Subject: [PATCH 012/374] Updated Before After you submit a PR (markdown) From c9359bd0b1452dbcc3569f7fcc19b66712f99468 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:38:05 +0530 Subject: [PATCH 013/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md index b6a4247cbe4..59d17afbd1a 100644 --- a/Before-After-you-submit-a-PR.md +++ b/Before-After-you-submit-a-PR.md @@ -1,4 +1,4 @@ -The following instructions will help you submit a PR effectively and in a much more clear way. +The following instructions will help you submit a PR effectively and in a much more cleaner way. Please going through this document you need knowledge from [Home-Page](https://github.com/oppia/oppia-android/wiki). ## Important Points From a3a013b226e0cffc62276e29b1bb3b09a761b001 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:38:32 +0530 Subject: [PATCH 014/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md index 59d17afbd1a..319cd75dcf4 100644 --- a/Before-After-you-submit-a-PR.md +++ b/Before-After-you-submit-a-PR.md @@ -1,5 +1,5 @@ The following instructions will help you submit a PR effectively and in a much more cleaner way. -Please going through this document you need knowledge from [Home-Page](https://github.com/oppia/oppia-android/wiki). +Before going through this document make sure you look at [Home-Page](https://github.com/oppia/oppia-android/wiki). ## Important Points From 9682665cb5187ca6bc2690be4c6f13959dc54944 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:38:49 +0530 Subject: [PATCH 015/374] Updated Before After you submit a PR (markdown) From 4218f0f3526685ed4e7c7979d65665563ed74dcd Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:39:01 +0530 Subject: [PATCH 016/374] Updated Before After you submit a PR (markdown) From ce25bdad24a76f9bcabb26a9adf8220c7534df6f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:41:51 +0530 Subject: [PATCH 017/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md index 319cd75dcf4..2137bd73b96 100644 --- a/Before-After-you-submit-a-PR.md +++ b/Before-After-you-submit-a-PR.md @@ -3,13 +3,13 @@ Before going through this document make sure you look at [Home-Page](https://git ## Important Points -1. **UI related issue/bug fix**: If your PR introduces changes to the UI/UX part of the android app then make sure you include before and after screenshot. Maybe be include 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 multiple of of 4dp.)_ +1. **UI related issue/bug fix**: If your PR introduces changes to the UI/UX part of the android app then make sure you include before and after screenshot. Maybe include 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 multiple of of 4dp.)_ 2. **Bug fixes**: While fixing an issue which is labelled as **Bug**, make sure to write test cases which actually catches 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. ##Clarification regarding **Assignees** and **Reviewers** section. 1. **Reviewers**: Add reviewers in this section who should review this PR, there can be multiple reviewers too. Once this section is filled out it would mostly not change throughout the timeline of that PR. -2. **Assignees**: Assignees indicate who all needs to currently check that PR. For the first time while submitting the PR, the **Assignees** and **Reviewers** section will be same. Now, once a reviewer has reviewed the PR, they will de-assign themselves and assign it back to you. And similarly the code-owner will make the request-changes and assign it back to the appropriate reviewer and de-assign themselves. That way this section will keep on changing, always point to people who need to check that PR currently. +2. **Assignees**: Assignees indicate who all needs to currently check that PR. For the first time while submitting the PR, the **Assignees** and **Reviewers** section will be same. Now, once a reviewer has reviewed the PR, they will de-assign themselves and assign it back to the code-owner. And similarly the code-owner will make the requested-changes and assign it back to the appropriate reviewer and de-assign themselves. That way this section will keep on changing and will always point to people who need to check that PR currently. ## Checklist before submitting a PR From cea4fd387e85dd75d325a1a8071c0d8e2a296dac Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 10:42:39 +0530 Subject: [PATCH 018/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md index 2137bd73b96..fada2178e19 100644 --- a/Before-After-you-submit-a-PR.md +++ b/Before-After-you-submit-a-PR.md @@ -19,6 +19,7 @@ Note: This checklist should be embedded in your every PR explanation with approp - [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). - [ ] The PR does not contain any unnecessary auto-generated code or unnecessary files from Android Studio. - [ ] The PR is made from a branch that's **not** called "develop". +- [ ] The PR is made from a branch that is up-to-date with "develop". - [ ] The PR's branch is based on "develop" and **not** on any other branch. - [ ] The PR is **assigned** to an appropriate reviewer in **Assignees** as well as **Reviewers** section. From 12d0a475ea765aeaf6920f62b706c0603c703b13 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 11:45:47 +0530 Subject: [PATCH 019/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md index fada2178e19..12c99b13df9 100644 --- a/Before-After-you-submit-a-PR.md +++ b/Before-After-you-submit-a-PR.md @@ -7,7 +7,7 @@ Before going through this document make sure you look at [Home-Page](https://git 2. **Bug fixes**: While fixing an issue which is labelled as **Bug**, make sure to write test cases which actually catches 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. -##Clarification regarding **Assignees** and **Reviewers** section. +## Clarification regarding **Assignees** and **Reviewers** section. 1. **Reviewers**: Add reviewers in this section who should review this PR, there can be multiple reviewers too. Once this section is filled out it would mostly not change throughout the timeline of that PR. 2. **Assignees**: Assignees indicate who all needs to currently check that PR. For the first time while submitting the PR, the **Assignees** and **Reviewers** section will be same. Now, once a reviewer has reviewed the PR, they will de-assign themselves and assign it back to the code-owner. And similarly the code-owner will make the requested-changes and assign it back to the appropriate reviewer and de-assign themselves. That way this section will keep on changing and will always point to people who need to check that PR currently. From ec6522a4e6dfa8869473617417b3a10c3becab99 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 5 Nov 2019 22:34:40 -0800 Subject: [PATCH 020/374] Updated Before After you submit a PR (markdown) --- Before-After-you-submit-a-PR.md | 31 ----------------------------- Guidance-on-submitting-a-PR.md | 35 +++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 31 deletions(-) delete mode 100644 Before-After-you-submit-a-PR.md create mode 100644 Guidance-on-submitting-a-PR.md diff --git a/Before-After-you-submit-a-PR.md b/Before-After-you-submit-a-PR.md deleted file mode 100644 index 12c99b13df9..00000000000 --- a/Before-After-you-submit-a-PR.md +++ /dev/null @@ -1,31 +0,0 @@ -The following instructions will help you submit a PR effectively and in a much more cleaner way. -Before going through this document make sure you look at [Home-Page](https://github.com/oppia/oppia-android/wiki). - -## Important Points - -1. **UI related issue/bug fix**: If your PR introduces changes to the UI/UX part of the android app then make sure you include before and after screenshot. Maybe include 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 multiple of of 4dp.)_ -2. **Bug fixes**: While fixing an issue which is labelled as **Bug**, make sure to write test cases which actually catches 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. - -## Clarification regarding **Assignees** and **Reviewers** section. -1. **Reviewers**: Add reviewers in this section who should review this PR, there can be multiple reviewers too. Once this section is filled out it would mostly not change throughout the timeline of that PR. -2. **Assignees**: Assignees indicate who all needs to currently check that PR. For the first time while submitting the PR, the **Assignees** and **Reviewers** section will be same. Now, once a reviewer has reviewed the PR, they will de-assign themselves and assign it back to the code-owner. And similarly the code-owner will make the requested-changes and assign it back to the appropriate reviewer and de-assign themselves. That way this section will keep on changing and will always point to people who need to check that PR currently. - -## Checklist before submitting a PR - -Note: This checklist should be embedded in your every PR explanation with appropriate ticks. Please tick the relevant boxes by putting an "x" in them -- [ ] The PR title starts with "Fix #bugnum: ", followed by a short, clear summary of the changes. (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) -- [ ] The PR explanation includes the words "Fixes #bugnum: ..." (or "Fixes part of #bugnum" if the PR only partially fixes an issue). -- [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). -- [ ] The PR does not contain any unnecessary auto-generated code or unnecessary files from Android Studio. -- [ ] The PR is made from a branch that's **not** called "develop". -- [ ] The PR is made from a branch that is up-to-date with "develop". -- [ ] The PR's branch is based on "develop" and **not** on any other branch. -- [ ] The PR is **assigned** to an appropriate reviewer in **Assignees** as well as **Reviewers** section. - - -## After PR submission -1. Keep track of **Assignees** section and reply to comments in the PR itself. -2. PR should not be merged if there are any requested changes. -3. Make sure to resolve all conversations with appropriate comments and replies, **no** conversation should be resolved without having a proper end to the conversation**. -4. Once everything is ready for merge, add a high-level comment regarding merge description and merge the PR. diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md new file mode 100644 index 00000000000..1844ac495d7 --- /dev/null +++ b/Guidance-on-submitting-a-PR.md @@ -0,0 +1,35 @@ +The following instructions will help you submit a PR effectively and in a clean way. Before going through this document, make sure you look at the instructions on the [wiki home page](https://github.com/oppia/oppia-android/wiki). + +## Important Points + +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 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. + +## Clarification regarding **Assignees** and **Reviewers** section. +1. **Reviewers**: In this section, add one or more people who should review this PR. Once this section is filled out, it generally should not change throughout the timeline of the PR. +2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More 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. + +## Checklist before submitting a PR + +Note: This checklist should be embedded in your every PR explanation with appropriate ticks. Please tick the relevant boxes by putting an "x" in them +- [ ] The PR title starts with "Fix #bugnum: ", followed by a short, clear summary of the changes. (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) +- [ ] The PR explanation includes the words "Fixes #bugnum: ..." (or "Fixes part of #bugnum" if the PR only partially fixes an issue). +- [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). +- [ ] The PR does not contain any unnecessary auto-generated code or unnecessary files from Android Studio. +- [ ] The PR is made from a branch that's **not** called "develop". +- [ ] The PR is made from a branch that is up-to-date with "develop". +- [ ] The PR's branch is based on "develop" and **not** on any other branch. +- [ ] The PR is **assigned** to an appropriate reviewer in **Assignees** as well as **Reviewers** section. + + +## Tips for getting your PR merged after submission +1. Keep track of **Assignees** section and reply to comments in the PR itself. +2. PRs should not be merged if there are any requested changes. +3. Make sure to resolve all conversations with appropriate comments and replies. **No** conversation should be resolved without having a proper end to the conversation. +4. Once everything is ready for 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 here too. \ No newline at end of file From 10fbbecafeb744c0a864d084270b83c4dc3386e8 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 6 Nov 2019 13:16:19 +0530 Subject: [PATCH 021/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 1844ac495d7..0d2b236c948 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -4,7 +4,7 @@ The following instructions will help you submit a PR effectively and in a clean 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 of 4dp.)_ + - 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. From e8619c7bb2e0a5d3dc1ae17d52dc48c95e79c4f9 Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Fri, 8 Nov 2019 16:00:30 -0800 Subject: [PATCH 022/374] Initial check in for the screenshots wiki entry --- Creating-a-screenshot.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 Creating-a-screenshot.md diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot.md new file mode 100644 index 00000000000..a5c375f67c7 --- /dev/null +++ b/Creating-a-screenshot.md @@ -0,0 +1,10 @@ +There are three ways in which we can easily take screenshots and get it on the computer + +## Using Android Studio on an Emulator +If you are running Oppia on an emulator running on Android Studio, you can directly take a screenshot from the sidebar of the emulator. + +The default location for the screenshot would be on Desktop. + +## Using Android Studio on a local device + +## Using an ADB command \ No newline at end of file From 2279f9546651c21ac31d24ad036ab5fdb91e3813 Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Fri, 8 Nov 2019 16:17:53 -0800 Subject: [PATCH 023/374] Added details to the screenshot wiki --- Creating-a-screenshot.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot.md index a5c375f67c7..6a9567a0054 100644 --- a/Creating-a-screenshot.md +++ b/Creating-a-screenshot.md @@ -2,9 +2,23 @@ There are three ways in which we can easily take screenshots and get it on the c ## Using Android Studio on an Emulator If you are running Oppia on an emulator running on Android Studio, you can directly take a screenshot from the sidebar of the emulator. - +

+Screen Shot 2019-11-08 at 3 58 05 PM +

The default location for the screenshot would be on Desktop. ## Using Android Studio on a local device +If you are running Oppia on a local Android device, you can take a screenshot using the Logcat window of Android Studio. +* Go to Tools > Windows > Logcat. You will see the Logcat window open up at the bottom. +* On the left hand side there is a column of icons, hover on the expand icon at the bottom and you will see a camera icon: . +* Click on that and Android studio will take a screenshot and open up a Screenshot Editor +* You can then save your image from the Screenshot Editor. + +For more details, see the [Android documentation](https://developer.android.com/studio/debug/am-screenshot) -## Using an ADB command \ No newline at end of file +## 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 From 04c7df1dab8123f7401d20bd66a25b7e86184380 Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Fri, 8 Nov 2019 16:18:50 -0800 Subject: [PATCH 024/374] Updated Creating a screenshot (markdown) --- ...reenshot.md => Creating-a-screenshot-from-an-Android-device.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Creating-a-screenshot.md => Creating-a-screenshot-from-an-Android-device.md (100%) diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot-from-an-Android-device.md similarity index 100% rename from Creating-a-screenshot.md rename to Creating-a-screenshot-from-an-Android-device.md From c6b1dedf60f30f86ccd715011e7ab26d7cd27dc0 Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Fri, 8 Nov 2019 16:19:27 -0800 Subject: [PATCH 025/374] Updated Creating a screenshot from an Android device (markdown) --- ...reenshot-from-an-Android-device.md => Creating-a-screenshot.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Creating-a-screenshot-from-an-Android-device.md => Creating-a-screenshot.md (100%) diff --git a/Creating-a-screenshot-from-an-Android-device.md b/Creating-a-screenshot.md similarity index 100% rename from Creating-a-screenshot-from-an-Android-device.md rename to Creating-a-screenshot.md From 3e83ffcffeb5b32e697894f299e416a55a8bd395 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 9 Dec 2019 15:29:35 +0530 Subject: [PATCH 026/374] Updated Creating a screenshot (markdown) --- Creating-a-screenshot.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot.md index 6a9567a0054..fad0a85619b 100644 --- a/Creating-a-screenshot.md +++ b/Creating-a-screenshot.md @@ -5,7 +5,15 @@ If you are running Oppia on an emulator running on Android Studio, you can direc

Screen Shot 2019-11-08 at 3 58 05 PM

-The default location for the screenshot would be on Desktop. + +Also, you can create a video/gif file from emulator by following these steps: +1. Click on three dots present at the bottom on emulator side bar. +2. In the extended menu click on `Record and Playback`. +3. Click on `Start Recording`. This will only record the emulator screen. +4. Once finished, click on `Stop Recording`. +5. You can save this file in `WEBM` or `GIF` format. + +The default location for the screenshot, video and gif would be on Desktop. ## Using Android Studio on a local device If you are running Oppia on a local Android device, you can take a screenshot using the Logcat window of Android Studio. From 40d150afe1968090f7df196ee68f409cf97a5122 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 23 Dec 2019 11:24:55 +0530 Subject: [PATCH 027/374] Created Fork and Clone Oppia-Android (markdown) --- Fork-and-Clone-Oppia-Android.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 Fork-and-Clone-Oppia-Android.md diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md new file mode 100644 index 00000000000..0d4e3c7b49c --- /dev/null +++ b/Fork-and-Clone-Oppia-Android.md @@ -0,0 +1,17 @@ +For a detailed explanation for fork and clone, you can go to github help page + +Make sure you are in `opensource/` folder. Now follow the steps below : + +* Click on the `fork` button. It is placed on the top right corner opposite to repository name `oppia/oppia-android`. +![Oppia-Android Fork](https://user-images.githubusercontent.com/9396084/71338568-663f1400-2576-11ea-9893-8d616f65368f.png) + +* You can now see Oppia-Android under your repositories. It will be marked as forked from `oppia/oppia-android` +![Oppia-Android Origin Repo](https://user-images.githubusercontent.com/9396084/71338640-b0c09080-2576-11ea-8dc3-3d4a0ef59877.png) + +* Let's clone this repository to your local computer using git clone `https://github.com/USERNAME/oppia-android.git` + +* We will configure remote repositories to keep your local repository, forked repository and main oppia-android repository in sync. You can check your current remote repositories by typing `git remote -v`. + +* Type the following to add oppia as upstream `git remote add upstream https://github.com/oppia/oppia-android`. + +* And we are done! You can access main oppia repository using `git fetch upstream` and access your forked version using `git fetch origin`. From 353027cb0c2ac846c55b8bb7c0f5b78b578897e9 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 24 Dec 2019 11:43:40 +0530 Subject: [PATCH 028/374] Updated Fork and Clone Oppia Android (markdown) --- Fork-and-Clone-Oppia-Android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index 0d4e3c7b49c..9767ef06ed9 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -1,4 +1,4 @@ -For a detailed explanation for fork and clone, you can go to github help page +For a detailed explanation for fork and clone, you can go to [github help page](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#platform-linux) Make sure you are in `opensource/` folder. Now follow the steps below : From c72883d9ce8a2c178a6187e910677f712e4c6fda Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 23 Dec 2019 22:17:56 -0800 Subject: [PATCH 029/374] Updated Fork and Clone Oppia Android (markdown) --- Fork-and-Clone-Oppia-Android.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index 9767ef06ed9..d01b3109c2a 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -1,17 +1,21 @@ -For a detailed explanation for fork and clone, you can go to [github help page](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#platform-linux) +_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)._ -Make sure you are in `opensource/` folder. Now follow the steps below : +## How to fork and clone the Oppia Android repository -* Click on the `fork` button. It is placed on the top right corner opposite to repository name `oppia/oppia-android`. +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): ![Oppia-Android Fork](https://user-images.githubusercontent.com/9396084/71338568-663f1400-2576-11ea-9893-8d616f65368f.png) -* You can now see Oppia-Android under your repositories. It will be marked as forked from `oppia/oppia-android` +3. You can now see Oppia-Android under your repositories. It will be marked as forked from `oppia/oppia-android` ![Oppia-Android Origin Repo](https://user-images.githubusercontent.com/9396084/71338640-b0c09080-2576-11ea-8dc3-3d4a0ef59877.png) -* Let's clone this repository to your local computer using git clone `https://github.com/USERNAME/oppia-android.git` +4. Clone this repository to your local computer by running `git clone https://github.com/USERNAME/oppia-android.git` in a terminal. -* We will configure remote repositories to keep your local repository, forked repository and main oppia-android repository in sync. You can check your current remote repositories by typing `git remote -v`. +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) -* Type the following to add oppia as upstream `git remote add upstream https://github.com/oppia/oppia-android`. +## Updating your local repository -* And we are done! You can access main oppia repository using `git fetch upstream` and access your forked version using `git fetch origin`. +You can download the latest contents of the main Oppia Android repository using `git fetch upstream`, and you can also access your forked version using `git fetch origin`. (Usually, you'll want to do the former.) From f7a54b224ddd6dc16072211202a1fe9553b5be3b Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 23 Dec 2019 22:26:54 -0800 Subject: [PATCH 030/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 64f52116203..ef2acfdb67c 100644 --- a/Home.md +++ b/Home.md @@ -3,7 +3,7 @@ Thanks for your interest in contributing to the Oppia Android project, and makin We're still working on setting up the basics of the Android project, but we are starting to welcome new contributors who'd like to help out. For now, if you're interested in contributing, please follow the following steps: 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). -1. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) Make sure to indicate prominently that you are interested in helping out with Android. +1. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** 1. Check out the oppia-android codebase to become familiar with the project! 1. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. 1. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide From 467b4d9d776ab43bc2cabfd1c4afc9675a5afba0 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 24 Dec 2019 12:15:21 +0530 Subject: [PATCH 031/374] Updated Fork and Clone Oppia Android (markdown) --- Fork-and-Clone-Oppia-Android.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index d01b3109c2a..2992d2c0293 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -5,9 +5,9 @@ _For a detailed explanation of the fork-and-clone process, please see this [GitH 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): -![Oppia-Android Fork](https://user-images.githubusercontent.com/9396084/71338568-663f1400-2576-11ea-9893-8d616f65368f.png) +![Oppia-Android Fork](https://user-images.githubusercontent.com/9396084/71397560-eed7b600-2643-11ea-854c-ea1d57df497d.png) -3. You can now see Oppia-Android under your repositories. It will be marked as forked from `oppia/oppia-android` +3. You can now see Oppia-Android under [your repositories](https://github.com/). It will be marked as forked from `oppia/oppia-android` ![Oppia-Android Origin Repo](https://user-images.githubusercontent.com/9396084/71338640-b0c09080-2576-11ea-8dc3-3d4a0ef59877.png) 4. Clone this repository to your local computer by running `git clone https://github.com/USERNAME/oppia-android.git` in a terminal. From cfc974dc95ca2e136a6a7320bef404293cc75920 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 24 Dec 2019 12:26:08 +0530 Subject: [PATCH 032/374] The installation section was earlier on README.md file, but has been shifted to this to keep everything organised, as suggested by @Sean. --- Home.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/Home.md b/Home.md index ef2acfdb67c..8abb78ca78f 100644 --- a/Home.md +++ b/Home.md @@ -3,11 +3,18 @@ Thanks for your interest in contributing to the Oppia Android project, and makin We're still working on setting up the basics of the Android project, but we are starting to welcome new contributors who'd like to help out. For now, if you're interested in contributing, please follow the following steps: 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). -1. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** -1. Check out the oppia-android codebase to become familiar with the project! -1. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. -1. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide +2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** +3. Check out the oppia-android codebase to become familiar with the project! +4. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. +5. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide +## Installation + +Please follow these steps for initial setup of the project 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`. + +2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. ## Instructions for making a code change From e53edfa02acfed1e46f790af047ea2d8f6397c20 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Jan 2020 15:31:12 +0530 Subject: [PATCH 033/374] Created Overview of the Oppia-Android codebase and architecture (markdown) --- ...Oppia-Android-codebase-and-architecture.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 Overview-of-the-Oppia-Android-codebase-and-architecture.md diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md new file mode 100644 index 00000000000..a05a598a58c --- /dev/null +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -0,0 +1,40 @@ +Oppia-Android is built with Kotlin and XML using Android Studio. The Oppia app will follow a layered architecture combining parts of [MVP](https://medium.com/upday-devs/android-architecture-patterns-part-2-model-view-presenter-8a6faaae14a5) (Model-View-Presenter) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel) + +# Directory Structure +Screenshot 2020-01-13 at 1 21 25 PM + +The Oppia project follows a standard Gradle project layout with five modules: +### 1. app: +* This module contains all the activities and fragments. +* This module contains view, view model, and presenter layers. +* Contains Robolectric test cases and integration/hermetic end-to-end tests using Espresso. + +### 2. data: +* Custom data delivery mechanism, and custom persistence layers that are lifecycle-safe. +* This module contains unit tested with a combination of JUnit and Robolectric. + +### 3. domain: +* Contains the business logic of the application. +* This is a Java/Kotlin library without Android components. +* This contains both frontend controller and business service logic. +* This library will be unit tested using raw JUnit tests. + +### 4. model: +* Contains all `protos` used in the app. +* This library contains no tests since it only contains data definitions. + +### 5. utility: +* This is a Java/Kotlin module without Android dependencies. +* This module contains utilities that all other modules may depend on. +* This module contains JUnit test cases. + +# App Architecture +Screenshot 2020-01-13 at 12 54 00 PM + +The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Model-View-ViewModel) where different Android components fulfill requirements for each piece: +* 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. +* Android Views are classic views: they perform no logic and are simply responsible for displaying data from view models (via Android data-binding). +* View models are Android ViewModels that listen for and expose changes from the model layer. +* The model layer is defined by a combination of protobuf and Kotlin data objects that are provided from the controller layer using LiveData; managers are responsible for maintaining state in this layer. +* The controller layer interacts with the database and network; it provides data via a custom data source mechanism. +* Android Activities should only perform high-level fragment transaction logic, and are responsible for initializing dagger components and performing routing. From efd31afa4b30154e2f66d9446ff0a6d8d9c5a95c Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Jan 2020 17:05:37 +0530 Subject: [PATCH 034/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- ...Oppia-Android-codebase-and-architecture.md | 41 ++++++++++++++++++- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index a05a598a58c..1b06350fa88 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -3,21 +3,49 @@ Oppia-Android is built with Kotlin and XML using Android Studio. The Oppia app w # Directory Structure Screenshot 2020-01-13 at 1 21 25 PM -The Oppia project follows a standard Gradle project layout with five modules: +The Oppia project follows a standard Gradle project layout with five modules and the subdirectories contains files specific to a particular feature or purpose. ### 1. app: * This module contains all the activities and fragments. * This module contains view, view model, and presenter layers. * Contains Robolectric test cases and integration/hermetic end-to-end tests using Espresso. +* **app/activity** - Basic Dagger code for activity implementation. +* **app/application** - Dagger code for application with different module declaration. +* **app/customview** - Any custom UI item used by the application is stored in this directory. +* **app/databinding** - Different BindingAdapters which can be used in any layout file. +* **app/fragment** - Basic Dagger code for fragment implementation. +* **app/home** - Home screen related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/mydownloads** -My Downloads screen related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/parser** - Various classes which parses one data type to another like String to Fraction. +* **app/player** - Directory containing everything related to exploration player like audio, state, etc. +* **app/profile** - Profile screen and subscreen related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/recyclerview** - helper classes for recyclerview which is used in various activities and fragments. +* **app/settings** - Settings screen and subscreen related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/splash** - Code related to Splash screen in app. +* **app/story** - Story screen related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/testing** - All dummy test activities and fragments needed to test the functionalities correctly which also helps in writing test cases. +* **app/topic** - Topic and its four tabs related fragments, activities, viewmodels, adapters, presenters and interfaces. +* **app/utility** - Any code which can be used centrally like date-time getter-setter, keyboard controller, etc are written in this subdirectory. +* **app/view** - Basic Dagger code for view implementation. +* **app/viewmodel** - Basic Dagger code for viewmodel implementation. ### 2. data: -* Custom data delivery mechanism, and custom persistence layers that are lifecycle-safe. +* Module which provides data to the application via fetching data from the Oppia-Backend or by fetching data from offline store PersistanceCacheStore. * This module contains unit tested with a combination of JUnit and Robolectric. +* **data/backends** - Contain APIs and models which are needed to make a data request from Oppia-Backend and convert that response to appropriate models. +* **data/persistence** - The offline store information is saved in this subdirectory using `[PersistanceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b)` ### 3. domain: * Contains the business logic of the application. * This is a Java/Kotlin library without Android components. * This contains both frontend controller and business service logic. * This library will be unit tested using raw JUnit tests. +* **domain/audio** - Business logic for playing audio in app. +* **domain/classify** - Classes responsible for classifying user answers to a specific outcome based on Oppia's interaction rule engine. +* **domain/exploration** - Controller for loading explorations, managing states and playing with exploration. +* **domain/profile** - Controller for retrieving, adding, updating, and deleting profiles. +* **domain/question** - Controller for retrieving a set of questions in Practice Mode of app. +* **domain/topic** - Controller for retrieving all aspects of a topic and topic-list along with progress. +* **domain/util** - Utility with different extension functions and classes to create models from JSON like `createStateFromJson`. ### 4. model: * Contains all `protos` used in the app. @@ -27,6 +55,15 @@ The Oppia project follows a standard Gradle project layout with five modules: * This is a Java/Kotlin module without Android dependencies. * This module contains utilities that all other modules may depend on. * This module contains JUnit test cases. +* **utility/caching** - A generic repository for access local APK asset files, and downloading remote binary files. This repository aims to centralize caching management of external asset files to simplify downstream code, and allow assets to be retrieved quickly and synchronously. +* **utility/data** - Contains various classes which helps fetching locally stored data in an effective way in domain layer. +* **utility/extensions** - This simply contains the extensions for Android classes like extension for LiveData. +* **utility/gcsresource** - Provides the default name of the GCS Resource bucket. +* **utility/logging** - Oppia-Android does not use `[Log](https://developer.android.com/reference/android/util/Log)` instead it has its custom Logger which is a wrapper class for Android Logcat and file logging. All logs in this project should use `Logger` instead of `Log` anywhere in the project. +* **utility/networking** - Utility to get the current connection status of the device. +* **utility/parser** - Contains parser for rich-text like HtmlParser and UrlParser which makes sure that the rich-text from Oppia Backend is parsed correctly to make to display it in android app. +* **utility/profile** - Utility to manage creation and deletion of directories. +* **utility/threading** - Utility which contains thread-safe enqueue and dequeue methods. # App Architecture Screenshot 2020-01-13 at 12 54 00 PM From 7f4142160cee7342b149496722060c3ee39a5b7c Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Jan 2020 17:08:10 +0530 Subject: [PATCH 035/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- Overview-of-the-Oppia-Android-codebase-and-architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index 1b06350fa88..d0804e9931b 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -32,7 +32,7 @@ The Oppia project follows a standard Gradle project layout with five modules and * Module which provides data to the application via fetching data from the Oppia-Backend or by fetching data from offline store PersistanceCacheStore. * This module contains unit tested with a combination of JUnit and Robolectric. * **data/backends** - Contain APIs and models which are needed to make a data request from Oppia-Backend and convert that response to appropriate models. -* **data/persistence** - The offline store information is saved in this subdirectory using `[PersistanceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b)` +* **data/persistence** - The offline store information is saved in this subdirectory using [PersistanceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b) ### 3. domain: * Contains the business logic of the application. @@ -59,7 +59,7 @@ The Oppia project follows a standard Gradle project layout with five modules and * **utility/data** - Contains various classes which helps fetching locally stored data in an effective way in domain layer. * **utility/extensions** - This simply contains the extensions for Android classes like extension for LiveData. * **utility/gcsresource** - Provides the default name of the GCS Resource bucket. -* **utility/logging** - Oppia-Android does not use `[Log](https://developer.android.com/reference/android/util/Log)` instead it has its custom Logger which is a wrapper class for Android Logcat and file logging. All logs in this project should use `Logger` instead of `Log` anywhere in the project. +* **utility/logging** - Oppia-Android does not use [Log](https://developer.android.com/reference/android/util/Log) instead it has its custom Logger which is a wrapper class for Android Logcat and file logging. All logs in this project should use `Logger` instead of `Log` anywhere in the project. * **utility/networking** - Utility to get the current connection status of the device. * **utility/parser** - Contains parser for rich-text like HtmlParser and UrlParser which makes sure that the rich-text from Oppia Backend is parsed correctly to make to display it in android app. * **utility/profile** - Utility to manage creation and deletion of directories. From 570b8846888f6dd60a80c71bff3f0a13d2db7d29 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Jan 2020 19:41:12 +0530 Subject: [PATCH 036/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- ...the-Oppia-Android-codebase-and-architecture.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index d0804e9931b..54dbcbe3b98 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -75,3 +75,18 @@ The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Mode * The model layer is defined by a combination of protobuf and Kotlin data objects that are provided from the controller layer using LiveData; managers are responsible for maintaining state in this layer. * The controller layer interacts with the database and network; it provides data via a custom data source mechanism. * Android Activities should only perform high-level fragment transaction logic, and are responsible for initializing dagger components and performing routing. + +# Codebase Walkthrough +Here are some useful examples on how to traverse the codebase (Note: These are not real tasks/features): +## Example +**Task**: Add a button in Info Tab which will open an already existing activity, for example, SplashActivity. +**Walkthrough**: +1. Now as per the subdirectory details mentioned above we know that the `app/topic` contains all the files related to Topic and its tabs. +2. Inside it there is another directory which is `app/topic/info` which should contain information related to already existing TopicInfo Tab. In this we see 3 files, `TopicInfoFragment`, `TopicInfoFragmentPresenter` and `TopicInfoViewModel`. +3. Now let's first open `TopicInfoFragment` which extends a `InjectableFragment`, in this we can see that it just calls the `TopicInfoFragmentPresenter`. +4. Inside `TopicInfoFragmentPresenter` we can see that an xml layout is getting inflated 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)`. From this we know that the corresponding xml file name is `topic_info_fragment.xml`. +5. Now open `topic_info_fragment.xml` file and create a button inside that. +6. Button click is handled via data binding a function (`clickDummyButton`) to the xml. That function will be created in the `TopicInfoViewModel`. From **App Architecture** section we know that the ViewModel does not handle the logic and the presenter is responsible for the logic part. +7. So we will create another function (`goToSplashActivity`) inside the `TopicInfoFragmentPresenter` and now we will call this function inside `clickDummyButton` which was present in `TopicInfoViewModel`. + +This way the entire task is complete with all the code blocks in correct files. From 38eea2001ac443a6bf3b9d7ae121296001cde91d Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 13 Jan 2020 06:31:23 -0800 Subject: [PATCH 037/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- ...Oppia-Android-codebase-and-architecture.md | 120 +++++++++--------- 1 file changed, 60 insertions(+), 60 deletions(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index 54dbcbe3b98..2186cbe61a8 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -1,69 +1,65 @@ -Oppia-Android is built with Kotlin and XML using Android Studio. The Oppia app will follow a layered architecture combining parts of [MVP](https://medium.com/upday-devs/android-architecture-patterns-part-2-model-view-presenter-8a6faaae14a5) (Model-View-Presenter) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel) +Oppia-Android is built using Kotlin and XML (via 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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). # Directory Structure Screenshot 2020-01-13 at 1 21 25 PM -The Oppia project follows a standard Gradle project layout with five modules and the subdirectories contains files specific to a particular feature or purpose. +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. -* This module contains view, view model, and presenter layers. -* Contains Robolectric test cases and integration/hermetic end-to-end tests using Espresso. +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/hermetic end-to-end tests using Espresso. Here are the contents of its subdirectories: + * **app/activity** - Basic Dagger code for activity implementation. -* **app/application** - Dagger code for application with different module declaration. -* **app/customview** - Any custom UI item used by the application is stored in this directory. +* **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/home** - Home screen related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/mydownloads** -My Downloads screen related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/parser** - Various classes which parses one data type to another like String to Fraction. -* **app/player** - Directory containing everything related to exploration player like audio, state, etc. -* **app/profile** - Profile screen and subscreen related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/recyclerview** - helper classes for recyclerview which is used in various activities and fragments. -* **app/settings** - Settings screen and subscreen related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/splash** - Code related to Splash screen in app. -* **app/story** - Story screen related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/testing** - All dummy test activities and fragments needed to test the functionalities correctly which also helps in writing test cases. -* **app/topic** - Topic and its four tabs related fragments, activities, viewmodels, adapters, presenters and interfaces. -* **app/utility** - Any code which can be used centrally like date-time getter-setter, keyboard controller, etc are written in this subdirectory. -* **app/view** - Basic Dagger code for view implementation. -* **app/viewmodel** - Basic Dagger code for viewmodel implementation. +* **app/home** - Fragments, activities, viewmodels, adapters, presenters and interfaces associated with the home screen. +* **app/mydownloads** - Fragments, activities, viewmodels, adapters, presenters and interfaces associated with the "My Downloads" screen. +* **app/parser** - Various classes which parse strings to other data types (e.g. String to Fraction). +* **app/player** - Everything related to the exploration player (e.g. audio, state, etc.). +* **app/profile** - Fragments, activities, viewmodels, adapters, presenters and interfaces for the profile screen and related subscreens. +* **app/recyclerview** - Helper classes for RecyclerView, which is used in various activities and fragments. +* **app/settings** - Fragments, activities, viewmodels, adapters, presenters and interfaces related to the Settings screen and related subscreens. +* **app/splash** - Code related to the app's Splash screen. +* **app/story** - Fragments, activities, viewmodels, 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, viewmodels, adapters, presenters and interfaces related to the Topic screen and its four tabs. +* **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. ### 2. data: -* Module which provides data to the application via fetching data from the Oppia-Backend or by fetching data from offline store PersistanceCacheStore. -* This module contains unit tested with a combination of JUnit and Robolectric. -* **data/backends** - Contain APIs and models which are needed to make a data request from Oppia-Backend and convert that response to appropriate models. -* **data/persistence** - The offline store information is saved in this subdirectory using [PersistanceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b) +This module provides data to the application by fetching data from the Oppia backend, or by fetching data from an offline PersistenceCacheStore. This module is unit-tested with a combination of JUnit and Robolectric. Here are the contents of its subdirectories: + +* **data/backends** - APIs and models which are needed to make a data request to the Oppia backend, and convert that response to appropriate models. +* **data/persistence** - Information pertaining to the offline store is saved here using [PersistenceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b) ### 3. domain: -* Contains the business logic of the application. -* This is a Java/Kotlin library without Android components. -* This contains both frontend controller and business service logic. -* This library will be unit tested using raw JUnit tests. -* **domain/audio** - Business logic for playing audio in app. +This module contains the business logic of the application, including both frontend controller and business service logic. It is a Java/Kotlin library without Android components, and it is unit-tested using raw JUnit tests. Its subdirectories are as follows: + +* **domain/audio** - Business logic for playing audio in the app. * **domain/classify** - Classes responsible for classifying user answers to a specific outcome based on Oppia's interaction rule engine. * **domain/exploration** - Controller for loading explorations, managing states and playing with exploration. * **domain/profile** - Controller for retrieving, adding, updating, and deleting profiles. -* **domain/question** - Controller for retrieving a set of questions in Practice Mode of app. -* **domain/topic** - Controller for retrieving all aspects of a topic and topic-list along with progress. -* **domain/util** - Utility with different extension functions and classes to create models from JSON like `createStateFromJson`. +* **domain/question** - Controller for retrieving a set of questions in the app's Practice Mode. +* **domain/topic** - Controller for retrieving all aspects of a topic and topic list, together with the user's progress. +* **domain/util** - Utility with different extension functions and classes to create models from JSON-encoded strings (e.g. `createStateFromJson`). -### 4. model: -* Contains all `protos` used in the app. -* This library contains no tests since it only contains data definitions. +### 4. model: +This library contains all `protos` used in the app. It only contains data definitions, so no tests are included. ### 5. utility: -* This is a Java/Kotlin module without Android dependencies. -* This module contains utilities that all other modules may depend on. -* This module contains JUnit test cases. +This is a Java/Kotlin module without Android dependencies. It contains utilities that all other modules may depend on. It also includes JUnit test cases. Its subdirectories are as follows: + * **utility/caching** - A generic repository for access local APK asset files, and downloading remote binary files. This repository aims to centralize caching management of external asset files to simplify downstream code, and allow assets to be retrieved quickly and synchronously. -* **utility/data** - Contains various classes which helps fetching locally stored data in an effective way in domain layer. -* **utility/extensions** - This simply contains the extensions for Android classes like extension for LiveData. +* **utility/data** - Various classes which help with effectively fetching locally-stored data in the domain layer. +* **utility/extensions** - Extensions for Android classes (e.g. LiveData). * **utility/gcsresource** - Provides the default name of the GCS Resource bucket. -* **utility/logging** - Oppia-Android does not use [Log](https://developer.android.com/reference/android/util/Log) instead it has its custom Logger which is a wrapper class for Android Logcat and file logging. All logs in this project should use `Logger` instead of `Log` anywhere in the project. -* **utility/networking** - Utility to get the current connection status of the device. -* **utility/parser** - Contains parser for rich-text like HtmlParser and UrlParser which makes sure that the rich-text from Oppia Backend is parsed correctly to make to display it in android app. -* **utility/profile** - Utility to manage creation and deletion of directories. -* **utility/threading** - Utility which contains thread-safe enqueue and dequeue methods. +* **utility/logging** - Oppia-Android does not use [Log](https://developer.android.com/reference/android/util/Log). Instead, it has a custom Logger, which is a wrapper class for Android Logcat and file logging. **All** logs in this project should use `Logger` instead of `Log`. +* **utility/networking** - A utility to get the current connection status of the device. +* **utility/parser** - Rich-text parsers (e.g. HtmlParser, UrlParser) which ensure that the rich-text from the Oppia backend is parsed correctly in order to display it properly in the Android app. +* **utility/profile** - A utility to manage creation and deletion of directories. +* **utility/threading** - A utility which contains thread-safe enqueue and dequeue methods. # App Architecture Screenshot 2020-01-13 at 12 54 00 PM @@ -72,21 +68,25 @@ The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Mode * 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. * Android Views are classic views: they perform no logic and are simply responsible for displaying data from view models (via Android data-binding). * View models are Android ViewModels that listen for and expose changes from the model layer. -* The model layer is defined by a combination of protobuf and Kotlin data objects that are provided from the controller layer using LiveData; managers are responsible for maintaining state in this layer. -* The controller layer interacts with the database and network; it provides data via a custom data source mechanism. -* Android Activities should only perform high-level fragment transaction logic, and are responsible for initializing dagger components and performing routing. +* The model layer is defined by a combination of protobuf and Kotlin data objects that are provided from the controller layer using LiveData. Managers are responsible for maintaining state in this layer. +* The controller layer interacts with the database and network. It provides data via a custom data source mechanism. +* Android Activities should only perform high-level fragment transaction logic, and are responsible for initializing Dagger components and performing routing. # Codebase Walkthrough -Here are some useful examples on how to traverse the codebase (Note: These are not real tasks/features): + +Here are some examples for how to traverse the codebase. (Note that the examples below are not real tasks/features, and should not be implemented.) + ## Example -**Task**: Add a button in Info Tab which will open an already existing activity, for example, SplashActivity. + +**Task**: Add a button in Info Tab which will open an already existing activity (e.g. SplashActivity). + **Walkthrough**: -1. Now as per the subdirectory details mentioned above we know that the `app/topic` contains all the files related to Topic and its tabs. -2. Inside it there is another directory which is `app/topic/info` which should contain information related to already existing TopicInfo Tab. In this we see 3 files, `TopicInfoFragment`, `TopicInfoFragmentPresenter` and `TopicInfoViewModel`. -3. Now let's first open `TopicInfoFragment` which extends a `InjectableFragment`, in this we can see that it just calls the `TopicInfoFragmentPresenter`. -4. Inside `TopicInfoFragmentPresenter` we can see that an xml layout is getting inflated 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)`. From this we know that the corresponding xml file name is `topic_info_fragment.xml`. -5. Now open `topic_info_fragment.xml` file and create a button inside that. -6. Button click is handled via data binding a function (`clickDummyButton`) to the xml. That function will be created in the `TopicInfoViewModel`. From **App Architecture** section we know that the ViewModel does not handle the logic and the presenter is responsible for the logic part. -7. So we will create another function (`goToSplashActivity`) inside the `TopicInfoFragmentPresenter` and now we will call this function inside `clickDummyButton` which was present in `TopicInfoViewModel`. - -This way the entire task is complete with all the code blocks in correct files. +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 a `InjectableFragment`, and we can see that it just calls the `TopicInfoFragmentPresenter`. +4. Inside `TopicInfoFragmentPresenter`, we can see that an XML layout is getting inflated 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)`. From this, we know that the corresponding xml file name is `topic_info_fragment.xml`. +5. Now, open `topic_info_fragment.xml` file and create a button inside it. +6. The button click can be handled by data-binding a function (`clickDummyButton`) to the XML. That function will be created in the `TopicInfoViewModel`. From the **App Architecture** section, we know that the ViewModel does not handle the logic, and the presenter is responsible for the logic part. +7. So, 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 the completion of the entire task, with all the code blocks in the correct files. \ No newline at end of file From f6181c9461b1ccdf50b4afda850075ec7f7cc783 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 13 Jan 2020 06:31:38 -0800 Subject: [PATCH 038/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- Overview-of-the-Oppia-Android-codebase-and-architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index 2186cbe61a8..f9bb7b2026f 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -1,4 +1,4 @@ -Oppia-Android is built using Kotlin and XML (via 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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). +The Oppia-Android codebase is built using Kotlin and XML (via 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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). # Directory Structure Screenshot 2020-01-13 at 1 21 25 PM From 7da86d8746909008645089aeee17c4deca31c102 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 13 Jan 2020 06:31:59 -0800 Subject: [PATCH 039/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- Overview-of-the-Oppia-Android-codebase-and-architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index f9bb7b2026f..c1885e4e408 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -1,4 +1,4 @@ -The Oppia-Android codebase is built using Kotlin and XML (via 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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). +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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). # Directory Structure Screenshot 2020-01-13 at 1 21 25 PM From 64416448142c8e95a0148abedce1a12d5f7704ab Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 14 Jan 2020 12:24:29 +0530 Subject: [PATCH 040/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- ...-Oppia-Android-codebase-and-architecture.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index c1885e4e408..fc803bb59a5 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -1,4 +1,4 @@ -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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). +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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). # Directory Structure Screenshot 2020-01-13 at 1 21 25 PM @@ -8,22 +8,22 @@ The Oppia project follows a standard Gradle project layout with five modules. Ea ### 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/hermetic end-to-end tests using Espresso. Here are the contents of its subdirectories: -* **app/activity** - Basic Dagger code for activity implementation. +* **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/home** - Fragments, activities, viewmodels, adapters, presenters and interfaces associated with the home screen. -* **app/mydownloads** - Fragments, activities, viewmodels, adapters, presenters and interfaces associated with the "My Downloads" screen. +* **app/home** - Fragments, activities, view models, adapters, presenters and interfaces associated with the home screen. +* **app/mydownloads** - Fragments, activities, view models, adapters, presenters and interfaces associated with the "My Downloads" screen. * **app/parser** - Various classes which parse strings to other data types (e.g. String to Fraction). * **app/player** - Everything related to the exploration player (e.g. audio, state, etc.). -* **app/profile** - Fragments, activities, viewmodels, adapters, presenters and interfaces for the profile screen and related subscreens. +* **app/profile** - Fragments, activities, view models, adapters, presenters and interfaces for the profile screen and related subscreens. * **app/recyclerview** - Helper classes for RecyclerView, which is used in various activities and fragments. -* **app/settings** - Fragments, activities, viewmodels, adapters, presenters and interfaces related to the Settings screen and related subscreens. +* **app/settings** - Fragments, activities, view models, adapters, presenters and interfaces related to the Settings screen and related subscreens. * **app/splash** - Code related to the app's Splash screen. -* **app/story** - Fragments, activities, viewmodels, adapters, presenters and interfaces related to the Story screen. +* **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, viewmodels, adapters, presenters and interfaces related to the Topic screen and its four tabs. +* **app/topic** - Fragments, activities, view models, adapters, presenters and interfaces related to the Topic screen and its four tabs. * **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. @@ -74,7 +74,7 @@ The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Mode # Codebase Walkthrough -Here are some examples for how to traverse the codebase. (Note that the examples below are not real tasks/features, and should not be implemented.) +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 From f03a90bf34a6f45db468351d3a943f7c2f1ace65 Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Thu, 16 Jan 2020 15:01:25 +0530 Subject: [PATCH 041/374] Rough page ... Please suggest screens to be removed/added --- Android-Studio-UI-based-Github-workflow.md | 80 ++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 Android-Studio-UI-based-Github-workflow.md diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md new file mode 100644 index 00000000000..0e5edb0e06d --- /dev/null +++ b/Android-Studio-UI-based-Github-workflow.md @@ -0,0 +1,80 @@ +## How to clone the Oppia Android repository from Android Studio. +Go to _https://github.com/oppia/oppia-android_ +Clone or download(Copy the link)> +1 + +Now ,go to _Android Studio>File>New> Project from Version Control >Git_ + + +2 +Login to gitHub with your credentials. +Paste the URL>_Clone_ +Wait for a few minutes that gradle build completes. + +4 + +## Create New Branch + +Now your android studio project is ready to start your work. +Right side bottom of your android studio screen you will find you cloned branch name "develop". +develop>New Branch>fill your new branch name>OK + +10 +12 + + +If you want to go back to develop or any branch/check out any branch you may righ click and find options for that +11 +Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select files >Add +5 +New files will be shown in green color and modified file name will be displayed in blue color in project window(select file/folder/directory Ctrl+Alt|+A to manually version an unversioned file/files) +8 + +click on the green tick symbol to commit your files +9 +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 before commiting. + +13 +## Push Changes +Now we need to Push the code changes to local branch(orgin) and upstream(remote) +Right click app>Git>Repository >Push +15 +Your new branch need to be added to both local(orgin) and upstream(remote). +Once you push a branch to git you wont be able to rename it so be sure about the naming before pushing. +16 +## Pull changes from Develop + +Once you push your new branch to develop you are ready to merge new changes from remote(upstream).Make sure your new branch's base branch is develop and the new branch is up-to-date with changes in develop. +17 +If you are not getting the below options of selecting upstream.Please login to your git hub account +18 +For login Go to Android Studio>Preference>Version Control >Github>Add Account +19 + +Fill all the credentials asked and login. +Now Click VCS>Git>Fetch +20 +21 +Now select the upstream to pull changes from develop +Select upstream in pull changes dialog>select branch develop> Pull +you will find all the new changes pulled from develop in version control update info. +23 +## Merge and resolve conflict + +select remote branch as upstream>select develop branch>select your branch name> pull +25 +27 + +You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. +select file>merge +28 + +Now the local changes ,Result , and remote changes are displayed should merge these changes. +29 +Once all conflicts are resolved you will get a popup like this "All changes have been processed" +Now click on Apply +30 +Now you will find the merged file changes locally in your android studio code. +31 + From db64b95fad41f38b76fb36a9b9075292c990ec5f Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Thu, 16 Jan 2020 15:02:26 +0530 Subject: [PATCH 042/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 0e5edb0e06d..89db151dc75 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -36,7 +36,9 @@ Now click on commit.(This will save the reference of your changes for pushing to If there are errors or warnings review the code change and fix before commiting. 13 + ## Push Changes + Now we need to Push the code changes to local branch(orgin) and upstream(remote) Right click app>Git>Repository >Push 15 From 6ee3ac84b41c9e64f6decca60e34c3e5f29d48ca Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 16 Jan 2020 15:22:49 +0530 Subject: [PATCH 043/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 24 +++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 89db151dc75..0ed2ae20a0c 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -1,29 +1,29 @@ -## How to clone the Oppia Android repository from Android Studio. -Go to _https://github.com/oppia/oppia-android_ -Clone or download(Copy the link)> +# Clone Oppia-Android using Android Studio +Go to https://github.com/oppia/oppia-android +Click on **Clone or download** and copy the link. 1 -Now ,go to _Android Studio>File>New> Project from Version Control >Git_ +Now, go to **Android Studio** -> **File** -> **New** -> **Project from Version Control** -> **Git** 2 -Login to gitHub with your credentials. -Paste the URL>_Clone_ -Wait for a few minutes that gradle build completes. +Login to GitHub with your credentials. +Paste the **URL** and click on **Clone** button. +Wait for a few minutes until gradle build completes. 4 -## Create New Branch +# Create New Branch -Now your android studio project is ready to start your work. -Right side bottom of your android studio screen you will find you cloned branch name "develop". -develop>New Branch>fill your new branch name>OK +Now the local copy of Oppia-Android is ready on your Android Studio +Right side bottom of your android studio screen you will find a **develop** branch. +Click on **develop** -> **New Branch** -> _Enter your new branch name_ -> **OK** 10 12 -If you want to go back to develop or any branch/check out any branch you may righ click and find options for that +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 11 Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select files >Add 5 From 60f723c5c902725bdb891b5d6db17ec6691cf5bb Mon Sep 17 00:00:00 2001 From: Veena Date: Thu, 16 Jan 2020 16:14:20 +0530 Subject: [PATCH 044/374] Created Overview of the Oppia Android Testing (markdown) --- Overview-of-the-Oppia-Android-Testing.md | 207 +++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 Overview-of-the-Oppia-Android-Testing.md diff --git a/Overview-of-the-Oppia-Android-Testing.md b/Overview-of-the-Oppia-Android-Testing.md new file mode 100644 index 00000000000..9a60ba20b53 --- /dev/null +++ b/Overview-of-the-Oppia-Android-Testing.md @@ -0,0 +1,207 @@ +# 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) + +# Guidelines for testing +1. Test names should read like a sentence, and be consistent with other nearby test names to facilitate easily coming up with new tests. Test names should include three things: +Consider using a format similar to the following for naming test functions: + + `___` + + +where , and are replaced with appropriate descriptions in snake_case. 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` + +2. 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 method: + + assertEquals(expected, actual); + In the assertEquals method, you can easily get confused and interchange the actual and expected argument position. + + assertThat(actual, is(equalTo(expected))); +The first thing to notice is that it’s the other way around (actual first, expected second), which is the biggest hurdle to get over. 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: + + assertThat(actual, is(not(equalTo(expected)))); +What’s cool about the “not” method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent short-hand version of the above equality methods which saves on typing: +Hence assertThat should be the preffered method over the other methods. + +3. Guidelines for 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 a private method/function, test it through 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). + +## Roboelectric +With Robolectric you can write tests like this: + + @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(), equalTo("Testing Android Rocks!")); + } + } + + +## Espresso +Use Espresso to write concise, beautiful, and reliable Android UI tests. +Example JUnit4 test using Rules: + + @RunWith(AndroidJUnit4::class) + class SplashActivityTest { + + @get:Rule + var activityTestRule: ActivityTestRule = ActivityTestRule( + SplashActivity::class.java, /* initialTouchMode= */ true, /* launchActivity= */ false) + + @Before + fun setUp() { + Intents.init() + } + @Test + fun testSplashActivity_initialOpen_routesToHomeActivity() { + activityTestRule.launchActivity(null) + intended(hasComponent(ProfileActivity::class.java.name)) + } + @After + fun tearDown() { + Intents.release() + } + } + + +How to use View Matchers, View Actions and View Assertions in Espresso? +Espresso has many ViewMatcher options which are very effective in uniquely locate UI element. You can also combine and create a combination of View Matchers to find element uniquely. + +The View Matcher is written like onView(ViewMatcher) which are commonly used. There are two types of actions that can be performed on View those are - + +onView(ViewMatcher).perform(ViewAction) + +onView(ViewMatcher).check(ViewAssertion) + + // frequently used matchers + // using resource id + onView(withId(R.id.my_view)) + // using visible text + onView(withText("Done")) + // using content description + onView(withContentDescription("profile")); + //using Hint Text + onView(withHint("Sample_text")) + //return TextView with links + onView(hasLinks()) + + //UI property matchers are mostly used in combination + // withId(R.id.my_view) is a ViewMatcher + // click() is a ViewAction + // matches(isDisplayed()) is a ViewAssertion + onView(withId(R.id.my_view)) + .perform(click()) + .check(matches(isDisplayed())) + + onView(withId(R.id.profile_edit_name)).check(matches(withText("Sean"))) + + onView(withId(R.id.test_number_input_interaction_view)) + .check(matches(isDisplayed())).check(matches(withText("9"))) + + onView(withText(R.string.home_activity_back_dialog_exit)).perform(click()) + onView(withId(R.id.story_chapter_list)).perform( + scrollToPosition(1)) + onView(withId(R.id.story_chapter_list)).check(hasItemCount(4)) + + +A test case can never be called complete without assertions and hence it is important to know View Assertions provided by Espresso to complete your test cases. + +### Using `isCompletelyDisplayed` and `isDisplayed` + +* **isCompletelyDisplayed** : Returns a matcher which only accepts a view whose height and width fit perfectly within the currently displayed region of this view. +* There exist views (such as ScrollViews) whose height and width are larger then the physical device screen by design. Such views will _never_ be completely displayed. +* **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. +* Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater then the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed + +### Using `swipeLeft/Right` and using `scrollToPage`: +* Espresso release contains new left and right swiping actions: swipeLeft() and swipeRight(). They both are really useful when you'd like to swipe between activity fragments, tab layouts or any other UI elements. +* At times, GeneralSwipeAction can become unreliable because of its calculation varies on different screen size or density, so it may not be suitable for ViewPager. Instead, we can use to scroll with ViewPagerActions + + @Test + fun testOnboardingFragment_checkSlide1Description_isCorrect() { + launch(OnboardingActivity::class.java).use { + onView(withId(R.id.onboarding_slide_view_pager)).perform(scrollToPage(1)) + onView( + allOf( + withId(R.id.slide_description_text_view), + isCompletelyDisplayed() + ) + ).check(matches(withText(R.string.onboarding_slide_1_description))) + } + + +## Testing RecyclerViews at Specific Positions + +### RecyclerViewActions +The espresso-contrib library provides a RecyclerViewActions class that offers a way to click on a specific position in a RecyclerView (see instructions on configuring espress-contrib). + +### RecyclerViewMatcher +Using the RecyclerViewMatcher under package ‘org.oppia.app.recyclerview’, you can perform actions on an item at a specific position in a RecyclerView, and also check that some content is contained within a descendant of a specific item. + + + @Test + fun testHomeActivity_recyclerViewIndex3_clickTopicSummary_opensTopicActivity() { + launch(HomeActivity::class.java).use { + onView(atPosition(R.id.home_recycler_view, 3)).perform(click()) + intended(hasComponent(TopicActivity::class.java.name)) + intended(hasExtra(TopicActivity.TOPIC_ACTIVITY_TOPIC_ID_ARGUMENT_KEY, TEST_TOPIC_ID_0)) + } + } + + @Test + fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { + launch(HomeActivity::class.java).use { + onView(withId(R.id.home_recycler_view)).perform(scrollToPosition(1)) + onView(atPositionOnView(R.id.home_recycler_view, 1, R.id.story_name_text_view)).check( + matches( + withText(containsString("Matthew Goes to the Bakery")) + ) + ) + } + } + + +## Integrate Espresso Idling Resources in the app to build flexible UI tests + +Espresso test might execute some checks while the app is doing some operations in the background threads, due to which the test may have no much content to interact with, therefore it throws an exception. + +We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like SystemClock.sleep(period) or Thread.sleep(period) . Yet with this approach, we might end up having inflexible and slow tests + +In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, CountingIdlingResource is one of the easiest to understand resource that comes bundled within the framework. \ No newline at end of file From 6aba611b8d9a77f3f334d7d7342df3766f733194 Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Thu, 16 Jan 2020 22:42:43 +0530 Subject: [PATCH 045/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 0ed2ae20a0c..2a94da5b0b3 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -3,11 +3,12 @@ Go to https://github.com/oppia/oppia-android Click on **Clone or download** and copy the link. 1 -Now, go to **Android Studio** -> **File** -> **New** -> **Project from Version Control** -> **Git** +Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**> **Git** 2 Login to GitHub with your credentials. + Paste the **URL** and click on **Clone** button. Wait for a few minutes until gradle build completes. @@ -17,7 +18,7 @@ Wait for a few minutes until gradle build completes. Now the local copy of Oppia-Android is ready on your Android Studio Right side bottom of your android studio screen you will find a **develop** branch. -Click on **develop** -> **New Branch** -> _Enter your new branch name_ -> **OK** +Click on **develop** > **New Branch** > _Enter your new branch name_ > **OK** 10 12 @@ -25,7 +26,7 @@ Click on **develop** -> **New Branch** -> _Enter your new branch name_ -> **OK** 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 11 -Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select files >Add +Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select **files >Add** 5 New files will be shown in green color and modified file name will be displayed in blue color in project window(select file/folder/directory Ctrl+Alt|+A to manually version an unversioned file/files) 8 @@ -40,7 +41,7 @@ If there are errors or warnings review the code change and fix before commiting. ## Push Changes Now we need to Push the code changes to local branch(orgin) and upstream(remote) -Right click app>Git>Repository >Push +Right click **app > Git > Repository > Push** 15 Your new branch need to be added to both local(orgin) and upstream(remote). Once you push a branch to git you wont be able to rename it so be sure about the naming before pushing. @@ -51,25 +52,25 @@ Once you push your new branch to develop you are ready to merge new changes from 17 If you are not getting the below options of selecting upstream.Please login to your git hub account 18 -For login Go to Android Studio>Preference>Version Control >Github>Add Account +For login Go to **Android Studio>Preference>Version Control >Github>Add Account** 19 Fill all the credentials asked and login. -Now Click VCS>Git>Fetch +Now Click **VCS>Git>Fetch** 20 21 Now select the upstream to pull changes from develop -Select upstream in pull changes dialog>select branch develop> Pull +Select upstream in pull changes **dialog>select branch develop>Pull** you will find all the new changes pulled from develop in version control update info. 23 ## Merge and resolve conflict -select remote branch as upstream>select develop branch>select your branch name> pull +select remote branch as **upstream>select develop branch>select your branch name> pull** 25 27 You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. -select file>merge +select **file>merge** 28 Now the local changes ,Result , and remote changes are displayed should merge these changes. From 99a7d88da602cb757f0994d5a51718ef2d167965 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 17 Jan 2020 11:27:31 +0530 Subject: [PATCH 046/374] Updated Overview of the Oppia Android Testing (markdown) --- ...oid-Testing.md => Oppia-Android-Testing.md | 47 ++++++++++--------- 1 file changed, 25 insertions(+), 22 deletions(-) rename Overview-of-the-Oppia-Android-Testing.md => Oppia-Android-Testing.md (76%) diff --git a/Overview-of-the-Oppia-Android-Testing.md b/Oppia-Android-Testing.md similarity index 76% rename from Overview-of-the-Oppia-Android-Testing.md rename to Oppia-Android-Testing.md index 9a60ba20b53..5c7bd611b09 100644 --- a/Overview-of-the-Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -10,41 +10,44 @@ In Oppia we are considering: * 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) # Guidelines for testing -1. Test names should read like a sentence, and be consistent with other nearby test names to facilitate easily coming up with new tests. Test names should include three things: +## 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. Test names should include three things: 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. -where , and are replaced with appropriate descriptions in snake_case. 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` +For Example: +* `testProfileChooserFragment_initializeProfiles_checkProfilesAreShown` +* `testSplashActivity_initialOpen_routesToHomeActivity` -2. Use: +## assertThat() vs. assertEqual(), assertTrue() / assertFalse() +Use `assertThat()` instead of `assertEqual()`, `assertTrue()` / `assertFalse()` -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()`: -The first benefit is that assertThat is more readable than the other assert methods. For example take a look at the following assertEquals method: + assertEquals(expected, actual) - assertEquals(expected, actual); - In the assertEquals method, you can easily get confused and interchange the actual and expected argument position. +In the `assertEquals()`, you can easily get confused and interchange the actual and expected argument position. - assertThat(actual, is(equalTo(expected))); -The first thing to notice is that it’s the other way around (actual first, expected second), which is the biggest hurdle to get over. 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: + assertThat(actual, is(equalTo(expected))) - 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: +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: - assertThat(actual, is(not(equalTo(expected)))); -What’s cool about the “not” method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent short-hand version of the above equality methods which saves on typing: -Hence assertThat should be the preffered method over the other methods. - -3. Guidelines for testing private methods/functions: + 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()`: + assertThat(actual, is(not(equalTo(expected)))) + +What’s cool about the **not** method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent shorthand version of the above equality methods which saves on typing: +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 a private method/function, test it through 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). +* If you want to test code execution of a private method/function, test it through 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 From fa9cb326de71d3168e1f641fc067e1c9316b8c9d Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 17 Jan 2020 11:28:03 +0530 Subject: [PATCH 047/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 5c7bd611b09..2ec243cd33b 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -150,7 +150,7 @@ A test case can never be called complete without assertions and hence it is impo * **isCompletelyDisplayed** : Returns a matcher which only accepts a view whose height and width fit perfectly within the currently displayed region of this view. * There exist views (such as ScrollViews) whose height and width are larger then the physical device screen by design. Such views will _never_ be completely displayed. -* **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. +* **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. * Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater then the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed ### Using `swipeLeft/Right` and using `scrollToPage`: From 7bb0a75f585ce79cc8e3bb028a1b7db0f8ea55ce Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 11:58:49 +0530 Subject: [PATCH 048/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 262 ++++++++++++++++++++------------------- 1 file changed, 136 insertions(+), 126 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 2ec243cd33b..4d68199bc2c 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -26,20 +26,24 @@ For Example: 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()`: - - assertEquals(expected, actual) +``` +assertEquals(expected, actual) +``` In the `assertEquals()`, you can easily get confused and interchange the actual and expected argument position. - - assertThat(actual, is(equalTo(expected))) +``` +assertThat(actual, is(equalTo(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)) +``` +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()`: - - assertThat(actual, is(not(equalTo(expected)))) +``` +assertThat(actual, is(not(equalTo(expected)))) +``` What’s cool about the **not** method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent shorthand version of the above equality methods which saves on typing: Hence assertThat should be the preferred method over the other methods. @@ -52,57 +56,61 @@ Tests should only be written to verify the behaviour of public methods/functions # 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 +* 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). ## Roboelectric -With Robolectric you can write tests like this: - - @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(), equalTo("Testing Android Rocks!")); - } - } - - +With [Roboelectric](https://github.com/robolectric/robolectric) you can write tests like this: +``` +@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(), equalTo("Testing Android Rocks!")); + } +} +``` ## Espresso -Use Espresso to write concise, beautiful, and reliable Android UI tests. +Use [Espresso](https://developer.android.com/training/testing/espresso) to write concise, beautiful, and reliable Android UI tests. Example JUnit4 test using Rules: - - @RunWith(AndroidJUnit4::class) - class SplashActivityTest { - - @get:Rule - var activityTestRule: ActivityTestRule = ActivityTestRule( - SplashActivity::class.java, /* initialTouchMode= */ true, /* launchActivity= */ false) - - @Before - fun setUp() { - Intents.init() - } - @Test - fun testSplashActivity_initialOpen_routesToHomeActivity() { - activityTestRule.launchActivity(null) - intended(hasComponent(ProfileActivity::class.java.name)) - } - @After - fun tearDown() { - Intents.release() - } - } - +``` +@RunWith(AndroidJUnit4::class) +class SplashActivityTest { + + // The initialTouchMode enables the activity to be launched in touch mode. The launchActivity is + // disabled to launch Activity explicitly within each test case. + @get:Rule + var activityTestRule: ActivityTestRule = ActivityTestRule( + SplashActivity::class.java, /* initialTouchMode= */ true, /* launchActivity= */ false + ) + + @Before + fun setUp() { + Intents.init() + } + + @Test + fun testSplashActivity_initialOpen_routesToHomeActivity() { + activityTestRule.launchActivity(null) + intended(hasComponent(ProfileActivity::class.java.name)) + } + + @After + fun tearDown() { + Intents.release() + } +} +``` How to use View Matchers, View Actions and View Assertions in Espresso? Espresso has many ViewMatcher options which are very effective in uniquely locate UI element. You can also combine and create a combination of View Matchers to find element uniquely. @@ -112,94 +120,96 @@ The View Matcher is written like onView(ViewMatcher) which are commonly used. Th onView(ViewMatcher).perform(ViewAction) onView(ViewMatcher).check(ViewAssertion) - - // frequently used matchers - // using resource id - onView(withId(R.id.my_view)) - // using visible text - onView(withText("Done")) - // using content description - onView(withContentDescription("profile")); - //using Hint Text - onView(withHint("Sample_text")) - //return TextView with links - onView(hasLinks()) - - //UI property matchers are mostly used in combination - // withId(R.id.my_view) is a ViewMatcher - // click() is a ViewAction - // matches(isDisplayed()) is a ViewAssertion - onView(withId(R.id.my_view)) - .perform(click()) - .check(matches(isDisplayed())) - - onView(withId(R.id.profile_edit_name)).check(matches(withText("Sean"))) - - onView(withId(R.id.test_number_input_interaction_view)) - .check(matches(isDisplayed())).check(matches(withText("9"))) - - onView(withText(R.string.home_activity_back_dialog_exit)).perform(click()) - onView(withId(R.id.story_chapter_list)).perform( - scrollToPosition(1)) - onView(withId(R.id.story_chapter_list)).check(hasItemCount(4)) - +``` +// frequently used matchers +// using resource id +onView(withId(R.id.my_view)) +// using visible text +onView(withText("Done")) +// using content description +onView(withContentDescription("profile")); +//using Hint Text +onView(withHint("Sample_text")) +//return TextView with links +onView(hasLinks()) + +//UI property matchers are mostly used in combination +// withId(R.id.my_view) is a ViewMatcher +// click() is a ViewAction +// matches(isDisplayed()) is a ViewAssertion +onView(withId(R.id.my_view)) + .perform(click()) + .check(matches(isDisplayed())) + +onView(withId(R.id.profile_edit_name)).check(matches(withText("Sean"))) + +onView(withId(R.id.test_number_input_interaction_view)).check(matches(isDisplayed())).check(matches(withText("9"))) + +onView(withText(R.string.home_activity_back_dialog_exit)).perform(click()) +onView(withId(R.id.story_chapter_list)).perform( + scrollToPosition( + 1 + ) +) +onView(withId(R.id.story_chapter_list)).check(hasItemCount(4)) +``` A test case can never be called complete without assertions and hence it is important to know View Assertions provided by Espresso to complete your test cases. -### Using `isCompletelyDisplayed` and `isDisplayed` +### Using isCompletelyDisplayed and isDisplayed * **isCompletelyDisplayed** : Returns a matcher which only accepts a view whose height and width fit perfectly within the currently displayed region of this view. * There exist views (such as ScrollViews) whose height and width are larger then the physical device screen by design. Such views will _never_ be completely displayed. * **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. * Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater then the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed -### Using `swipeLeft/Right` and using `scrollToPage`: +### Using swipeLeft/Right and using `scrollToPage`: * Espresso release contains new left and right swiping actions: swipeLeft() and swipeRight(). They both are really useful when you'd like to swipe between activity fragments, tab layouts or any other UI elements. -* At times, GeneralSwipeAction can become unreliable because of its calculation varies on different screen size or density, so it may not be suitable for ViewPager. Instead, we can use to scroll with ViewPagerActions - - @Test - fun testOnboardingFragment_checkSlide1Description_isCorrect() { - launch(OnboardingActivity::class.java).use { - onView(withId(R.id.onboarding_slide_view_pager)).perform(scrollToPage(1)) - onView( - allOf( - withId(R.id.slide_description_text_view), - isCompletelyDisplayed() - ) - ).check(matches(withText(R.string.onboarding_slide_1_description))) - } - - +* At times, GeneralSwipeAction can become unreliable because of its calculation varies on different screen size or density, so it may not be suitable for ViewPager. Instead, we can use to scroll with [ViewPagerActions](https://developer.android.com/reference/android/support/test/espresso/contrib/ViewPagerActions) + +``` +@Test +fun testOnboardingFragment_checkSlide1Description_isCorrect() { + launch(OnboardingActivity::class.java).use { + onView(withId(R.id.onboarding_slide_view_pager)).perform(scrollToPage(1)) + onView( + allOf( + withId(R.id.slide_description_text_view), + isCompletelyDisplayed() + ) + ).check(matches(withText(R.string.onboarding_slide_1_description))) +} +``` ## Testing RecyclerViews at Specific Positions ### RecyclerViewActions -The espresso-contrib library provides a RecyclerViewActions class that offers a way to click on a specific position in a RecyclerView (see instructions on configuring espress-contrib). +The espresso-contrib library provides a [RecyclerViewActions](https://github.com/shauvik/espresso/blob/master/espresso/contrib/src/main/java/android/support/test/espresso/contrib/RecyclerViewActions.java) class that offers a way to click on a specific position in a RecyclerView (see [instructions on configuring espress-contrib](https://guides.codepath.com/android/UI-Testing-with-Espresso#interacting-with-a-recyclerview)). ### RecyclerViewMatcher Using the RecyclerViewMatcher under package ‘org.oppia.app.recyclerview’, you can perform actions on an item at a specific position in a RecyclerView, and also check that some content is contained within a descendant of a specific item. - - - @Test - fun testHomeActivity_recyclerViewIndex3_clickTopicSummary_opensTopicActivity() { - launch(HomeActivity::class.java).use { - onView(atPosition(R.id.home_recycler_view, 3)).perform(click()) - intended(hasComponent(TopicActivity::class.java.name)) - intended(hasExtra(TopicActivity.TOPIC_ACTIVITY_TOPIC_ID_ARGUMENT_KEY, TEST_TOPIC_ID_0)) - } - } - - @Test - fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { - launch(HomeActivity::class.java).use { - onView(withId(R.id.home_recycler_view)).perform(scrollToPosition(1)) - onView(atPositionOnView(R.id.home_recycler_view, 1, R.id.story_name_text_view)).check( - matches( - withText(containsString("Matthew Goes to the Bakery")) - ) - ) - } - } - +``` +@Test +fun testHomeActivity_recyclerViewIndex3_clickTopicSummary_opensTopicActivity() { + launch(HomeActivity::class.java).use { + + onView(atPosition(R.id.home_recycler_view, 3)).perform(click()) + intended(hasComponent(TopicActivity::class.java.name)) + intended(hasExtra(TopicActivity.TOPIC_ACTIVITY_TOPIC_ID_ARGUMENT_KEY, TEST_TOPIC_ID_0)) + } +} + +@Test +fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { + launch(HomeActivity::class.java).use { + onView(withId(R.id.home_recycler_view)).perform(scrollToPosition(1)) + onView(atPositionOnView(R.id.home_recycler_view, 1, R.id.story_name_text_view)).check( + matches( + withText(containsString("Matthew Goes to the Bakery")) + ) + ) + } +} +``` ## Integrate Espresso Idling Resources in the app to build flexible UI tests @@ -207,4 +217,4 @@ Espresso test might execute some checks while the app is doing some operations i We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like SystemClock.sleep(period) or Thread.sleep(period) . Yet with this approach, we might end up having inflexible and slow tests -In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, CountingIdlingResource is one of the easiest to understand resource that comes bundled within the framework. \ No newline at end of file +In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, [CountingIdlingResource](https://android.jlelse.eu/integrate-espresso-idling-resources-in-your-app-to-build-flexible-ui-tests-c779e24f5057) is one of the easiest to understand resource that comes bundled within the framework. \ No newline at end of file From 3b11a53347edcadbc5c10cb96779d93c01bdec11 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 12:01:44 +0530 Subject: [PATCH 049/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 4d68199bc2c..51a75286255 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -112,7 +112,7 @@ class SplashActivityTest { } ``` -How to use View Matchers, View Actions and View Assertions in Espresso? +### How to use View Matchers, View Actions and View Assertions in Espresso? Espresso has many ViewMatcher options which are very effective in uniquely locate UI element. You can also combine and create a combination of View Matchers to find element uniquely. The View Matcher is written like onView(ViewMatcher) which are commonly used. There are two types of actions that can be performed on View those are - From f689e65562901f30bf7e4b40dc565e24343dbcfc Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 12:04:00 +0530 Subject: [PATCH 050/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 51a75286255..f79aff256ef 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -163,7 +163,7 @@ A test case can never be called complete without assertions and hence it is impo * **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. * Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater then the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed -### Using swipeLeft/Right and using `scrollToPage`: +### Using swipeLeft/Right and using scrollToPage: * Espresso release contains new left and right swiping actions: swipeLeft() and swipeRight(). They both are really useful when you'd like to swipe between activity fragments, tab layouts or any other UI elements. * At times, GeneralSwipeAction can become unreliable because of its calculation varies on different screen size or density, so it may not be suitable for ViewPager. Instead, we can use to scroll with [ViewPagerActions](https://developer.android.com/reference/android/support/test/espresso/contrib/ViewPagerActions) @@ -215,6 +215,6 @@ fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { Espresso test might execute some checks while the app is doing some operations in the background threads, due to which the test may have no much content to interact with, therefore it throws an exception. -We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like SystemClock.sleep(period) or Thread.sleep(period) . Yet with this approach, we might end up having inflexible and slow tests +We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like `SystemClock.sleep(period)` or `Thread.sleep(period)` . Yet with this approach, we might end up having inflexible and slow tests In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, [CountingIdlingResource](https://android.jlelse.eu/integrate-espresso-idling-resources-in-your-app-to-build-flexible-ui-tests-c779e24f5057) is one of the easiest to understand resource that comes bundled within the framework. \ No newline at end of file From 5d9f924a7bb3710a3c8d5ec7722bceee93be2776 Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Fri, 17 Jan 2020 12:54:19 +0530 Subject: [PATCH 051/374] Updated Home (markdown) --- Home.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Home.md b/Home.md index 8abb78ca78f..2fdaa6cd26f 100644 --- a/Home.md +++ b/Home.md @@ -16,6 +16,10 @@ Please follow these steps for initial setup of the project on your local machine 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. + or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) + + + ## Instructions for making a code change **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). From 1a5370a57fdd2fff8f7227a460a401dc21ebd891 Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Fri, 17 Jan 2020 14:59:45 +0530 Subject: [PATCH 052/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 78 +++++++++++++++------- 1 file changed, 54 insertions(+), 24 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 2a94da5b0b3..4d97f58ae96 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -1,18 +1,19 @@ # Clone Oppia-Android using Android Studio Go to https://github.com/oppia/oppia-android Click on **Clone or download** and copy the link. -1 + +1 Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**> **Git** -2 +2 Login to GitHub with your credentials. Paste the **URL** and click on **Clone** button. Wait for a few minutes until gradle build completes. -4 +4 # Create New Branch @@ -20,64 +21,93 @@ Now the local copy of Oppia-Android is ready on your Android Studio Right side bottom of your android studio screen you will find a **develop** branch. Click on **develop** > **New Branch** > _Enter your new branch name_ > **OK** -10 -12 +10 +12 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 -11 + +11 + Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select **files >Add** -5 + +5 + New files will be shown in green color and modified file name will be displayed in blue color in project window(select file/folder/directory Ctrl+Alt|+A to manually version an unversioned file/files) -8 + +8 click on the green tick symbol to commit your files -9 + +9 + 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 before commiting. -13 +13 ## Push Changes Now we need to Push the code changes to local branch(orgin) and upstream(remote) Right click **app > Git > Repository > Push** -15 + +15 + Your new branch need to be added to both local(orgin) and upstream(remote). Once you push a branch to git you wont be able to rename it so be sure about the naming before pushing. -16 + +16 + ## Pull changes from Develop Once you push your new branch to develop you are ready to merge new changes from remote(upstream).Make sure your new branch's base branch is develop and the new branch is up-to-date with changes in develop. -17 + +17 + If you are not getting the below options of selecting upstream.Please login to your git hub account -18 + +18 + For login Go to **Android Studio>Preference>Version Control >Github>Add Account** -19 + +19 Fill all the credentials asked and login. Now Click **VCS>Git>Fetch** -20 -21 + +20 + +21 + Now select the upstream to pull changes from develop Select upstream in pull changes **dialog>select branch develop>Pull** you will find all the new changes pulled from develop in version control update info. -23 + +23 + ## Merge and resolve conflict select remote branch as **upstream>select develop branch>select your branch name> pull** -25 -27 + +25 + +27 You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. select **file>merge** -28 + +28 Now the local changes ,Result , and remote changes are displayed should merge these changes. -29 + +29 + Once all conflicts are resolved you will get a popup like this "All changes have been processed" Now click on Apply -30 + +30 + Now you will find the merged file changes locally in your android studio code. -31 + +31 From 3f1fb5e472e0e53daa933f8bb895094a1b581b4e Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 17 Jan 2020 15:03:48 +0530 Subject: [PATCH 053/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 4d97f58ae96..d0bb9782e65 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -1,10 +1,10 @@ # Clone Oppia-Android using Android Studio -Go to https://github.com/oppia/oppia-android +Go to https://github.com/oppia/oppia-android. Click on **Clone or download** and copy the link. 1 -Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**> **Git** +Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git** 2 @@ -37,7 +37,7 @@ New files will be shown in green color and modified file name will be displayed 8 -click on the green tick symbol to commit your files +Click on the green tick symbol to commit your files 9 From c67516a5f9a5facdab8f0c75575aa50b80ead80e Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 17 Jan 2020 15:11:21 +0530 Subject: [PATCH 054/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index d0bb9782e65..019e0189894 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -85,12 +85,12 @@ you will find all the new changes pulled from develop in version control update 23 -## Merge and resolve conflict - -select remote branch as **upstream>select develop branch>select your branch name> pull** - -25 - +## Merge and resolve conflict +Follow these steps mentioned below (Note: The image is just for reference in this case) +* Select remote branch as **upstream** +* Select **develop** branch +* Select **your_branch_name** +* Click on **Pull** 27 You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. From a4569f7f126644d8a90a9849ffa9996c39419234 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 15:11:29 +0530 Subject: [PATCH 055/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index f79aff256ef..1e2fe7de126 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -32,7 +32,7 @@ assertEquals(expected, actual) In the `assertEquals()`, you can easily get confused and interchange the actual and expected argument position. ``` -assertThat(actual, is(equalTo(expected))) +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: From 2a52a3f210727c9ce9f6cfba31216a843dfc1aae Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 15:19:02 +0530 Subject: [PATCH 056/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 1e2fe7de126..d42334357e4 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -42,7 +42,7 @@ 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()`: ``` -assertThat(actual, is(not(equalTo(expected)))) +assertThat(actual).isNotEqualTo(expected) ``` What’s cool about the **not** method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent shorthand version of the above equality methods which saves on typing: From a69f5023d58e17aaa34811e5f546cc4b75f0fa8c Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Fri, 17 Jan 2020 15:22:46 +0530 Subject: [PATCH 057/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 019e0189894..d661ec10d4b 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -2,7 +2,7 @@ Go to https://github.com/oppia/oppia-android. Click on **Clone or download** and copy the link. -1 +1 Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git** @@ -89,8 +89,11 @@ you will find all the new changes pulled from develop in version control update Follow these steps mentioned below (Note: The image is just for reference in this case) * Select remote branch as **upstream** * Select **develop** branch +25 + * Select **your_branch_name** * Click on **Pull** + 27 You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. From 72d7a778c9e08e5924eba30211213d6568d57d1e Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 16:20:04 +0530 Subject: [PATCH 058/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index d42334357e4..a662fbbd65f 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -45,7 +45,13 @@ Since there is no **assertNotEquals** (unless it’s custom coded) we have to us assertThat(actual).isNotEqualTo(expected) ``` -What’s cool about the **not** method is that it can surround any other method, which makes it a negate for any matcher. Also as seen above, the matcher methods can be chained to create any number of possible assertions. Another cool thing is that there’s an equivalent shorthand version of the above equality methods which saves on typing: +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: +``` +assertThat(logicalCondition).isTrue() +assertThat(logicalCondition).isFalse() +``` Hence assertThat should be the preferred method over the other methods. ## Testing private methods/functions From 26b2531dba63911dbbcd4877c34cb8f305bd2c73 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 16:22:07 +0530 Subject: [PATCH 059/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index a662fbbd65f..0b2f3c65bba 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -82,7 +82,7 @@ public class MyActivityTest { TextView results = (TextView) activity.findViewById(R.id.results_text_view); button.performClick(); - assertThat(results.getText().toString(), equalTo("Testing Android Rocks!")); + assertThat(results.getText().toString()).isEqualTo("Testing!")); } } ``` From 267dae60e952cabdb30f66492bc6e226ed4f6ee9 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 16:23:31 +0530 Subject: [PATCH 060/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 0b2f3c65bba..39a5a5cceef 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -93,8 +93,6 @@ Example JUnit4 test using Rules: @RunWith(AndroidJUnit4::class) class SplashActivityTest { - // The initialTouchMode enables the activity to be launched in touch mode. The launchActivity is - // disabled to launch Activity explicitly within each test case. @get:Rule var activityTestRule: ActivityTestRule = ActivityTestRule( SplashActivity::class.java, /* initialTouchMode= */ true, /* launchActivity= */ false @@ -197,7 +195,6 @@ Using the RecyclerViewMatcher under package ‘org.oppia.app.recyclerview’, yo @Test fun testHomeActivity_recyclerViewIndex3_clickTopicSummary_opensTopicActivity() { launch(HomeActivity::class.java).use { - onView(atPosition(R.id.home_recycler_view, 3)).perform(click()) intended(hasComponent(TopicActivity::class.java.name)) intended(hasExtra(TopicActivity.TOPIC_ACTIVITY_TOPIC_ID_ARGUMENT_KEY, TEST_TOPIC_ID_0)) From 26747c4c86011765ae56413e95611448c338f381 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 16:28:26 +0530 Subject: [PATCH 061/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 39a5a5cceef..0c5f76c9730 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -11,8 +11,7 @@ In Oppia we are considering: # 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. Test names should include three things: -Consider using a format similar to the following for naming test functions: +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`_ From 10ac009a69cbc6e0b6984ebf15a14dd298c7352d Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 17 Jan 2020 16:29:45 +0530 Subject: [PATCH 062/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 0c5f76c9730..2418a76b699 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -11,7 +11,7 @@ In Oppia we are considering: # 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: +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`_ From fe9e11e8b12c6cdf5125c74d8aee736e3f52fe60 Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Wed, 22 Jan 2020 14:56:06 +0530 Subject: [PATCH 063/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 43 +++++++++++----------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index d661ec10d4b..b1e01f526d4 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -8,10 +8,10 @@ Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**> 2 -Login to GitHub with your credentials. +Log in GitHub with your credentials. Paste the **URL** and click on **Clone** button. -Wait for a few minutes until gradle build completes. +Wait for a few minutes until Gradle build completes. 4 @@ -25,63 +25,63 @@ Click on **develop** > **New Branch** > _Enter your new branch name_ > **OK** 12 -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 +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 11 -Now when you create new activity it will show a dialog to add new files to Git(new files will be unversioned unless you allow this i.e. shown in reddish brown color file name.)Select **files >Add** +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. 5 -New files will be shown in green color and modified file name will be displayed in blue color in project window(select file/folder/directory Ctrl+Alt|+A to manually version an unversioned file/files) +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) 8 -Click on the green tick symbol to commit your files +Click on the green tick symbol to commit your files. 9 -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 before commiting. +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. 13 ## Push Changes -Now we need to Push the code changes to local branch(orgin) and upstream(remote) +Now we need to Push the code changes to local branch(origin) and upstream(remote) Right click **app > Git > Repository > Push** 15 -Your new branch need to be added to both local(orgin) and upstream(remote). -Once you push a branch to git you wont be able to rename it so be sure about the naming before pushing. +Your new branch needs to be added to both origin and upstream remote. +Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. 16 ## Pull changes from Develop -Once you push your new branch to develop you are ready to merge new changes from remote(upstream).Make sure your new branch's base branch is develop and the new branch is up-to-date with changes in develop. +Once you push your new branch to "develop" you are ready to merge new changes from remote(upstream). Make sure the new branch's base branch is "develop" and the new branch is up-to-date with changes in "develop". 17 -If you are not getting the below options of selecting upstream.Please login to your git hub account +If you are not getting the below options of selecting upstream.Please log in your GitHub account. 18 -For login Go to **Android Studio>Preference>Version Control >Github>Add Account** +For log in Go to **Android Studio>Preference>Version Control >GitHub>Add Account** 19 -Fill all the credentials asked and login. +Fill all the credentials asked and log in. Now Click **VCS>Git>Fetch** 20 21 -Now select the upstream to pull changes from develop +Now select the upstream to pull changes from "develop" Select upstream in pull changes **dialog>select branch develop>Pull** -you will find all the new changes pulled from develop in version control update info. +you will find all the new changes pulled from "develop" in version control update info. 23 @@ -96,21 +96,20 @@ Follow these steps mentioned below (Note: The image is just for reference in thi 27 -You will get the dialog of conflict files.You need to resolve the conflicts by merging the file changes. +You will get the dialog of conflicted files. You need to resolve the conflicts by merging the file changes. select **file>merge** 28 -Now the local changes ,Result , and remote changes are displayed should merge these changes. +Now the local changes, result and remote changes are displayed, should merge changes. 29 -Once all conflicts are resolved you will get a popup like this "All changes have been processed" -Now click on Apply +Once all conflicts are resolved, "All changes have been processed" pop up appears. Now click on **Apply** 30 -Now you will find the merged file changes locally in your android studio code. +Now you will find the merged file changes locally in your Android Studio code. 31 From afa72f5c027c997203b12682f651bda0a072c6b0 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 22 Jan 2020 15:55:42 +0530 Subject: [PATCH 064/374] Created Working on Oppia-Android UI (markdown) --- Working-on-Oppia-Android-UI.md | 64 ++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 Working-on-Oppia-Android-UI.md diff --git a/Working-on-Oppia-Android-UI.md b/Working-on-Oppia-Android-UI.md new file mode 100644 index 00000000000..1f0442fd835 --- /dev/null +++ b/Working-on-Oppia-Android-UI.md @@ -0,0 +1,64 @@ +Oppia-Android app mocks have been prepared on AdobeXD and the mocks have a version associated with them which is displayed on the bottom right corner of the "SplashScreen" page in mocks. Before working on any UI issue make sure that you have latest link of the mock associated with that UI. + +# Understanding the Mock Link: +For understanding the mocks let's take one example. +Open [Admin Auth Mock Link](https://xd.adobe.com/view/0687f00c-695b-437a-79a6-688e7f4f7552-70b6/screen/a841330e-efe5-4bdb-acdd-4d6e52a59571/PC-MP-Admin-Authorization-Add-Profile-Empty-) + +In the below image you can see that there are two icons on left side of the screen. First icon is fo comment, using which you can comment on the mock and second icon is for screen details which provides detailed information about the UI. +Screenshot 2020-01-22 at 3 14 13 PM + +Once you have selected the second icon, you will see a menu on right as below: +Screenshot 2020-01-22 at 3 17 03 PM + +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 respective to different items which helps to set margin/padding in android code. + +Screenshot 2020-01-22 at 3 20 19 PM + +*** + +# 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. + +### 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 not using blur effect in android code, so if the mock item does have a blur value than 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 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 you testing you can do 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 From 586c1c0f0664ae1230d191cf9ba0021274fbac3c Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 22 Jan 2020 16:08:14 +0530 Subject: [PATCH 065/374] Updated Working on Oppia Android UI (markdown) --- Working-on-Oppia-Android-UI.md => Working-on-UI.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Working-on-Oppia-Android-UI.md => Working-on-UI.md (100%) diff --git a/Working-on-Oppia-Android-UI.md b/Working-on-UI.md similarity index 100% rename from Working-on-Oppia-Android-UI.md rename to Working-on-UI.md From 36562c44c626d54e9d578dca5b8825339aad3e06 Mon Sep 17 00:00:00 2001 From: Veena Date: Wed, 22 Jan 2020 16:22:27 +0530 Subject: [PATCH 066/374] Updated Working on UI (markdown) --- Working-on-UI.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Working-on-UI.md b/Working-on-UI.md index 1f0442fd835..a7b1a71378f 100644 --- a/Working-on-UI.md +++ b/Working-on-UI.md @@ -4,7 +4,7 @@ Oppia-Android app mocks have been prepared on AdobeXD and the mocks have a versi For understanding the mocks let's take one example. Open [Admin Auth Mock Link](https://xd.adobe.com/view/0687f00c-695b-437a-79a6-688e7f4f7552-70b6/screen/a841330e-efe5-4bdb-acdd-4d6e52a59571/PC-MP-Admin-Authorization-Add-Profile-Empty-) -In the below image you can see that there are two icons on left side of the screen. First icon is fo comment, using which you can comment on the mock and second icon is for screen details which provides detailed information about the UI. +In the below image you can see that there are two icons on left side of the screen. First icon is for comment, using which you can comment on the mock and second icon is for screen details which provides detailed information about the UI. Screenshot 2020-01-22 at 3 14 13 PM Once you have selected the second icon, you will see a menu on right as below: @@ -49,7 +49,7 @@ In all textviews, make sure that proper `android:maxLines` and `android:ellipsiz *** # Testing UI -For you testing you can do following things: +For UI testing you can do 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. From d1340b350ab7bf29c6742755b5563f7ae678fe93 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 23 Jan 2020 11:51:29 +0530 Subject: [PATCH 067/374] Updated Working on UI (markdown) --- Working-on-UI.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Working-on-UI.md b/Working-on-UI.md index a7b1a71378f..26dd83a2412 100644 --- a/Working-on-UI.md +++ b/Working-on-UI.md @@ -27,7 +27,8 @@ Mocks uses Roboto fonts which are similar to sans-serif font in the android code 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. +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: From 19a98eb327ba9ac873264d310863c85beddc995e Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Mon, 27 Jan 2020 16:23:07 +0530 Subject: [PATCH 068/374] Updated Working on UI (markdown) --- Working-on-UI.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Working-on-UI.md b/Working-on-UI.md index 26dd83a2412..415c26e6b31 100644 --- a/Working-on-UI.md +++ b/Working-on-UI.md @@ -4,7 +4,7 @@ Oppia-Android app mocks have been prepared on AdobeXD and the mocks have a versi For understanding the mocks let's take one example. Open [Admin Auth Mock Link](https://xd.adobe.com/view/0687f00c-695b-437a-79a6-688e7f4f7552-70b6/screen/a841330e-efe5-4bdb-acdd-4d6e52a59571/PC-MP-Admin-Authorization-Add-Profile-Empty-) -In the below image you can see that there are two icons on left side of the screen. First icon is for comment, using which you can comment on the mock and second icon is for screen details which provides detailed information about the UI. +In the below image you can see that there are two icons on left side of the screen. First icon is for comment, using which you can comment on the mock and second icon is for screen details which provide detailed information about the UI. Screenshot 2020-01-22 at 3 14 13 PM Once you have selected the second icon, you will see a menu on right as below: @@ -13,7 +13,7 @@ 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 respective to different items which helps to set margin/padding in android code. +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. Screenshot 2020-01-22 at 3 20 19 PM @@ -36,7 +36,7 @@ Do not forget to check the opacity value in mocks. For example you find Opacity 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 not using blur effect in android code, so if the mock item does have a blur value than in that case optimise the android code in such a way that it does look almost like the mock without using the blur effect. +Currently, we are not using blur effect in android code, so if the mock item does have a blur value than 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 and use it accordingly in the code. @@ -50,9 +50,9 @@ In all textviews, make sure that proper `android:maxLines` and `android:ellipsiz *** # Testing UI -For UI testing you can do following things: +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. +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. From 8764beb00cf6a29afb4a7cc514c4e0f4bec70e2d Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 25 Mar 2020 04:29:06 +0530 Subject: [PATCH 069/374] Added prerequisites section --- Home.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Home.md b/Home.md index 2fdaa6cd26f..699403abea3 100644 --- a/Home.md +++ b/Home.md @@ -8,6 +8,10 @@ We're still working on setting up the basics of the Android project, but we are 4. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. 5. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide +## Prerequisites +1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. +2. Android Studio version [3.4.2](https://developer.android.com/studio/archive) or lower version. This is important because the `app` module test cases in this project will fail in latest android studio. + ## Installation Please follow these steps for initial setup of the project on your local machine. From 53fece7c9aa18086131995b4668be33548c7b6db Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 25 Mar 2020 04:29:56 +0530 Subject: [PATCH 070/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 699403abea3..477057dea82 100644 --- a/Home.md +++ b/Home.md @@ -10,7 +10,7 @@ We're still working on setting up the basics of the Android project, but we are ## Prerequisites 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. -2. Android Studio version [3.4.2](https://developer.android.com/studio/archive) or lower version. This is important because the `app` module test cases in this project will fail in latest android studio. +2. Android Studio version [3.4.2](https://developer.android.com/studio/archive) or lower version. This is important because the `app` module test cases are failing in latest android studio. ## Installation From fe12b0363bb534b3d636b45b863a16abee681cd0 Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Mon, 6 Apr 2020 15:22:28 +0530 Subject: [PATCH 071/374] Added wiki entry on installing ktlint as a prerequisite --- Home.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Home.md b/Home.md index 477057dea82..297212cf30a 100644 --- a/Home.md +++ b/Home.md @@ -11,6 +11,8 @@ We're still working on setting up the basics of the Android project, but we are ## Prerequisites 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. 2. Android Studio version [3.4.2](https://developer.android.com/studio/archive) or lower version. This is important because the `app` module test cases are failing in latest android studio. +3. Install the following linters: + * [Ktlint](https://github.com/pinterest/ktlint#installation) ## Installation From 966761108e68ab5ba107d578ec5ee28a2b1402f9 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 9 Apr 2020 16:03:50 +0530 Subject: [PATCH 072/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 297212cf30a..5bd605b4bb2 100644 --- a/Home.md +++ b/Home.md @@ -10,7 +10,7 @@ We're still working on setting up the basics of the Android project, but we are ## Prerequisites 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. -2. Android Studio version [3.4.2](https://developer.android.com/studio/archive) or lower version. This is important because the `app` module test cases are failing in latest android studio. +2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 3. Install the following linters: * [Ktlint](https://github.com/pinterest/ktlint#installation) From 28a0bbb59f525ff7be4e390498da26cbd9937714 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Apr 2020 14:57:28 +0530 Subject: [PATCH 073/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 2418a76b699..a9edc9d35c2 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -85,6 +85,19 @@ public class MyActivityTest { } } ``` + +### Running Roboelectric tests +1. Go to **Edit Configuration** in Android Studio +Screenshot 2020-04-13 at 2 51 02 PM + +2. Add **Android JUnit** +Screenshot 2020-04-13 at 2 51 31 PM + +3. Enter following information - (a.) **Name** (Normally class name) (b.)**Use classpath of module** (c.) **Class** +Screenshot 2020-04-13 at 2 52 01 PM + +4. Press `OK` to run the test cases in roboelectric. + ## Espresso Use [Espresso](https://developer.android.com/training/testing/espresso) to write concise, beautiful, and reliable Android UI tests. Example JUnit4 test using Rules: From ccf2302257f4d9a118a1dc6921135195b0161604 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 13 Apr 2020 15:20:23 +0530 Subject: [PATCH 074/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index a9edc9d35c2..4a17d45f479 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -94,7 +94,8 @@ public class MyActivityTest { Screenshot 2020-04-13 at 2 51 31 PM 3. Enter following information - (a.) **Name** (Normally class name) (b.)**Use classpath of module** (c.) **Class** -Screenshot 2020-04-13 at 2 52 01 PM +Screenshot 2020-04-13 at 3 18 39 PM + 4. Press `OK` to run the test cases in roboelectric. From 1dbb8849340cd1b2c841ed12be725aea58651de6 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 16 Apr 2020 16:21:57 -0700 Subject: [PATCH 075/374] Add coding style guidelines for layout files & IDs. --- Coding-style-guide.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index b5ef803806e..e23ee000312 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -36,6 +36,30 @@ NOTE: This does not guarantee 100% formatting of code as per guidelines but will - Order imports alphabetically. Remove unused imports. - Do not use "magic numbers" in code. Declare constants instead (typically at the module level). +## 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 ``_activity.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: _\_\__ + - The following are some recognized widget types (this list is not comprehensive): + - ``TextView`` + - ``EditText`` + - ``RecyclerView`` + - ``Button`` + - ``View`` + - Custom views (the full name of the view should be spelled out for the widget type in identifiers) + - Layout elements should be named as follows: + - ``container``: if the element contains other elements within the same layout + - ``placeholder``: if the element will be replaced at runtime with new elements (such as a fragment layout) + - Here are some examples of valid IDs: + - ``recently_played_activity_recently_played_fragment_placeholder`` (a ``FrameLayout`` in ``recently_played_activity.xml``) + - ``recently_played_fragment_ongoing_story_recycler_view`` (a ``RecyclerView`` in ``recently_played_fragment.xml``) + ## build.gradle file - Arrange lists in alphabetical order unless there's a good reason not to. - Combine `implementation`, `androidTestImplementation` and `testImplementation` to declare all similar dependencies in one block. \ No newline at end of file From 0d2874b3130fbe4e691e27a9f1168d37829aacbe Mon Sep 17 00:00:00 2001 From: nikitamarysolomanpvt <54615666+nikitamarysolomanpvt@users.noreply.github.com> Date: Mon, 27 Apr 2020 18:07:40 +0530 Subject: [PATCH 076/374] Created XML code style format (markdown) --- XML-code-style-format.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 XML-code-style-format.md diff --git a/XML-code-style-format.md b/XML-code-style-format.md new file mode 100644 index 00000000000..303f84aa215 --- /dev/null +++ b/XML-code-style-format.md @@ -0,0 +1,40 @@ + +## Problem Statement +Android Code Style improves productivity. When working alone on your apps you don’t have problems with your manual code formatting. Whereas while multiple developers, with multiple opinions, multiple operating systems and multiple screen sizes work on the same code base, if you don’t let a tool format your code, discussions about the formatting may arise or worse, different formatting and sorting increases diffs and can cause completely unnecessary merge conflicts. This will slow down development for no reason. + +It’s professional to have common formatting throughout the project. It helps the project to be ready to scale to two or more developers. +## Steps to do +* **Android Studio**>**Preferences(in mac)** +**Open Settings** > **Editor** >**Code Style** > **XML** > **Others** +![8](https://user-images.githubusercontent.com/54615666/80364656-ea4a3500-88a3-11ea-9b7b-ab804e8bbf55.png) +![pasted image 0](https://user-images.githubusercontent.com/54615666/80364659-eae2cb80-88a3-11ea-819a-f1d96beaea8b.png) +* Keep blank lines: 2 change it to 0 + +* **Open Settings** > **Editor** > **Code Style** > **XML** > **Android** Click **Set from...** text. +* Select **Predefined Styles** > **Android** Click **Apply button** + +![2](https://user-images.githubusercontent.com/54615666/80364643-e5858100-88a3-11ea-8a15-7a6e9ecf785c.png) + +## Final Settings + +![3](https://user-images.githubusercontent.com/54615666/80364649-e7e7db00-88a3-11ea-97c4-46b3bc2096eb.png) +![4](https://user-images.githubusercontent.com/54615666/80364650-e8807180-88a3-11ea-818b-effa8e4e2897.png) + +## Other Settings +![5](https://user-images.githubusercontent.com/54615666/80364651-e9190800-88a3-11ea-82ce-874110ff53c3.png) +![6](https://user-images.githubusercontent.com/54615666/80364653-e9b19e80-88a3-11ea-8489-1b6fafeb518a.png) +![7](https://user-images.githubusercontent.com/54615666/80364655-e9b19e80-88a3-11ea-90f4-15662f9f04c0.png) +![8](https://user-images.githubusercontent.com/54615666/80364656-ea4a3500-88a3-11ea-9b7b-ab804e8bbf55.png) + + +## Share rules +Formatting files makes even more sense when multiple people are working on a project so of course, should share formatting rules with the team. It’s a good start if we use Android Studio’s default code formatting. But that’s unsafe! The default settings have changed in the past and will change in the future. Our team should use a code style independent from the IntelliJ version one is working on. So if we want any custom changes that would help all, please do update in this doc and share rules. +Find current rules in CodeStyleRules.xml +## Beyond Setting Changes +After following all these steps in android studio, now it is easy to use standard code guidelines in XML files. + +Reformat all edited files automatically in android studio using the following command. +* **Windows:** Ctrl + Alt + L +* **Linux:** Ctrl + Shift + Alt + L +* **mac:** Option + Command + L +* **Ubuntu** users might face the issue because Ctrl + Alt + L locks the screen by default nature. Refer to this stackoverflow-link on how to solve this. From 303c5f104c0d42f61f1b1dbd3bcd3b98ae07fd31 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 27 Apr 2020 18:25:17 +0530 Subject: [PATCH 077/374] Updated XML code style format (markdown) --- XML-code-style-format.md | 1 - 1 file changed, 1 deletion(-) diff --git a/XML-code-style-format.md b/XML-code-style-format.md index 303f84aa215..566f12171a9 100644 --- a/XML-code-style-format.md +++ b/XML-code-style-format.md @@ -1,5 +1,4 @@ -## Problem Statement Android Code Style improves productivity. When working alone on your apps you don’t have problems with your manual code formatting. Whereas while multiple developers, with multiple opinions, multiple operating systems and multiple screen sizes work on the same code base, if you don’t let a tool format your code, discussions about the formatting may arise or worse, different formatting and sorting increases diffs and can cause completely unnecessary merge conflicts. This will slow down development for no reason. It’s professional to have common formatting throughout the project. It helps the project to be ready to scale to two or more developers. From fbf49a5c9fdab13faf4477c94928c6170d731d63 Mon Sep 17 00:00:00 2001 From: Veena Date: Fri, 22 May 2020 16:12:12 +0530 Subject: [PATCH 078/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 4a17d45f479..9c288a033dc 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -233,4 +233,19 @@ Espresso test might execute some checks while the app is doing some operations i We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like `SystemClock.sleep(period)` or `Thread.sleep(period)` . Yet with this approach, we might end up having inflexible and slow tests -In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, [CountingIdlingResource](https://android.jlelse.eu/integrate-espresso-idling-resources-in-your-app-to-build-flexible-ui-tests-c779e24f5057) is one of the easiest to understand resource that comes bundled within the framework. \ No newline at end of file +In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, [CountingIdlingResource](https://android.jlelse.eu/integrate-espresso-idling-resources-in-your-app-to-build-flexible-ui-tests-c779e24f5057) is one of the easiest to understand resource that comes bundled within the framework. + + +# Tips to run testcases in both Expresso and Roboelectric +The project contains two kinds of tests, unit tests using Robolectric and instrumentation tests using Espresso. + +Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. + +Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. + +For Performance Exception where at least 90 percent of the view should be visible to handle click +() event. +Make ScrollView as a parent in XML file and use scrollTo() while performing click() in the test. + +Example: +`onView(withId(R.id.walkthrough_welcome_next_button)).perform(scrollTo(), click())` From 810b55cd1fc1c138cabeb09be7fa12e3cc7e6b0d Mon Sep 17 00:00:00 2001 From: Veena Date: Tue, 26 May 2020 12:17:13 +0530 Subject: [PATCH 079/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 9c288a033dc..3fb228677ef 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -241,11 +241,32 @@ The project contains two kinds of tests, unit tests using Robolectric and instru Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. -Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. +Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. -For Performance Exception where at least 90 percent of the view should be visible to handle click +For **Performance Exception** where at least 90 percent of the view should be visible to handle click () event. Make ScrollView as a parent in XML file and use scrollTo() while performing click() in the test. Example: `onView(withId(R.id.walkthrough_welcome_next_button)).perform(scrollTo(), click())` + +**Assertion Failure :** Unlike on a real device, Robolectric shares a single thread for both UI operations and Test code. By default, Robolectric will execute tasks posted to Loopers synchronously inline. This causes Robolectric to execute tasks earlier than they would be on a real device. + +Robolectric’s default behavior is to process posted code synchronously and immediately, so the assertion fails with **[before, after, between]**, which is clearly incorrect. + +Apply the LooperMode(PAUSED) annotation to your test package/class/method [reference](http://robolectric.org/blog/2019/06/04/paused-looper/). + +``` +@LooperMode(LooperMode.Mode.PAUSED) + @Test + fun testAdministratorControlsFragment_clickOkButtonInLogoutDialog_opensProfileActivity() { + ActivityScenario.launch(createAdministratorControlsActivityIntent(0)).use { + onView(withId(R.id.administrator_controls_list)).perform(scrollToPosition(4)) + onView(withId(R.id.log_out_text_view)).perform(click()) + onView(withText(R.string.log_out_dialog_message)).inRoot(isDialog()) + .check(matches(isDisplayed())) + onView(withText(R.string.log_out_dialog_okay_button)).perform(click()) + intended(hasComponent(ProfileActivity::class.java.name)) + } + } +``` \ No newline at end of file From 01c8172ac5c6fc364efd7e9780ac17900106ce47 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 29 May 2020 16:23:36 -0700 Subject: [PATCH 080/374] Update the PR tips to include the expectations for PR assignees & handling of PR conversation threads. --- Guidance-on-submitting-a-PR.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 0d2b236c948..6fb06df3ef8 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -30,6 +30,8 @@ Note: This checklist should be embedded in your every PR explanation with approp ## Tips for getting your PR merged after submission 1. Keep track of **Assignees** section and reply to comments in the PR itself. -2. PRs should not be merged if there are any requested changes. -3. Make sure to resolve all conversations with appropriate comments and replies. **No** conversation should be resolved without having a proper end to the conversation. -4. Once everything is ready for 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 here too. \ No newline at end of file +2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. +3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. +4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). +5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. +6. 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. \ No newline at end of file From bbfeb0ab0ce2aeb350256f4cc9a9b46537fb43d6 Mon Sep 17 00:00:00 2001 From: Veena Date: Mon, 1 Jun 2020 13:43:48 +0530 Subject: [PATCH 081/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 3fb228677ef..b36585ad6d4 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -250,7 +250,8 @@ Make ScrollView as a parent in XML file and use scrollTo() while performing clic Example: `onView(withId(R.id.walkthrough_welcome_next_button)).perform(scrollTo(), click())` -**Assertion Failure :** Unlike on a real device, Robolectric shares a single thread for both UI operations and Test code. By default, Robolectric will execute tasks posted to Loopers synchronously inline. This causes Robolectric to execute tasks earlier than they would be on a real device. +### Assertion Failure : +1. Unlike on a real device, Robolectric shares a single thread for both UI operations and Test code. By default, Robolectric will execute tasks posted to Loopers synchronously inline. This causes Robolectric to execute tasks earlier than they would be on a real device. Robolectric’s default behavior is to process posted code synchronously and immediately, so the assertion fails with **[before, after, between]**, which is clearly incorrect. @@ -269,4 +270,16 @@ Apply the LooperMode(PAUSED) annotation to your test package/class/method [refer intended(hasComponent(ProfileActivity::class.java.name)) } } -``` \ No newline at end of file +``` +2. Choosing the right matcher to check your view. + - The doesNotExist() view assertion checks if a view exists in the current view hierarchy. + +``` +onView(withId(R.id.made_up_view_id)).check(doesNotExist()) +``` + + - We may have to test if the view is Visible or Gone and if `isDisplayed()` doesn't work, we make use of `withEffectiveVisibility(ViewMatchers.Visibility.VISIBLE))`. This matcher checks how the visibility of a view is set in the code. + +``` +onView(allOf(withId(R.id.ivPlayPauseAudio),withEffectiveVisibility(ViewMatchers.Visibility.VISIBLE))) +``` From 63c98866f9b99315eec6faa91bf85fa3c54e496b Mon Sep 17 00:00:00 2001 From: Veena Date: Mon, 1 Jun 2020 13:48:17 +0530 Subject: [PATCH 082/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index b36585ad6d4..5c791694cc7 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -253,9 +253,9 @@ Example: ### Assertion Failure : 1. Unlike on a real device, Robolectric shares a single thread for both UI operations and Test code. By default, Robolectric will execute tasks posted to Loopers synchronously inline. This causes Robolectric to execute tasks earlier than they would be on a real device. -Robolectric’s default behavior is to process posted code synchronously and immediately, so the assertion fails with **[before, after, between]**, which is clearly incorrect. +- Robolectric’s default behavior is to process posted code synchronously and immediately, so the assertion fails with **[before, after, between]**, which is clearly incorrect. -Apply the LooperMode(PAUSED) annotation to your test package/class/method [reference](http://robolectric.org/blog/2019/06/04/paused-looper/). +- Apply the LooperMode(PAUSED) annotation to your test package/class/method [reference](http://robolectric.org/blog/2019/06/04/paused-looper/). ``` @LooperMode(LooperMode.Mode.PAUSED) From 1ee3adff2d17b6c0ffd246376a1ef56f72caa138 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 3 Jun 2020 11:08:24 +0530 Subject: [PATCH 083/374] added Bufbuild in linters --- Home.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Home.md b/Home.md index 5bd605b4bb2..216a771e70e 100644 --- a/Home.md +++ b/Home.md @@ -13,6 +13,7 @@ We're still working on setting up the basics of the Android project, but we are 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 3. Install the following linters: * [Ktlint](https://github.com/pinterest/ktlint#installation) + * [Bufbuild](https://buf.build/docs/installation) ## Installation From d3da301dc78fe4fcd10b2817d7da239966f4d831 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 3 Jun 2020 11:49:57 +0530 Subject: [PATCH 084/374] added buf guide --- Home.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 216a771e70e..720ab90c716 100644 --- a/Home.md +++ b/Home.md @@ -13,7 +13,7 @@ We're still working on setting up the basics of the Android project, but we are 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 3. Install the following linters: * [Ktlint](https://github.com/pinterest/ktlint#installation) - * [Bufbuild](https://buf.build/docs/installation) + * [Bufbuild](https://github.com/oppia/oppia-android/wiki#buf-guide) ## Installation @@ -132,6 +132,39 @@ The following instructions describe how to make a one-off code change using a fe ``` By using this command git will detect the file as a renamed file. + + +## Buf Guide + +Install `buf` from [here](https://buf.build/docs/installation). We have a configuration file `buf.yaml` in the root of the project. Following is the list of things we are checking and 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. +* `PACKAGE_SAME_DIRECTORY` checks that all files with a given package are 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. +* `PACKAGE_SAME_JAVA_PACKAGE` checks that all files with a given package have the same value for the java_package option. +* `ENUM_NO_ALLOW_ALIAS` checks that enums do not have the allow_alias option set. +* `FIELD_NO_DESCRIPTOR` checks that field names are are not name capitalization of "descriptor" with any number of prefix or suffix underscores. +* `IMPORT_NO_PUBLIC` checks that imports are not public. +* `IMPORT_NO_WEAK` checks that imports are not weak. +* `PACKAGE_DEFINED` checks that all files with have a package defined. +* `ENUM_PASCAL_CASE` checks that enums are PascalCase. +* `ENUM_VALUE_UPPER_SNAKE_CASE` checks that enum values are UPPER_SNAKE_CASE. +* `FIELD_LOWER_SNAKE_CASE` checks that field names are lower_snake_case. +* `MESSAGE_PASCAL_CASE` checks that messages are PascalCase. +* `ONEOF_LOWER_SNAKE_CASE` checks that oneof names are lower_snake_case. +* `PACKAGE_LOWER_SNAKE_CASE` checks that packages are lower_snake.case. +* `ENUM_ZERO_VALUE_SUFFIX` checks that enum zero values are suffixed with _UNSPECIFIED (suffix is configurable). +* `FILE_LOWER_SNAKE_CASE` checks that filenames are lower_snake_case. + + +### Excluding: +* `PACKAGE_DIRECTORY_MATCH` checks that all files with are in a directory that matches their package name. +* `ENUM_VALUE_PREFIX` checks that enum values are prefixed with ENUM_NAME_UPPER_SNAKE_CASE. +* `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. + + + ## Communication channels ### Mailing lists From 83d4759733d48cbdbf8b57b5c62f0d989c238fbd Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 3 Jun 2020 12:07:16 +0530 Subject: [PATCH 085/374] Created Buf Guide (markdown) --- Buf-Guide.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 Buf-Guide.md diff --git a/Buf-Guide.md b/Buf-Guide.md new file mode 100644 index 00000000000..d6f9b8f5ac7 --- /dev/null +++ b/Buf-Guide.md @@ -0,0 +1,32 @@ +## Installation + +Install `buf` from [here](https://buf.build/docs/installation). + +## Configuration File + +We have a configuration file `buf.yaml` in the root of the project. Following is the list of things we are checking and 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. +* `PACKAGE_SAME_DIRECTORY` checks that all files with a given package are 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. +* `PACKAGE_SAME_JAVA_PACKAGE` checks that all files with a given package have the same value for the java_package option. +* `ENUM_NO_ALLOW_ALIAS` checks that enums do not have the allow_alias option set. +* `FIELD_NO_DESCRIPTOR` checks that field names are are not name capitalization of "descriptor" with any number of prefix or suffix underscores. +* `IMPORT_NO_PUBLIC` checks that imports are not public. +* `IMPORT_NO_WEAK` checks that imports are not weak. +* `PACKAGE_DEFINED` checks that all files with have a package defined. +* `ENUM_PASCAL_CASE` checks that enums are PascalCase. +* `ENUM_VALUE_UPPER_SNAKE_CASE` checks that enum values are UPPER_SNAKE_CASE. +* `FIELD_LOWER_SNAKE_CASE` checks that field names are lower_snake_case. +* `MESSAGE_PASCAL_CASE` checks that messages are PascalCase. +* `ONEOF_LOWER_SNAKE_CASE` checks that oneof names are lower_snake_case. +* `PACKAGE_LOWER_SNAKE_CASE` checks that packages are lower_snake.case. +* `ENUM_ZERO_VALUE_SUFFIX` checks that enum zero values are suffixed with _UNSPECIFIED (suffix is configurable). +* `FILE_LOWER_SNAKE_CASE` checks that filenames are lower_snake_case. + + +#### Excluding: +* `PACKAGE_DIRECTORY_MATCH` checks that all files with are in a directory that matches their package name. +* `ENUM_VALUE_PREFIX` checks that enum values are prefixed with ENUM_NAME_UPPER_SNAKE_CASE. +* `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. From de703c0bf72827af622e5c2043f7e877b3d69def Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 3 Jun 2020 12:08:08 +0530 Subject: [PATCH 086/374] added buf guide page link --- Home.md | 34 +--------------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/Home.md b/Home.md index 720ab90c716..3eb33467824 100644 --- a/Home.md +++ b/Home.md @@ -13,7 +13,7 @@ We're still working on setting up the basics of the Android project, but we are 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 3. Install the following linters: * [Ktlint](https://github.com/pinterest/ktlint#installation) - * [Bufbuild](https://github.com/oppia/oppia-android/wiki#buf-guide) + * [Bufbuild](https://github.com/oppia/oppia-android/wiki/Buf-Guide) ## Installation @@ -133,38 +133,6 @@ The following instructions describe how to make a one-off code change using a fe By using this command git will detect the file as a renamed file. - -## Buf Guide - -Install `buf` from [here](https://buf.build/docs/installation). We have a configuration file `buf.yaml` in the root of the project. Following is the list of things we are checking and 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. -* `PACKAGE_SAME_DIRECTORY` checks that all files with a given package are 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. -* `PACKAGE_SAME_JAVA_PACKAGE` checks that all files with a given package have the same value for the java_package option. -* `ENUM_NO_ALLOW_ALIAS` checks that enums do not have the allow_alias option set. -* `FIELD_NO_DESCRIPTOR` checks that field names are are not name capitalization of "descriptor" with any number of prefix or suffix underscores. -* `IMPORT_NO_PUBLIC` checks that imports are not public. -* `IMPORT_NO_WEAK` checks that imports are not weak. -* `PACKAGE_DEFINED` checks that all files with have a package defined. -* `ENUM_PASCAL_CASE` checks that enums are PascalCase. -* `ENUM_VALUE_UPPER_SNAKE_CASE` checks that enum values are UPPER_SNAKE_CASE. -* `FIELD_LOWER_SNAKE_CASE` checks that field names are lower_snake_case. -* `MESSAGE_PASCAL_CASE` checks that messages are PascalCase. -* `ONEOF_LOWER_SNAKE_CASE` checks that oneof names are lower_snake_case. -* `PACKAGE_LOWER_SNAKE_CASE` checks that packages are lower_snake.case. -* `ENUM_ZERO_VALUE_SUFFIX` checks that enum zero values are suffixed with _UNSPECIFIED (suffix is configurable). -* `FILE_LOWER_SNAKE_CASE` checks that filenames are lower_snake_case. - - -### Excluding: -* `PACKAGE_DIRECTORY_MATCH` checks that all files with are in a directory that matches their package name. -* `ENUM_VALUE_PREFIX` checks that enum values are prefixed with ENUM_NAME_UPPER_SNAKE_CASE. -* `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. - - - ## Communication channels ### Mailing lists From 8438f682d0dc91037bf21231c4d142b84397322e Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 4 Jun 2020 11:02:24 +0530 Subject: [PATCH 087/374] added commands and sub points in config --- Buf-Guide.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/Buf-Guide.md b/Buf-Guide.md index d6f9b8f5ac7..fb39dcfd5ef 100644 --- a/Buf-Guide.md +++ b/Buf-Guide.md @@ -2,31 +2,75 @@ Install `buf` from [here](https://buf.build/docs/installation). +## Commands + +* `buf --version` - to check the version of the buf you had installed +* `buf --help` - help command of buf +* `buf check lint --input=model/src/main/proto --input-config buf.yaml` - this is where we do lint check + + ## Configuration File We have a configuration file `buf.yaml` in the root of the project. Following is the list of things we are checking and 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 same package name should be in 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. -* `FIELD_NO_DESCRIPTOR` checks that field names are are not name capitalization of "descriptor" with any number of prefix or suffix underscores. + * 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 with have a package defined. + * All proto files must have a package name specify in it, 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 lower snake case + * `PACKAGE_LOWER_SNAKE_CASE` checks that packages are lower_snake.case. -* `ENUM_ZERO_VALUE_SUFFIX` checks that enum zero values are suffixed with _UNSPECIFIED (suffix is configurable). -* `FILE_LOWER_SNAKE_CASE` checks that filenames 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` (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, example - `topic.proto` #### Excluding: * `PACKAGE_DIRECTORY_MATCH` checks that all files with are in a directory that matches their package name. -* `ENUM_VALUE_PREFIX` checks that enum values are prefixed with ENUM_NAME_UPPER_SNAKE_CASE. + * this verifies that all files that declare a given package foo.bar.baz.v1 are 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` From 0a9df6072c7535581c7d60d1f3781bf5ebc5dc77 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 15 Jun 2020 17:37:43 +0530 Subject: [PATCH 088/374] added detailed page for ktlint setup and use --- Ktlint-Guide.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 Ktlint-Guide.md diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md new file mode 100644 index 00000000000..fd1b2acc4a8 --- /dev/null +++ b/Ktlint-Guide.md @@ -0,0 +1,56 @@ +# Installation +Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation) + +# Commands +* `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.0`. + +* `ktlint "path/of/your/kotlin/file"` - To check any specific kotlin file or all the kotlin file under a directory you can use this command. + + * Examples
+ * Specific File -
`ktlint "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * Specific Directory - `ktlint utility/src/**/*.kt` + +* `ktlint --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` + + * Examples
+ * Specific File -
`ktlint --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * Specific Directory - `ktlint --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 `Kotlinx` 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` + + If you want to disable for a block of code/ multiple lines, you can put the blocky comment as well. At starting `/* ktlint-disable max-line-length */` and at the end `/* ktlint-enable max-line-length */` + + * Example -
+ * `fun testWalkthroughWelcomeFragment_recyclerViewIndex1_topicSelected_clickNoButton_worksCorrectly() { // ktlint-disable max-line-length` + + * ``` + /* ktlint-disable max-line-length */ + fun testWalkthroughWelcomeFragment_recyclerViewIndex1_topicSelected_clickNoButton_worksCorrectly() { + .... + .... + } + /* ktlint-enable max-line-length */ + ``` \ No newline at end of file From 13edb6c5efe4175a7e3a56aca9c026e118dc057e Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 16 Jun 2020 11:01:09 +0530 Subject: [PATCH 089/374] kotlinx update to kotlin --- Ktlint-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index fd1b2acc4a8..75b6462ff52 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -22,7 +22,7 @@ In Android Studio we have a feature called Macros which helps you convert multip 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 `Kotlinx` will get shifted at the end of the import list which is a correct order. +* `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 From 57dc6553372609e215128f3a216c9e78f30100dd Mon Sep 17 00:00:00 2001 From: Veena Date: Wed, 17 Jun 2020 15:38:07 +0530 Subject: [PATCH 090/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 5c791694cc7..1ae3ff3ec6b 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -243,13 +243,45 @@ Both frameworks can create the same kinds of tests, the difference is how they Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. -For **Performance Exception** where at least 90 percent of the view should be visible to handle click -() event. -Make ScrollView as a parent in XML file and use scrollTo() while performing click() in the test. +### Performance Exception/Runtime Exception Failure: -Example: +``` +androidx.test.espresso.PerformException: Error performing 'single click' on view 'with id: org.oppia.app:id/profile_progress_list'. + +Caused by: java.lang.RuntimeException: Action will not be performed because the target view does not match one or more of the following constraints: +at least 90 percent of the view's area is displayed to the user. +```` +1. Make ScrollView as a parent in XML file and use scrollTo() while performing click() in the test. + + **Example:** `onView(withId(R.id.walkthrough_welcome_next_button)).perform(scrollTo(), click())` +2. Sometimes test is rejected on small screen devices. Use Robolectric `qualifiers` property that sets up the Android simulation environment with a corresponding configuration. The system’s Configuration, Display and DisplayMetrics objects will all reflect the specified configuration, the locale will be set, and appropriate resources will be selected. + + Apply the `@Config(qualifiers = "port-xxhdpi")` annotation to your test package/class/method [reference](http://robolectric.org/device-configuration/). + +``` + @Test + @Config(qualifiers = "port-xxhdpi") + fun testProfileProgressActivity_recyclerViewIndex0_clickViewAll_opensRecentlyPlayedActivity() { + launch(createProfileProgressActivityIntent(internalProfileId)).use { + waitForTheView(withText("Sean")) + onView(atPositionOnView(R.id.profile_progress_list, 0, R.id.view_all_text_view)).check( + matches( + withText("View All") + ) + ).perform(click()) + intended(hasComponent(RecentlyPlayedActivity::class.java.name)) + intended( + hasExtra( + RecentlyPlayedActivity.RECENTLY_PLAYED_ACTIVITY_INTERNAL_PROFILE_ID_KEY, + internalProfileId + ) + ) + } + } +``` + ### Assertion Failure : 1. Unlike on a real device, Robolectric shares a single thread for both UI operations and Test code. By default, Robolectric will execute tasks posted to Loopers synchronously inline. This causes Robolectric to execute tasks earlier than they would be on a real device. From 4b2b2de7382d3da641244c5ac64779a5480658eb Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 17 Jun 2020 16:13:52 -0700 Subject: [PATCH 091/374] Clarify that team members with write access don't need to use a repo fork. --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 3eb33467824..55991863a90 100644 --- a/Home.md +++ b/Home.md @@ -19,7 +19,7 @@ We're still working on setting up the basics of the Android project, but we are Please follow these steps for initial setup of the project 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`. +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. 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. From e62ea0deceb9b1e9aae9e5a8927d927a10078241 Mon Sep 17 00:00:00 2001 From: Veena Date: Thu, 18 Jun 2020 12:04:55 +0530 Subject: [PATCH 092/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 1ae3ff3ec6b..99057b08d4e 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -241,7 +241,9 @@ The project contains two kinds of tests, unit tests using Robolectric and instru Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. -Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. +Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. + +Following are the different ways you can try to pass the testcases. ### Performance Exception/Runtime Exception Failure: From 1e9a19a9d0a90962a0cf01e2aecad1473ab89462 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 18 Jun 2020 12:11:49 +0530 Subject: [PATCH 093/374] connected Ktlint Guide page --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 55991863a90..d222ce10b51 100644 --- a/Home.md +++ b/Home.md @@ -12,7 +12,7 @@ We're still working on setting up the basics of the Android project, but we are 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). 3. Install the following linters: - * [Ktlint](https://github.com/pinterest/ktlint#installation) + * [Ktlint](https://github.com/oppia/oppia-android/wiki/Ktlint-Guide) * [Bufbuild](https://github.com/oppia/oppia-android/wiki/Buf-Guide) ## Installation From ad2d5896a16eb033766ccbcb21ca9d8d3c8a1fd5 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 19 Jun 2020 19:10:26 +0530 Subject: [PATCH 094/374] Created Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 Firebase-Console-Guide.md diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md new file mode 100644 index 00000000000..aa1943a2ffb --- /dev/null +++ b/Firebase-Console-Guide.md @@ -0,0 +1,34 @@ +## Index +* [Viewing the Console](#viewing-the-console) + * [Crashlytics](#crashlytics) + * [Analytics](#analytics) +* Setting up your own Firebase Project +## Viewing the Console +* Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account (if you haven't) -> Select Oppia Android Dev Project. +* You will be welcomed by the following screen : +> +### 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 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. From 76f8e13e962f8678feeb5b47f7224f2acc8c0171 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 19 Jun 2020 19:13:52 +0530 Subject: [PATCH 095/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index aa1943a2ffb..0dc1767b097 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -1,4 +1,4 @@ -## Index +## Table of Contents * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) * [Analytics](#analytics) From eab7ac7641a6394ab8831e73f6f35fc5e864e1e8 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 19 Jun 2020 20:46:10 +0530 Subject: [PATCH 096/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index 0dc1767b097..30513713e5b 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -2,7 +2,8 @@ * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) * [Analytics](#analytics) -* Setting up your own Firebase Project +* [Your own Firebase Project](#your-own-firebase-project) + * [Setting it up](#setting-it-up) ## Viewing the Console * Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account (if you haven't) -> Select Oppia Android Dev Project. * You will be welcomed by the following screen : @@ -32,3 +33,11 @@ * 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. + +## 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. From 56b24fb87ae375e59b286807b96e1f2c72084c53 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 19 Jun 2020 21:33:44 +0530 Subject: [PATCH 097/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index 30513713e5b..b28802042aa 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -4,6 +4,7 @@ * [Analytics](#analytics) * [Your own Firebase Project](#your-own-firebase-project) * [Setting it up](#setting-it-up) + * [App registration](#app-registration) ## Viewing the Console * Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account (if you haven't) -> Select Oppia Android Dev Project. * You will be welcomed by the following screen : @@ -40,4 +41,12 @@ * 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. +* 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. \ No newline at end of file From 20b9b09b709198e0122d1acbbec560588f1e66a8 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 23 Jun 2020 07:57:54 +0530 Subject: [PATCH 098/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index b28802042aa..b931a82858b 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -2,6 +2,7 @@ * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) * [Analytics](#analytics) + * [DebugView](#debugview) * [Your own Firebase Project](#your-own-firebase-project) * [Setting it up](#setting-it-up) * [App registration](#app-registration) @@ -34,6 +35,15 @@ * 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 package_name` 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. ## Your own Firebase Project ### Setting it up From 5a08e3e0bd2f646f697a62ff64f763a6724dbf1b Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 6 Jul 2020 04:53:45 +0530 Subject: [PATCH 099/374] added auto formatter example --- Ktlint-Guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index 75b6462ff52..1124e444169 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -4,18 +4,18 @@ Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation) # Commands * `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.0`. -* `ktlint "path/of/your/kotlin/file"` - To check any specific kotlin file or all the kotlin file under a directory you can use this command. - - * Examples
- * Specific File -
`ktlint "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
- * Specific Directory - `ktlint utility/src/**/*.kt` - * `ktlint --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` * Examples
* Specific File -
`ktlint --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
* Specific Directory - `ktlint --android "utility/src/**/*.kt"` +* `ktlint -F --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` with Ktlint Auto Formatter `-F`. This will fix some of the issues automatically. + + * Examples
+ * Specific File -
`ktlint -F --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * Specific Directory - `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. From 1e3e3cb6c81a99228155fb7e24f2ac3a3eb35d2b Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 11 Aug 2020 23:03:17 -0700 Subject: [PATCH 100/374] Introduce revert & regression policy --- Revert-&-regression-policy.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 Revert-&-regression-policy.md diff --git a/Revert-&-regression-policy.md b/Revert-&-regression-policy.md new file mode 100644 index 00000000000..5e3827c1e37 --- /dev/null +++ b/Revert-&-regression-policy.md @@ -0,0 +1,24 @@ +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. + +## 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. \ No newline at end of file From 5b31c424c6a7ec088e3d62b1c999f1743025eb4d Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 11 Aug 2020 23:14:25 -0700 Subject: [PATCH 101/374] Add details for folks who cause regressions. --- Revert-&-regression-policy.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/Revert-&-regression-policy.md b/Revert-&-regression-policy.md index 5e3827c1e37..ebaa813b506 100644 --- a/Revert-&-regression-policy.md +++ b/Revert-&-regression-policy.md @@ -12,7 +12,7 @@ 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. +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 @@ -21,4 +21,15 @@ For this reason, the team's policy is to quickly revert regressions when they're 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. \ No newline at end of file + - 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 From 503ffdabe033d74c0e885eda8c30d46808cea478 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 4 Sep 2020 05:10:40 +0530 Subject: [PATCH 102/374] Funnels, Conversions, Custom Parameters, Filtering. --- Firebase-Console-Guide.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index b931a82858b..62ab195ad95 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -3,6 +3,9 @@ * [Crashlytics](#crashlytics) * [Analytics](#analytics) * [DebugView](#debugview) + * [Funnels](#funnels) + * [Adding Custom Parameters](#adding-custom-parameters) + * [Conversions](#conversions) * [Your own Firebase Project](#your-own-firebase-project) * [Setting it up](#setting-it-up) * [App registration](#app-registration) @@ -32,6 +35,7 @@ 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. @@ -44,7 +48,30 @@ > * 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. - +### 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" From 32670699f79a16baf716d351e312f29327f567ee Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Fri, 4 Sep 2020 05:38:33 +0530 Subject: [PATCH 103/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index 62ab195ad95..e621353e632 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -1,3 +1,4 @@ +This document is made as a guide for viewing and customising the firebase project(s) of Oppia-Android. It is recommended to fully read this doc before making any changes to the Firebase project. If you only want to view the firebase console then this doc can help you in viewing exactly the thing that you want to see. It must also be noted that appropriate permissions are required for viewing/editing anything in the console. For permissions, please contact Ben Henning at henning.benmax@gmail.com. ## Table of Contents * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) From d0c8c18ccdf90f2899ec2059dd9b324b058bb7af Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 3 Sep 2020 17:24:15 -0700 Subject: [PATCH 104/374] Switch contact information to oppia-android-dev@ --- Firebase-Console-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index e621353e632..2821e1c2d97 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -1,4 +1,4 @@ -This document is made as a guide for viewing and customising the firebase project(s) of Oppia-Android. It is recommended to fully read this doc before making any changes to the Firebase project. If you only want to view the firebase console then this doc can help you in viewing exactly the thing that you want to see. It must also be noted that appropriate permissions are required for viewing/editing anything in the console. For permissions, please contact Ben Henning at henning.benmax@gmail.com. +This document is made as a guide for viewing and customising the Firebase project(s) of Oppia-Android. It is recommended to fully read this doc before making any changes to the Firebase project. If you only want to view the Firebase console then this doc can help you in viewing exactly the thing that you want to see. It must also be noted that appropriate permissions are required for viewing/editing anything in the console. For permissions, please contact oppia-android-dev@googlegroups.com. ## Table of Contents * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) From 3f2ed3c8bc0a7bc853477671aae5d8ac62d909fa Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 8 Sep 2020 12:47:50 -0700 Subject: [PATCH 105/374] Moving onboarding instructions to their own section --- Home.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Home.md b/Home.md index d222ce10b51..bb00b955123 100644 --- a/Home.md +++ b/Home.md @@ -1,5 +1,6 @@ Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! +## Onboarding instructions We're still working on setting up the basics of the Android project, but we are starting to welcome new contributors who'd like to help out. For now, if you're interested in contributing, please follow the following steps: 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). @@ -8,6 +9,7 @@ We're still working on setting up the basics of the Android project, but we are 4. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. 5. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide + ## Prerequisites 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). From f2a449ef06810c1ac63e1780363cdac3cc541877 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 18 Sep 2020 22:50:34 +0530 Subject: [PATCH 106/374] Created SLoP 2020 (Android) (markdown) --- SLoP-2020-(Android).md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 SLoP-2020-(Android).md diff --git a/SLoP-2020-(Android).md b/SLoP-2020-(Android).md new file mode 100644 index 00000000000..0c6509785eb --- /dev/null +++ b/SLoP-2020-(Android).md @@ -0,0 +1,41 @@ +**_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” 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 “**DSC point**”. +5. If you would like to take up issues that are not part of above labels or do not have a score label, please contact your onboarding mentor and request for the score for the issue. Your mentor will assign a score to the issue and communicate the same to the org admins. The org admins will then add the relevant label to the issue. + +### Expectations from students +1. Look for issues which are not assigned to anyone and comment on the issue mentioning your mentor name that you would like to work on it. Once the mentor approves you can start working on it. +2. Make sure that the issue that you are working on has a score assigned to it before you finish the PR for that issue. +3. Keep in touch with your mentor and give updates on regular time intervals. This can be something which you can figure out with your mentor. It's a good practice to communicate to your mentor atleast once a week. +4. Your PRs should get reviewed by your mentor within 24 hours but if for some reason the mentor is not reachable for more than 24 hours then assign your PRs to Rajat (@rt4914) for review. **NOTE: wait for atleast 24 hours to get a reply from a mentor.** +5. In case of any doubts or issues you should immediately talk to your mentor. + +# Instructions for mentors + +### Who are the mentors? +For initial 2 PRs default mentors will be Ben and Rajat. +After 2 PRs tentative mentor list: Akshay, Mohamed, Pulkit, Sarthak + +### Expectations +1. Please review assigned PRs within a 24 hr period. + - If you cannot review in that time frame, due to a one-off problem, please communicate the same in the PR thread and mention when you + - would be able to review the PR. +If you cannot review PRs in a 24 hr time frame for an extended period, consider temporarily assigning code-ownership to another experienced contributor. +2. If a student shows no activity for an assigned issue for >1 week, de-assign them so that other contributors get a chance to work on the issue. +3. Project leads may need to score project specific issues if a student requests to work on them (see “Scoring”). +4. Mentors are encouraged to have check-ins with their students on a weekly basis to make sure the students aren't stuck and are having a positive experience. +5. The level of mentoring is expected to be slightly higher than that of hacktoberfest and dealing with new contributors but less than that of GSoC. +Please note: Apart from the standard “24 hr review” rule, there is no formal time commitment for a mentor. + +### Escalation Policy +If there are any SLoP-related doubts / concerns, please reach out to the org admins (@kevintab95, @rt4914, @BenHenning). From d2e372ae7df82392222f28193680dcfaf2db0310 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 18 Sep 2020 22:50:50 +0530 Subject: [PATCH 107/374] Updated SLoP 2020 (Android) (markdown) --- SLoP-2020-(Android).md => SLoP-2020-Android.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename SLoP-2020-(Android).md => SLoP-2020-Android.md (100%) diff --git a/SLoP-2020-(Android).md b/SLoP-2020-Android.md similarity index 100% rename from SLoP-2020-(Android).md rename to SLoP-2020-Android.md From c9da77d09aaf6f40526b58f7131742a6dc187512 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 18 Sep 2020 23:09:26 +0530 Subject: [PATCH 108/374] Updated SLoP 2020 Android (markdown) --- SLoP-2020-Android.md => SLoP-2020.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename SLoP-2020-Android.md => SLoP-2020.md (99%) diff --git a/SLoP-2020-Android.md b/SLoP-2020.md similarity index 99% rename from SLoP-2020-Android.md rename to SLoP-2020.md index 0c6509785eb..1014e9b6fa7 100644 --- a/SLoP-2020-Android.md +++ b/SLoP-2020.md @@ -10,7 +10,7 @@ - [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” 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 “**DSC point**”. +4. Your onboarding mentor will suggest starter issues for you to work on. These issues will have score labels of the form “**DSC \ point**”. 5. If you would like to take up issues that are not part of above labels or do not have a score label, please contact your onboarding mentor and request for the score for the issue. Your mentor will assign a score to the issue and communicate the same to the org admins. The org admins will then add the relevant label to the issue. ### Expectations from students From 26a85dabb6b52850149fdb5f609227422183c01c Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 24 Sep 2020 22:41:02 -0700 Subject: [PATCH 109/374] Clarify that we suggest using the CLI, not Gradle integration for ktlint. --- Ktlint-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index 1124e444169..6d81a606ffc 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -1,5 +1,5 @@ # Installation -Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation) +Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation). Note that we specifically recommend using the command-line interface, not the Gradle integration. # Commands * `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.0`. From 4c46d0932af666da371a124249e04ce933edeb0a Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 28 Sep 2020 12:26:37 +0530 Subject: [PATCH 110/374] added TestCoroutineDispatchers detail --- Oppia-Android-Testing.md | 42 ++++++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 99057b08d4e..b1abed4751a 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -24,7 +24,7 @@ For Example: ## 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()`: +The first benefit is that `assertThat()` is more readable than the other assert methods. For example, take a look at the following `assertEquals()`: ``` assertEquals(expected, actual) ``` @@ -44,7 +44,7 @@ Since there is no **assertNotEquals** (unless it’s custom coded) we have to us 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 . +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: ``` @@ -55,7 +55,7 @@ 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 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 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 @@ -67,8 +67,8 @@ The following is the default directory structure for Oppia application and test If you follow this conversion, the Android build system runs your tests on the correct target (JVM or Android device). -## Roboelectric -With [Roboelectric](https://github.com/robolectric/robolectric) you can write tests like this: +## Robolectric +With [Robolectric](https://github.com/robolectric/robolectric) you can write tests like this: ``` @RunWith(AndroidJUnit4.class) public class MyActivityTest { @@ -86,7 +86,7 @@ public class MyActivityTest { } ``` -### Running Roboelectric tests +### Running Robolectric tests 1. Go to **Edit Configuration** in Android Studio Screenshot 2020-04-13 at 2 51 02 PM @@ -97,7 +97,7 @@ public class MyActivityTest { Screenshot 2020-04-13 at 3 18 39 PM -4. Press `OK` to run the test cases in roboelectric. +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. @@ -176,9 +176,9 @@ A test case can never be called complete without assertions and hence it is impo ### Using isCompletelyDisplayed and isDisplayed * **isCompletelyDisplayed** : Returns a matcher which only accepts a view whose height and width fit perfectly within the currently displayed region of this view. -* There exist views (such as ScrollViews) whose height and width are larger then the physical device screen by design. Such views will _never_ be completely displayed. +* There exist views (such as ScrollViews) whose height and width are larger than the physical device screen by design. Such views will _never_ be completely displayed. * **isDisplayed** : Returns a matcher that matches {@link View}s that are currently displayed on the screen to the user. -* Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater then the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed +* Note: isDisplayed will select views that are partially displayed (eg: the full height/width of the view is greater than the height/width of the visible rectangle). If you wish to ensure the entire rectangle this view draws is displayed to the user use isCompletelyDisplayed ### Using swipeLeft/Right and using scrollToPage: * Espresso release contains new left and right swiping actions: swipeLeft() and swipeRight(). They both are really useful when you'd like to swipe between activity fragments, tab layouts or any other UI elements. @@ -231,17 +231,19 @@ fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { Espresso test might execute some checks while the app is doing some operations in the background threads, due to which the test may have no much content to interact with, therefore it throws an exception. -We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like `SystemClock.sleep(period)` or `Thread.sleep(period)` . Yet with this approach, we might end up having inflexible and slow tests +We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like `SystemClock.sleep(period)` or `Thread.sleep(period)`. Yet with this approach, we might end up having inflexible and slow tests. -In order to solve this in a clean and effective manner, we have integrated IdlingResources in the application, [CountingIdlingResource](https://android.jlelse.eu/integrate-espresso-idling-resources-in-your-app-to-build-flexible-ui-tests-c779e24f5057) is one of the easiest to understand resource that comes bundled within the framework. +In order to solve this in a clean and effective manner, we have created a [TestCoroutineDispatchers](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt) using which we can provide test cases required delay weather on robolectric or espresso, both has its own implementation. +1. [TestCoroutineDispatchersEspressoImpl](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchersEspressoImpl.kt) - Here, we are using the real-time-clock and hooking the idling resources to monitor background coroutines. +2. [TestCoroutineDispatchersRobolectricImpl](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchersRobolectricImpl.kt) - Here, we had implemented a way using which we can run test cases in a coordinated, deterministic, and thread-safe way. -# Tips to run testcases in both Expresso and Roboelectric +# Tips to run testcases in both Espresso and Robolectric The project contains two kinds of tests, unit tests using Robolectric and instrumentation tests using Espresso. Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. -Sometimes it may happen that testcases pass in Expresso but fail in Roboelectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. +Sometimes it may happen that testcases pass in Espresso but fail in Robolectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. Following are the different ways you can try to pass the testcases. @@ -262,12 +264,22 @@ at least 90 percent of the view's area is displayed to the user. Apply the `@Config(qualifiers = "port-xxhdpi")` annotation to your test package/class/method [reference](http://robolectric.org/device-configuration/). +3. Along with the qualifiers, we are using our own application class rather than depending on the main application class which in our codebase is `OppiaApplication`. + + `@Config(application = ExplorationActivityTest.TestApplication::class)` + +4. We can inject `TestCoroutineDispatchers` and provide a delay as per the requirement. +``` + @Inject + lateinit var testCoroutineDispatchers: TestCoroutineDispatchers +``` + ``` @Test - @Config(qualifiers = "port-xxhdpi") + @Config(application = ProfileProgressActivityTest.TestApplication::class , qualifiers = "port-xxhdpi") fun testProfileProgressActivity_recyclerViewIndex0_clickViewAll_opensRecentlyPlayedActivity() { launch(createProfileProgressActivityIntent(internalProfileId)).use { - waitForTheView(withText("Sean")) + testCoroutineDispatchers.runCurrent() onView(atPositionOnView(R.id.profile_progress_list, 0, R.id.view_all_text_view)).check( matches( withText("View All") From e8894e76cae2911c8dafd29633b0fad30e356feb Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 28 Sep 2020 14:35:11 +0530 Subject: [PATCH 111/374] update page --- Oppia-Android-Testing.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index b1abed4751a..db019b2562b 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -227,25 +227,22 @@ fun testHomeActivity_recyclerViewIndex1_promotedCard_storyNameIsCorrect() { } ``` -## Integrate Espresso Idling Resources in the app to build flexible UI tests +# Tips to run test cases in both Espresso and Robolectric +The project contains two kinds of tests, unit tests using Robolectric and instrumentation tests using Espresso. + +Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. Espresso test might execute some checks while the app is doing some operations in the background threads, due to which the test may have no much content to interact with, therefore it throws an exception. -We can solve this by adding an artificial delay (solution illustrated in some of SO answers to this issue) either by adding code like `SystemClock.sleep(period)` or `Thread.sleep(period)`. Yet with this approach, we might end up having inflexible and slow tests. +While writing espresso test cases we should never use `Thread.sleep(period)` as this approach, we might end up having inflexible and slow tests. + +Sometimes it may happen that test cases pass in Espresso but fail in Robolectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. In order to solve this in a clean and effective manner, we have created a [TestCoroutineDispatchers](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchers.kt) using which we can provide test cases required delay weather on robolectric or espresso, both has its own implementation. 1. [TestCoroutineDispatchersEspressoImpl](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchersEspressoImpl.kt) - Here, we are using the real-time-clock and hooking the idling resources to monitor background coroutines. 2. [TestCoroutineDispatchersRobolectricImpl](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/TestCoroutineDispatchersRobolectricImpl.kt) - Here, we had implemented a way using which we can run test cases in a coordinated, deterministic, and thread-safe way. - -# Tips to run testcases in both Espresso and Robolectric -The project contains two kinds of tests, unit tests using Robolectric and instrumentation tests using Espresso. - -Both frameworks can create the same kinds of tests, the difference is how they’re executed. Robolectric tests are run on a standard JVM, which makes them very fast to run, but there are some limitations on what can be tested. Espresso tests are run on a device (either actual or virtual) so they more closely resemble the actual running system, but they are a lot slower to run. - -Sometimes it may happen that testcases pass in Espresso but fail in Robolectric. Direct dependencies on Robolectric causes build failures when trying to build the test with Espresso. - -Following are the different ways you can try to pass the testcases. +Following are the different ways you can try to pass the test cases. ### Performance Exception/Runtime Exception Failure: @@ -260,7 +257,7 @@ at least 90 percent of the view's area is displayed to the user. **Example:** `onView(withId(R.id.walkthrough_welcome_next_button)).perform(scrollTo(), click())` -2. Sometimes test is rejected on small screen devices. Use Robolectric `qualifiers` property that sets up the Android simulation environment with a corresponding configuration. The system’s Configuration, Display and DisplayMetrics objects will all reflect the specified configuration, the locale will be set, and appropriate resources will be selected. +2. Sometimes the test is rejected on small screen devices. Use Robolectric `qualifiers` property that sets up the Android simulation environment with a corresponding configuration. The system’s Configuration, Display and DisplayMetrics objects will all reflect the specified configuration, the locale will be set, and appropriate resources will be selected. Apply the `@Config(qualifiers = "port-xxhdpi")` annotation to your test package/class/method [reference](http://robolectric.org/device-configuration/). From 119898f633c39a260eabb2e51af7667af25e08a1 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 30 Sep 2020 01:47:36 +0530 Subject: [PATCH 112/374] Updated SLoP 2020 (markdown) --- SLoP-2020.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/SLoP-2020.md b/SLoP-2020.md index 1014e9b6fa7..f7eab62b416 100644 --- a/SLoP-2020.md +++ b/SLoP-2020.md @@ -9,8 +9,8 @@ - [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” 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 “**DSC \ point**”. + - 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-\**”. 5. If you would like to take up issues that are not part of above labels or do not have a score label, please contact your onboarding mentor and request for the score for the issue. Your mentor will assign a score to the issue and communicate the same to the org admins. The org admins will then add the relevant label to the issue. ### Expectations from students @@ -37,5 +37,37 @@ If you cannot review PRs in a 24 hr time frame for an extended period, consider 5. The level of mentoring is expected to be slightly higher than that of hacktoberfest and dealing with new contributors but less than that of GSoC. Please note: Apart from the standard “24 hr review” rule, there is no formal time commitment for a mentor. +### Scoring Policy +The set of points allowed to be allocated to each issue are: +* 5 Points - Level 1 +* 25 Points - Level 2 +* 75 Points - Level 3 +* 150 Points - Level 4 + +5 Points +* Very Easy Issue - Beginner level +* GitHub Issue Label: SLoP-5 +* Example: 1 line change in code, Typo fix in Documentation + +25 Points +* Easy-Moderate issue +* GitHub Issue Label: SLoP-25 +* Example: A small bug fix, minor refactor or contributions spanning to +few lines of code + +75 Points +* Moderately Difficult issue +* GitHub Issue Label: SLoP-75 +* Example: Addition of small feature, contribution that has fair bit of +learning involved + +150 Points +* Difficult Issue +* GitHub Issue Label: SLoP-150 +* Example: Major bug fix, a contribution that requires heavy effort and +research, Good new feature implemented + +NOTE: At any point before PR gets merged mentors can increase or decrease points. + ### Escalation Policy If there are any SLoP-related doubts / concerns, please reach out to the org admins (@kevintab95, @rt4914, @BenHenning). From d47f1da1852de1516548ff105732f50c2119678e Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 12 Oct 2020 22:58:38 -0700 Subject: [PATCH 113/374] Add link to writing tests presentation slides. --- Oppia-Android-Testing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index db019b2562b..b4a5bc8aac0 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -9,6 +9,9 @@ In Oppia we are considering: * 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: From 5bf08331f33b97028a79a32746d1cab930ed40f3 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 30 Nov 2020 14:55:46 -0800 Subject: [PATCH 114/374] Add section on dependency injection with link to presentation slides. --- Overview-of-the-Oppia-Android-codebase-and-architecture.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index fc803bb59a5..f16dcb1ba09 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -89,4 +89,8 @@ Here is an example of how to traverse the codebase. (Note that the examples belo 6. The button click can be handled by data-binding a function (`clickDummyButton`) to the XML. That function will be created in the `TopicInfoViewModel`. From the **App Architecture** section, we know that the ViewModel does not handle the logic, and the presenter is responsible for the logic part. 7. So, 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 the completion of the entire task, with all the code blocks in the correct files. \ No newline at end of file +Following these steps would lead to the completion of the entire task, with all the code blocks in the correct files. + +## Dependency Injection + +Oppia Android uses Dagger 2 for dependency injection. For an overview on 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 From 9f5a5ec61ab8861415a6abea4a2aa835a0851c57 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 1 Dec 2020 15:43:42 -0800 Subject: [PATCH 115/374] Clarify that contributors should be cloning from their fork, not the main repository. --- Android-Studio-UI-based-Github-workflow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index b1e01f526d4..f4d88b56391 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -1,6 +1,6 @@ # Clone Oppia-Android using Android Studio -Go to https://github.com/oppia/oppia-android. -Click on **Clone or download** and copy the link. +Navigate to your fork, e.g. ``https://github.com//oppia-android``. +Click on **Clone or download** and copy the link (the URL will look different since you should be using your fork, **not** https://github.com/oppia/oppia-android). 1 From e9fe3cba80c2b4357599f0f64c2e69acb5d1f3f2 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 1 Dec 2020 16:01:47 -0800 Subject: [PATCH 116/374] Switch our own instructions for upstream merge with GitHub since it includes steps we left out. --- Fork-and-Clone-Oppia-Android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index 2992d2c0293..f7761085aad 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -18,4 +18,4 @@ _For a detailed explanation of the fork-and-clone process, please see this [GitH ## Updating your local repository -You can download the latest contents of the main Oppia Android repository using `git fetch upstream`, and you can also access your forked version using `git fetch origin`. (Usually, you'll want to do the former.) +If you need to update your local branch with the latest changes in the main Oppia Android repository on develop (e.g. in cases when your PR is showing extra commits that you didn't create), follow the steps listed [here](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). \ No newline at end of file From 2665a7411bb6b4834ccf536e03116b1093c95165 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 1 Dec 2020 16:05:01 -0800 Subject: [PATCH 117/374] Clarify that we use develop not main. --- Fork-and-Clone-Oppia-Android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index f7761085aad..9ab01c91d30 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -18,4 +18,4 @@ _For a detailed explanation of the fork-and-clone process, please see this [GitH ## Updating your local repository -If you need to update your local branch with the latest changes in the main Oppia Android repository on develop (e.g. in cases when your PR is showing extra commits that you didn't create), follow the steps listed [here](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). \ No newline at end of file +If you need to update your local branch with the latest changes in the main Oppia Android repository on develop (e.g. in cases when your PR is showing extra commits that you didn't create), follow the steps listed [here](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). Note that Oppia Android uses 'develop' not 'main' for its mainline branch. \ No newline at end of file From b7c1fb7046e8ef8d6018b0e7eafef0312902df22 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 15 Dec 2020 14:28:09 -0800 Subject: [PATCH 118/374] Mention that we use Kotlin Android style guide, not Google Java anymore. --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index e23ee000312..fbd21e86595 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -1,7 +1,7 @@ Please follow the following style rules when writing code, in order to minimize unnecessary back-and-forth during code review. ## General -- In general, we follow [Google's Java style guide](https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation) (but please look at it from a Kotlin perspective). +- 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. From dd7175645beb45758fa70e3db9f70b266a416f9e Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 15 Dec 2020 14:30:57 -0800 Subject: [PATCH 119/374] Rermove/clarify TBDs. We still need to add a presubmit script in the future. --- Home.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Home.md b/Home.md index bb00b955123..8b0fa244381 100644 --- a/Home.md +++ b/Home.md @@ -51,8 +51,8 @@ The following instructions describe how to make a one-off code change using a fe * 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 **[TBD]** and that it is well-tested. - * Ensure that the code has no lint errors and passes all automated tests by running the presubmit script **[TBD]**. + * 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: @@ -69,11 +69,10 @@ The following instructions describe how to make a one-off code change using a fe * 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 **[TBD]**, ensuring that your PR description includes the issue number (e.g. "This PR fixes issue #bugnum" or "This PR fixes part of issue #bugnum"). + * 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".) - * After a while, check your PR to see whether the Travis checks have passed. If not, follow the instructions at "[If your build fails...](https://github.com/oppia/oppia/wiki/If-your-build-fails)". **[TBD]** * 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').** From fa6d80a09da3db2e53b9f8afd06ee0d245aaee6f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 28 Dec 2020 10:47:12 +0530 Subject: [PATCH 120/374] Created RTL Guidlines (markdown) --- RTL-Guidlines.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 RTL-Guidlines.md diff --git a/RTL-Guidlines.md b/RTL-Guidlines.md new file mode 100644 index 00000000000..2b4bdd25038 --- /dev/null +++ b/RTL-Guidlines.md @@ -0,0 +1,6 @@ +# Testing app for RTL Layouts +To test any screen for RTL language follow these steps: +1. Enable [`Developer Options`](https://developer.android.com/studio/debug/dev-options) on your device. +2. Set language to `Arabic [XB]` or `cibarA [XB]` with the help of this [link](https://developer.android.com/guide/topics/resources/pseudolocales). + +Make this language as primary language and now open the oppia app. You will notice that all characters appear from right-to-left similar to what `Arabic` languages follow. \ No newline at end of file From da657967ba0f6d9b0489b6d3dbf1188ddda1577a Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 28 Dec 2020 10:47:29 +0530 Subject: [PATCH 121/374] Updated RTL Guidlines (markdown) --- RTL-Guidlines.md => RTL-Guidelines.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename RTL-Guidlines.md => RTL-Guidelines.md (100%) diff --git a/RTL-Guidlines.md b/RTL-Guidelines.md similarity index 100% rename from RTL-Guidlines.md rename to RTL-Guidelines.md From 83ead189b4b82c662b5f2e217686f0b038c4e18f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 28 Dec 2020 10:59:47 +0530 Subject: [PATCH 122/374] Updated RTL Guidelines (markdown) --- RTL-Guidelines.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/RTL-Guidelines.md b/RTL-Guidelines.md index 2b4bdd25038..46592db1606 100644 --- a/RTL-Guidelines.md +++ b/RTL-Guidelines.md @@ -3,4 +3,7 @@ To test any screen for RTL language follow these steps: 1. Enable [`Developer Options`](https://developer.android.com/studio/debug/dev-options) on your device. 2. Set language to `Arabic [XB]` or `cibarA [XB]` with the help of this [link](https://developer.android.com/guide/topics/resources/pseudolocales). -Make this language as primary language and now open the oppia app. You will notice that all characters appear from right-to-left similar to what `Arabic` languages follow. \ No newline at end of file +Make this language as primary language and now open the oppia app. You will notice that all characters appear from right-to-left similar to what `Arabic` languages follow. +The screen will look something like this: + + From 7dd71acf36b7a6aca9fa198998fa4059bd5412aa Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 29 Dec 2020 09:58:49 +0530 Subject: [PATCH 123/374] Updated RTL Guidelines (markdown) --- RTL-Guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RTL-Guidelines.md b/RTL-Guidelines.md index 46592db1606..f1814c72bc8 100644 --- a/RTL-Guidelines.md +++ b/RTL-Guidelines.md @@ -3,7 +3,7 @@ To test any screen for RTL language follow these steps: 1. Enable [`Developer Options`](https://developer.android.com/studio/debug/dev-options) on your device. 2. Set language to `Arabic [XB]` or `cibarA [XB]` with the help of this [link](https://developer.android.com/guide/topics/resources/pseudolocales). -Make this language as primary language and now open the oppia app. You will notice that all characters appear from right-to-left similar to what `Arabic` languages follow. +Make this language as primary language from your `Language Preferences` in `Settings` and now open the oppia app. You will notice that all characters appear from right-to-left similar to what `Arabic` languages follow. The screen will look something like this: From 65f48e751bf183b1df13107f3db8beb404eb4fbb Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 31 Dec 2020 17:10:24 +0530 Subject: [PATCH 124/374] add point for setup script --- Home.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 8b0fa244381..746eda2c598 100644 --- a/Home.md +++ b/Home.md @@ -27,7 +27,18 @@ Please follow these steps for initial setup of the project on your local machine or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) - +3. For Mac or Linux + 1. Open terminal + 2. Move to `opensource/oppia-android/` + 3. Run a script `bash scripts/setup.sh` + + For Windows + 1. Install [Git Bash Command Line](https://gitforwindows.org/) + 2. Open gt bash command line + 3. Move to `opensource/oppia-android/` + 4. Run a script `bash scripts/setup.sh` + +This will create a folder `opensource/oppia-android-tools`. ## Instructions for making a code change From e8fcd08737c664761632cd91c7b452464dd83ab2 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 31 Dec 2020 17:33:40 +0530 Subject: [PATCH 125/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 746eda2c598..13d294c89b6 100644 --- a/Home.md +++ b/Home.md @@ -38,7 +38,7 @@ Please follow these steps for initial setup of the project on your local machine 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` -This will create a folder `opensource/oppia-android-tools`. +This will create a folder `opensource/oppia-android-tools`. This will set up `ktlint` executable file which is used to validate Kotlin's file formatting when sending a pull request. ## Instructions for making a code change From e8e2e8f6286c5590d0e71bd95855d8296982177d Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 4 Jan 2021 09:08:12 +0530 Subject: [PATCH 126/374] formatting and update espresso test case example --- Oppia-Android-Testing.md | 71 ++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 31 deletions(-) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index b4a5bc8aac0..4649f558bd1 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -28,12 +28,12 @@ For Example: 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) ``` @@ -43,14 +43,14 @@ 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() ``` @@ -72,7 +72,7 @@ If you follow this conversion, the Android build system runs your tests on the c ## Robolectric With [Robolectric](https://github.com/robolectric/robolectric) you can write tests like this: -``` +```java @RunWith(AndroidJUnit4.class) public class MyActivityTest { @@ -105,25 +105,31 @@ public class MyActivityTest { ## Espresso Use [Espresso](https://developer.android.com/training/testing/espresso) to write concise, beautiful, and reliable Android UI tests. Example JUnit4 test using Rules: -``` -@RunWith(AndroidJUnit4::class) -class SplashActivityTest { - @get:Rule - var activityTestRule: ActivityTestRule = ActivityTestRule( - SplashActivity::class.java, /* initialTouchMode= */ true, /* launchActivity= */ false - ) +```kotlin +@RunWith(AndroidJUnit4::class) +class PinPasswordActivityTest { @Before fun setUp() { Intents.init() } - @Test - fun testSplashActivity_initialOpen_routesToHomeActivity() { - activityTestRule.launchActivity(null) - intended(hasComponent(ProfileActivity::class.java.name)) - } + @Test + fun testPinPasswordActivityWithAdmin_inputCorrectPin_checkOpensHomeActivity() { + ActivityScenario.launch( + PinPasswordActivity.createPinPasswordActivityIntent( + context, + adminPin, + adminId + ) + ).use { + testCoroutineDispatchers.runCurrent() + onView(withId(R.id.input_pin)).perform(editTextInputAction.appendText("12345")) + testCoroutineDispatchers.runCurrent() + intended(hasComponent(HomeActivity::class.java.name)) + } + } @After fun tearDown() { @@ -135,12 +141,12 @@ class SplashActivityTest { ### How to use View Matchers, View Actions and View Assertions in Espresso? Espresso has many ViewMatcher options which are very effective in uniquely locate UI element. You can also combine and create a combination of View Matchers to find element uniquely. -The View Matcher is written like onView(ViewMatcher) which are commonly used. There are two types of actions that can be performed on View those are - +The View Matcher is written like `onView(ViewMatcher)` which are commonly used. There are two types of actions that can be performed on View those are - -onView(ViewMatcher).perform(ViewAction) +`onView(ViewMatcher).perform(ViewAction)` -onView(ViewMatcher).check(ViewAssertion) -``` +`onView(ViewMatcher).check(ViewAssertion)` +```kotlin // frequently used matchers // using resource id onView(withId(R.id.my_view)) @@ -153,7 +159,7 @@ onView(withHint("Sample_text")) //return TextView with links onView(hasLinks()) -//UI property matchers are mostly used in combination +// UI property matchers are mostly used in combination // withId(R.id.my_view) is a ViewMatcher // click() is a ViewAction // matches(isDisplayed()) is a ViewAssertion @@ -187,7 +193,7 @@ A test case can never be called complete without assertions and hence it is impo * Espresso release contains new left and right swiping actions: swipeLeft() and swipeRight(). They both are really useful when you'd like to swipe between activity fragments, tab layouts or any other UI elements. * At times, GeneralSwipeAction can become unreliable because of its calculation varies on different screen size or density, so it may not be suitable for ViewPager. Instead, we can use to scroll with [ViewPagerActions](https://developer.android.com/reference/android/support/test/espresso/contrib/ViewPagerActions) -``` +```kotlin @Test fun testOnboardingFragment_checkSlide1Description_isCorrect() { launch(OnboardingActivity::class.java).use { @@ -207,10 +213,13 @@ The espresso-contrib library provides a [RecyclerViewActions](https://github.com ### RecyclerViewMatcher Using the RecyclerViewMatcher under package ‘org.oppia.app.recyclerview’, you can perform actions on an item at a specific position in a RecyclerView, and also check that some content is contained within a descendant of a specific item. -``` +```kotlin @Test fun testHomeActivity_recyclerViewIndex3_clickTopicSummary_opensTopicActivity() { launch(HomeActivity::class.java).use { + onView(withId(R.id.home_recycler_view)).perform( + scrollToPosition(3) + ) onView(atPosition(R.id.home_recycler_view, 3)).perform(click()) intended(hasComponent(TopicActivity::class.java.name)) intended(hasExtra(TopicActivity.TOPIC_ACTIVITY_TOPIC_ID_ARGUMENT_KEY, TEST_TOPIC_ID_0)) @@ -249,12 +258,12 @@ Following are the different ways you can try to pass the test cases. ### Performance Exception/Runtime Exception Failure: -``` +```console androidx.test.espresso.PerformException: Error performing 'single click' on view 'with id: org.oppia.app:id/profile_progress_list'. Caused by: java.lang.RuntimeException: Action will not be performed because the target view does not match one or more of the following constraints: at least 90 percent of the view's area is displayed to the user. -```` +``` 1. Make ScrollView as a parent in XML file and use scrollTo() while performing click() in the test. **Example:** @@ -269,12 +278,12 @@ at least 90 percent of the view's area is displayed to the user. `@Config(application = ExplorationActivityTest.TestApplication::class)` 4. We can inject `TestCoroutineDispatchers` and provide a delay as per the requirement. -``` +```kotlin @Inject lateinit var testCoroutineDispatchers: TestCoroutineDispatchers ``` -``` +```kotlin @Test @Config(application = ProfileProgressActivityTest.TestApplication::class , qualifiers = "port-xxhdpi") fun testProfileProgressActivity_recyclerViewIndex0_clickViewAll_opensRecentlyPlayedActivity() { @@ -303,7 +312,7 @@ at least 90 percent of the view's area is displayed to the user. - Apply the LooperMode(PAUSED) annotation to your test package/class/method [reference](http://robolectric.org/blog/2019/06/04/paused-looper/). -``` +```kotlin @LooperMode(LooperMode.Mode.PAUSED) @Test fun testAdministratorControlsFragment_clickOkButtonInLogoutDialog_opensProfileActivity() { @@ -320,12 +329,12 @@ at least 90 percent of the view's area is displayed to the user. 2. Choosing the right matcher to check your view. - The doesNotExist() view assertion checks if a view exists in the current view hierarchy. -``` +```kotlin onView(withId(R.id.made_up_view_id)).check(doesNotExist()) ``` - We may have to test if the view is Visible or Gone and if `isDisplayed()` doesn't work, we make use of `withEffectiveVisibility(ViewMatchers.Visibility.VISIBLE))`. This matcher checks how the visibility of a view is set in the code. -``` +```kotlin onView(allOf(withId(R.id.ivPlayPauseAudio),withEffectiveVisibility(ViewMatchers.Visibility.VISIBLE))) ``` From 8b21920f9202f7c8e56dd29455de8c0888a79561 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 4 Jan 2021 09:44:57 +0530 Subject: [PATCH 127/374] version update --- Ktlint-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index 6d81a606ffc..f3a3b033071 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -2,7 +2,7 @@ Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation). Note that we specifically recommend using the command-line interface, not the Gradle integration. # Commands -* `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.0`. +* `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.1`. * `ktlint --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` From b6e0102b726765ae540d536e67552c624b0b6fa9 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 13 Jan 2021 13:35:00 -0800 Subject: [PATCH 128/374] Fix ending for custom view file names. --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index fbd21e86595..03801ef89db 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -40,7 +40,7 @@ NOTE: This does not guarantee 100% formatting of code as per guidelines but will - 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 ``_activity.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. From 2b929a47cdf00d7f9f62e0397c078a1a8e24c84b Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 13 Jan 2021 13:35:20 -0800 Subject: [PATCH 129/374] Add underscore prefix to fragment file name style for consistency. --- Coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index 03801ef89db..c64fdfbbc69 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -39,7 +39,7 @@ NOTE: This does not guarantee 100% formatting of code as per guidelines but will ## 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``) + - 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``) From e66ee57378b72a87f5e1ac15f50a209ee35cfe3a Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Sat, 16 Jan 2021 03:37:08 +0530 Subject: [PATCH 130/374] Removed install linters as pre push come --- Home.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/Home.md b/Home.md index 13d294c89b6..f29b23a5ebb 100644 --- a/Home.md +++ b/Home.md @@ -13,9 +13,6 @@ We're still working on setting up the basics of the Android project, but we are ## Prerequisites 1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. 2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). -3. Install the following linters: - * [Ktlint](https://github.com/oppia/oppia-android/wiki/Ktlint-Guide) - * [Bufbuild](https://github.com/oppia/oppia-android/wiki/Buf-Guide) ## Installation From 0b6a6f99115c55895708e6c5d813b54d718aa202 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 18 Jan 2021 09:37:03 +0530 Subject: [PATCH 131/374] error and solution for pre-push --- Home.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Home.md b/Home.md index f29b23a5ebb..bd347948b7d 100644 --- a/Home.md +++ b/Home.md @@ -29,12 +29,16 @@ Please follow these steps for initial setup of the project on your local machine 2. Move to `opensource/oppia-android/` 3. Run a script `bash scripts/setup.sh` +If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. + For Windows 1. Install [Git Bash Command Line](https://gitforwindows.org/) 2. Open gt bash command line 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` +If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. + This will create a folder `opensource/oppia-android-tools`. This will set up `ktlint` executable file which is used to validate Kotlin's file formatting when sending a pull request. ## Instructions for making a code change From e14e132a21093c415f84448995ca2ae919ef55aa Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 18 Jan 2021 09:40:11 +0530 Subject: [PATCH 132/374] nit formatting --- Home.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Home.md b/Home.md index bd347948b7d..7cdd2433fe6 100644 --- a/Home.md +++ b/Home.md @@ -20,23 +20,20 @@ Please follow these steps for initial setup of the project 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. -2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. - - or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) +2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) 3. For Mac or Linux 1. Open terminal 2. Move to `opensource/oppia-android/` 3. Run a script `bash scripts/setup.sh` -If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. - For Windows 1. Install [Git Bash Command Line](https://gitforwindows.org/) 2. Open gt bash command line 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` +If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. This will create a folder `opensource/oppia-android-tools`. This will set up `ktlint` executable file which is used to validate Kotlin's file formatting when sending a pull request. From 1853b4b8a1e056509b3d7292c298c52550635928 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Fri, 22 Jan 2021 15:13:41 +0530 Subject: [PATCH 133/374] nit formatting --- Home.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/Home.md b/Home.md index 7cdd2433fe6..efa65a56d76 100644 --- a/Home.md +++ b/Home.md @@ -22,19 +22,20 @@ Please follow these steps for initial setup of the project on your local machine 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) -3. For Mac or Linux - 1. Open terminal - 2. Move to `opensource/oppia-android/` - 3. Run a script `bash scripts/setup.sh` - - For Windows - 1. Install [Git Bash Command Line](https://gitforwindows.org/) - 2. Open gt bash command line - 3. Move to `opensource/oppia-android/` - 4. Run a script `bash scripts/setup.sh` - -If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
-If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. +3. Run the script + - For Mac or Linux + 1. Open terminal + 2. Move to `opensource/oppia-android/` + 3. Run a script `bash scripts/setup.sh` + + - For Windows + 1. Install [Git Bash Command Line](https://gitforwindows.org/) + 2. Open gt bash command line + 3. Move to `opensource/oppia-android/` + 4. Run a script `bash scripts/setup.sh` + + - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
+ - If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. This will create a folder `opensource/oppia-android-tools`. This will set up `ktlint` executable file which is used to validate Kotlin's file formatting when sending a pull request. From 9c99ceb7b65638881a0f06250bd6478b03d17ae8 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 25 Jan 2021 10:26:01 +0530 Subject: [PATCH 134/374] added a step to setup java --- Home.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index efa65a56d76..d9acb90fe8d 100644 --- a/Home.md +++ b/Home.md @@ -22,7 +22,10 @@ Please follow these steps for initial setup of the project on your local machine 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) -3. Run the script +3. Set up `Java` with the latest version. Install from [here](https://www.java.com/en/download/).
+If you are on Windows, please set up the environment path correctly for `Java`. + +4. Run the script - For Mac or Linux 1. Open terminal 2. Move to `opensource/oppia-android/` From 62e7c25bbe4f2b08a93c2e1ea734661ba1eda7c1 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 25 Jan 2021 15:46:41 +0530 Subject: [PATCH 135/374] Created Oppia-Bazel Guide (markdown) --- Oppia-Bazel-Guide.md | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 Oppia-Bazel-Guide.md diff --git a/Oppia-Bazel-Guide.md b/Oppia-Bazel-Guide.md new file mode 100644 index 00000000000..af51871ae93 --- /dev/null +++ b/Oppia-Bazel-Guide.md @@ -0,0 +1,53 @@ +## Overview +Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. It uses a human-readable, high-level build language. + + +## Concepts and Terminology +**[Workspace](https://github.com/oppia/oppia-android/blob/develop/WORKSPACE)**
+A workspace is a directory where we add targetted 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, +) +``` + From 44cafa8f9408323c0fddcd607f1cf7491264b711 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 28 Jan 2021 18:09:26 +0530 Subject: [PATCH 136/374] Created Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 44 +++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 Accessibility-(A11y)-Guide.md diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md new file mode 100644 index 00000000000..2a17851d418 --- /dev/null +++ b/Accessibility-(A11y)-Guide.md @@ -0,0 +1,44 @@ +## Overview +Accessibility is an important part of Oppia to ensure that the app is accessible by everyone. Some common conditions that affect a person's use of an Android device are: +* blindness / low vision +* deafness / impaired hearing +* cognitive disabilities +* confined motor skills +* color blindness, etc. + +Making sure that the Oppia app is accessible by all resonates with overall Oppia's mission: **to help anyone learn anything they want in an effective and enjoyable way.** + +Note: In short we can write Accessibility as **A11Y**. + +## Useful Resources +* [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) +* [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) + +## Using a11y scanner in android +[Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) scans your screen and provides suggestions to improve the accessibility of your app, based on: +* Content labels +* Touch target size +* Clickable items +* Text and image contrast + +### For real device +1. Go to Google Play Store +2. Download/Install **Accessibility Scanner** app + +### For mobile emulator +1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. +2. Open "Play Store" app and sign-in. +3. Download/Install **Accessibility Scanner** app + +### How to use +1. After installation, open Settings +2. Search **Accessibility Scanner**, click on it. +3. Turn on **Use Accessibility Scanner** -> **Allow** +4. You will notice a blue colored floating button with tick/check icon. +5. Open **Oppia** app. +6. Now on any screen inside app click on the floating button and either record or take snapshot. + +**Result**: You will notice that the scanner analyses the screen and give errors if there are any or else it will show that no errors were found. + +### Using Talkback in android + From 7ac4e3fad2fa37bbca260138ed8230b29822762f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 28 Jan 2021 18:18:02 +0530 Subject: [PATCH 137/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 2a17851d418..6476be2d58f 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -13,6 +13,7 @@ Note: In short we can write Accessibility as **A11Y**. ## Useful Resources * [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) * [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) +* [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) ## Using a11y scanner in android [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) scans your screen and provides suggestions to improve the accessibility of your app, based on: @@ -21,16 +22,16 @@ Note: In short we can write Accessibility as **A11Y**. * Clickable items * Text and image contrast -### For real device +#### For real device 1. Go to Google Play Store 2. Download/Install **Accessibility Scanner** app -### For mobile emulator +#### For mobile emulator 1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. 2. Open "Play Store" app and sign-in. 3. Download/Install **Accessibility Scanner** app -### How to use +#### How to use 1. After installation, open Settings 2. Search **Accessibility Scanner**, click on it. 3. Turn on **Use Accessibility Scanner** -> **Allow** @@ -40,5 +41,22 @@ Note: In short we can write Accessibility as **A11Y**. **Result**: You will notice that the scanner analyses the screen and give errors if there are any or else it will show that no errors were found. -### Using Talkback in android +## Using Talkback in android +TalkBack is the Google **screen reader** included on Android devices. TalkBack gives you spoken feedback so that you can use your device without looking at the screen. +#### For real device +1. Go to Google Play Store +2. Download/Install **Android Accessibility Suite** app + +#### For mobile emulator +1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. +2. Open "Play Store" app and sign-in. +3. Download/Install **Android Accessibility Suite** app + +#### How to use +1. After installation, open Settings +2. Search **Talkback**, click on it. +3. Read all the instructions written on the screen as using Talkback requires specific steps. +4. Turn on **Use Service** -> **Allow** + +Now you can use talkback. For more information visit [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677). From b15135dcf52cd68b7e7847147805672adc5b0c53 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 2 Feb 2021 09:52:04 +0530 Subject: [PATCH 138/374] Added Installation --- Oppia-Bazel-Guide.md | 59 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/Oppia-Bazel-Guide.md b/Oppia-Bazel-Guide.md index af51871ae93..e48181ed2eb 100644 --- a/Oppia-Bazel-Guide.md +++ b/Oppia-Bazel-Guide.md @@ -2,6 +2,65 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. It uses a human-readable, high-level build language. +## Installation +**We recommend contributor having Windows OS, not to follow this installation guide as Oppia-Bazel doesn't support on Windows OS as for now.**
+For Linux or macOS, install Bazel from [here](https://docs.bazel.build/versions/master/install.html). + +After installing the original Bazel version, you need to setup Oppia's Bazel version.
+1. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
+ - Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
+ - macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` + +2. Clone https://github.com/oppia/bazel (note that this is very large and will take a bit to download) to a specific directory,
e.g.: + `git clone https://github.com/oppia/bazel oppia-bazel` + +3. Move you command line head to oppia-bazel dir
`cd ~/oppia-bazel` + +4. Run the command to extract folders (note that this command will probably take 5-10 minutes)
`bazel build //src:bazel //tools/android/runtime_deps:android_tools.tar.gz` + +5. Create dir if it is not created from the above command
`mkdir android_tools` + +6. `tar -xf bazel-bin/tools/android/runtime_deps/android_tools.tar.gz -C ./android_tools` + +7. `cp ~/oppia-bazel/bazel-bin/src/bazel ./bazel` + +8. Linux : `echo build --override_repository=android_tools=~/oppia-bazel/android_tools > ~/.bazelrc`
+ + macOS: `echo build --override_repository=android_tools=../oppia-bazel/android_tools > ../oppia-bazel/.bazelrc` + +#### Possible Error: +``` +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. + +After the installation completes you can build the app using Bazel. Move you command line head to the `~/opensource/oppia-android` and run the below bazel command: + +#### Building the app + +``` +~/oppia-bazel/bazel build //:oppia +``` + +#### Building + installing the app + +``` +~/oppia-bazel/bazel mobile-install //:oppia +``` + +#### Running specific module (app) Robolectric tests + +``` +~/oppia-bazel/bazel test //app/... +``` + +#### Running all Robolectric tests (slow) + +``` +~/oppia-bazel/bazel test //... +``` + ## Concepts and Terminology **[Workspace](https://github.com/oppia/oppia-android/blob/develop/WORKSPACE)**
A workspace is a directory where we add targetted 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. From 8d09bdac0754b803bb65e37c15543a36513e5635 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 4 Feb 2021 13:06:00 +0530 Subject: [PATCH 139/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 6476be2d58f..30c4aad5fb8 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -15,6 +15,16 @@ Note: In short we can write Accessibility as **A11Y**. * [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) * [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) +## Setup Play Store in mobile emulator +1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. +2. Open "Play Store" app and sign-in. + +## Setup Play Store in tablet emulator +By default tablet emulators do not contain **Play Store** app and therefore you will need to make some changes to make it available. +1. Follow the steps mentioned [here](https://stackoverflow.com/a/62680014). +2. Once above steps are done, start the emulator. +3. Open "Play Store" app and sign-in. + ## Using a11y scanner in android [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) scans your screen and provides suggestions to improve the accessibility of your app, based on: * Content labels @@ -53,6 +63,13 @@ TalkBack is the Google **screen reader** included on Android devices. TalkBack g 2. Open "Play Store" app and sign-in. 3. Download/Install **Android Accessibility Suite** app +#### For tablet emulator +By default tablet emulators do not contain **Play Store** app and therefore you will need to make some changes to make it available. +1. Follow the steps mentioned [here](https://stackoverflow.com/a/62680014). +2. Once above steps are done, start the emulator. +3. Open "Play Store" app and sign-in. +4. Download/Install **Android Accessibility Suite** app + #### How to use 1. After installation, open Settings 2. Search **Talkback**, click on it. From 5eec224763f43eb8afa358914fa7d63516686e5b Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 4 Feb 2021 13:08:37 +0530 Subject: [PATCH 140/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 49 ++++++++++------------------------- 1 file changed, 14 insertions(+), 35 deletions(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 30c4aad5fb8..f10d7fccafc 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -32,48 +32,27 @@ By default tablet emulators do not contain **Play Store** app and therefore you * Clickable items * Text and image contrast -#### For real device -1. Go to Google Play Store +### How to Use? +1. Open **Google Play Store** 2. Download/Install **Accessibility Scanner** app - -#### For mobile emulator -1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. -2. Open "Play Store" app and sign-in. -3. Download/Install **Accessibility Scanner** app - -#### How to use -1. After installation, open Settings -2. Search **Accessibility Scanner**, click on it. -3. Turn on **Use Accessibility Scanner** -> **Allow** -4. You will notice a blue colored floating button with tick/check icon. -5. Open **Oppia** app. -6. Now on any screen inside app click on the floating button and either record or take snapshot. +3. After installation, open Settings +4. Search **Accessibility Scanner**, click on it. +5. Turn on **Use Accessibility Scanner** -> **Allow** +6. You will notice a blue colored floating button with tick/check icon. +7. Open **Oppia** app. +8. Now on any screen inside app click on the floating button and either record or take snapshot. **Result**: You will notice that the scanner analyses the screen and give errors if there are any or else it will show that no errors were found. ## Using Talkback in android TalkBack is the Google **screen reader** included on Android devices. TalkBack gives you spoken feedback so that you can use your device without looking at the screen. -#### For real device -1. Go to Google Play Store -2. Download/Install **Android Accessibility Suite** app - -#### For mobile emulator -1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. -2. Open "Play Store" app and sign-in. -3. Download/Install **Android Accessibility Suite** app - -#### For tablet emulator -By default tablet emulators do not contain **Play Store** app and therefore you will need to make some changes to make it available. -1. Follow the steps mentioned [here](https://stackoverflow.com/a/62680014). -2. Once above steps are done, start the emulator. -3. Open "Play Store" app and sign-in. -4. Download/Install **Android Accessibility Suite** app - #### How to use -1. After installation, open Settings -2. Search **Talkback**, click on it. -3. Read all the instructions written on the screen as using Talkback requires specific steps. -4. Turn on **Use Service** -> **Allow** +1. Open **Google Play Store** +2. Download/Install **Android Accessibility Suite** app +3. After installation, open Settings +4. Search **Talkback**, click on it. +5. Read all the instructions written on the screen as using Talkback requires specific steps. +6. Turn on **Use Service** -> **Allow** Now you can use talkback. For more information visit [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677). From ba8f0f144b3cb80a4f0f9e78eade6aee63110f5a Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 4 Feb 2021 13:09:11 +0530 Subject: [PATCH 141/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index f10d7fccafc..1fd915cb2da 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -47,7 +47,7 @@ By default tablet emulators do not contain **Play Store** app and therefore you ## Using Talkback in android TalkBack is the Google **screen reader** included on Android devices. TalkBack gives you spoken feedback so that you can use your device without looking at the screen. -#### How to use +### How to use? 1. Open **Google Play Store** 2. Download/Install **Android Accessibility Suite** app 3. After installation, open Settings From c95ee5b2d13487bd1c2371d68b3bf22f3b55e6bb Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 4 Feb 2021 13:09:27 +0530 Subject: [PATCH 142/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 1fd915cb2da..022d779a99e 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -32,7 +32,7 @@ By default tablet emulators do not contain **Play Store** app and therefore you * Clickable items * Text and image contrast -### How to Use? +#### How to Use? 1. Open **Google Play Store** 2. Download/Install **Accessibility Scanner** app 3. After installation, open Settings @@ -47,7 +47,7 @@ By default tablet emulators do not contain **Play Store** app and therefore you ## Using Talkback in android TalkBack is the Google **screen reader** included on Android devices. TalkBack gives you spoken feedback so that you can use your device without looking at the screen. -### How to use? +#### How to use? 1. Open **Google Play Store** 2. Download/Install **Android Accessibility Suite** app 3. After installation, open Settings From cb545e36556b80ccbb5e21e334afe57f7e4bf6dc Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 4 Feb 2021 15:22:04 +0530 Subject: [PATCH 143/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 022d779a99e..7e9a90ac291 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -14,6 +14,7 @@ Note: In short we can write Accessibility as **A11Y**. * [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) * [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) * [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) +* [Display speech output as Text: Talkback](https://developer.android.com/guide/topics/ui/accessibility/testing#optional_talkback_developer_settings) ## Setup Play Store in mobile emulator 1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. From da74f47d40da8f88f92a0ec5fb8acfdbc294e0d0 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 9 Feb 2021 12:35:57 -0800 Subject: [PATCH 144/374] Rename page since we will have a separate page for Bazel guide. --- Oppia-Bazel-Guide.md => Oppia-Bazel-Setup-Instructions.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Oppia-Bazel-Guide.md => Oppia-Bazel-Setup-Instructions.md (100%) diff --git a/Oppia-Bazel-Guide.md b/Oppia-Bazel-Setup-Instructions.md similarity index 100% rename from Oppia-Bazel-Guide.md rename to Oppia-Bazel-Setup-Instructions.md From 482fe5fc1b7b87c5e201fbf95c8587312194f974 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Feb 2021 10:16:53 +0530 Subject: [PATCH 145/374] nit formatting --- Home.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/Home.md b/Home.md index d9acb90fe8d..22095d241ad 100644 --- a/Home.md +++ b/Home.md @@ -40,8 +40,6 @@ If you are on Windows, please set up the environment path correctly for `Java`. - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. -This will create a folder `opensource/oppia-android-tools`. This will set up `ktlint` executable file which is used to validate Kotlin's file formatting when sending a pull request. - ## Instructions for making a code change **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). From 849bfad023d006aa4e4e38bdbc41ffd3dedd9482 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Feb 2021 10:18:59 +0530 Subject: [PATCH 146/374] adding push details --- Android-Studio-UI-based-Github-workflow.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index f4d88b56391..bae5c20e410 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -58,6 +58,27 @@ Once you push a branch to Git you wont be able to rename it so, be sure about th 16 +If you are using Command line to push and if you have any file formatting issues, the code will not get pushed and it will show you an error like this: + + + +

+If you are using Android Studio VCS>Git to push the code, you will get the failure result like this: + + + +While using Android Studio VCS>Git you will not be able to see much detail on what the failure is, but you can try running below commands to checks the failure details: + +If you have failure related to kotlin, then use this script to get a detailed failure result: +``` +scripts/ktlint_lint_check.sh +``` + +If you have failure related to checkstyle/java, then use this script to get a detailed failure result: +``` +scripts/checkstyle_lint_check.sh +``` + ## Pull changes from Develop Once you push your new branch to "develop" you are ready to merge new changes from remote(upstream). Make sure the new branch's base branch is "develop" and the new branch is up-to-date with changes in "develop". From 5cab9c269451741a1e660acf6bb1805838dd0b3b Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Feb 2021 16:05:42 +0530 Subject: [PATCH 147/374] adding info to use git bash command line for windows --- Android-Studio-UI-based-Github-workflow.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index bae5c20e410..317568d85a5 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -69,6 +69,8 @@ If you are using Android Studio VCS>Git to push the code, you will get the failu While using Android Studio VCS>Git you will not be able to see much detail on what the failure is, but you can try running below commands to checks the failure details: +If you are using Windows, please use [Git Bash Command Line](https://gitforwindows.org/) to run these scripts. + If you have failure related to kotlin, then use this script to get a detailed failure result: ``` scripts/ktlint_lint_check.sh From 55f5bd08c548a9a01a73e34d46fb66320c2a2b49 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Feb 2021 16:28:26 +0530 Subject: [PATCH 148/374] added push fix title --- Android-Studio-UI-based-Github-workflow.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 317568d85a5..af86e78f55b 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -58,6 +58,8 @@ Once you push a branch to Git you wont be able to rename it so, be sure about th 16 +### How to Fix Push Failures? + If you are using Command line to push and if you have any file formatting issues, the code will not get pushed and it will show you an error like this: From 5e6c9bcbcc5c00e56de66babd22befe6df8c0680 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Feb 2021 16:29:40 +0530 Subject: [PATCH 149/374] adding link for pre-push fix --- Home.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Home.md b/Home.md index 22095d241ad..7c1ed6e29c3 100644 --- a/Home.md +++ b/Home.md @@ -39,6 +39,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. + - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) ## Instructions for making a code change From 9e916ee77404bc08b2b33363e76784fe4eb4e4d9 Mon Sep 17 00:00:00 2001 From: Srikanth K B Date: Wed, 10 Feb 2021 23:27:08 +0530 Subject: [PATCH 150/374] Updated info on google_checks.xml file download for Windows. --- Home.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Home.md b/Home.md index 7c1ed6e29c3..fbef36db3dd 100644 --- a/Home.md +++ b/Home.md @@ -33,12 +33,14 @@ If you are on Windows, please set up the environment path correctly for `Java`. - For Windows 1. Install [Git Bash Command Line](https://gitforwindows.org/) - 2. Open gt bash command line + 2. Open git bash command line 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` + 5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml) file. + 6. Copy it to directory where `Git` is installed (usually `C:/Program Files/Git/`). - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- - If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. + - If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) ## Instructions for making a code change From 2a2a202787e818b660796b82da120adf52c3e8a2 Mon Sep 17 00:00:00 2001 From: Srikanth K B Date: Wed, 10 Feb 2021 23:31:53 +0530 Subject: [PATCH 151/374] Updated comment link for checkstyle config file error --- Android-Studio-UI-based-Github-workflow.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index af86e78f55b..47dc361a46b 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -82,6 +82,7 @@ If you have failure related to checkstyle/java, then use this script to get a de ``` scripts/checkstyle_lint_check.sh ``` +Refer [comment](https://github.com/oppia/oppia-android/pull/2101#issuecomment-759331732) here for error related to `google_checks.xml` config file. ## Pull changes from Develop From 47984376f1ede1c82441c9943b40183700a98608 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 11 Feb 2021 09:03:15 +0530 Subject: [PATCH 152/374] installation removed, added note to don't use ktlint disable --- Ktlint-Guide.md | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index f3a3b033071..477ffb2bcf7 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -1,6 +1,3 @@ -# Installation -Install `Ktlint` from [here](https://github.com/pinterest/ktlint#installation). Note that we specifically recommend using the command-line interface, not the Gradle integration. - # Commands * `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.1`. @@ -41,16 +38,7 @@ There are two major tasks when we talk about style formatting, One is the `Refor 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` - If you want to disable for a block of code/ multiple lines, you can put the blocky comment as well. At starting `/* ktlint-disable max-line-length */` and at the end `/* ktlint-enable max-line-length */` - * Example -
* `fun testWalkthroughWelcomeFragment_recyclerViewIndex1_topicSelected_clickNoButton_worksCorrectly() { // ktlint-disable max-line-length` - - * ``` - /* ktlint-disable max-line-length */ - fun testWalkthroughWelcomeFragment_recyclerViewIndex1_topicSelected_clickNoButton_worksCorrectly() { - .... - .... - } - /* ktlint-enable max-line-length */ - ``` \ No newline at end of file + +**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 From b291ecbdd1a822de7085e1af7d548e96592041b8 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 11 Feb 2021 17:54:30 +0530 Subject: [PATCH 153/374] update google_checks file link --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index fbef36db3dd..7e1f50b90f2 100644 --- a/Home.md +++ b/Home.md @@ -36,7 +36,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. 2. Open git bash command line 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` - 5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml) file. + 5. Download the [google_checks.xml](RecordComponentName) file. 6. Copy it to directory where `Git` is installed (usually `C:/Program Files/Git/`). - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
From aac73e6ba9d01ed0c57205d822893b8649472a83 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Thu, 11 Feb 2021 17:55:27 +0530 Subject: [PATCH 154/374] added link google_checks.xml --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 7e1f50b90f2..8a3ba5abb47 100644 --- a/Home.md +++ b/Home.md @@ -36,7 +36,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. 2. Open git bash command line 3. Move to `opensource/oppia-android/` 4. Run a script `bash scripts/setup.sh` - 5. Download the [google_checks.xml](RecordComponentName) file. + 5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/14005e371803bd52dff429904b354dc3e72638c0/src/main/resources/google_checks.xml) file. 6. Copy it to directory where `Git` is installed (usually `C:/Program Files/Git/`). - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
From acb12debd53e5b62ba233a936a1b9a3653e6b47d Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Sat, 13 Feb 2021 12:46:01 +0530 Subject: [PATCH 155/374] Added note for project folder name --- Home.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Home.md b/Home.md index 8a3ba5abb47..0574efbccd4 100644 --- a/Home.md +++ b/Home.md @@ -21,6 +21,7 @@ Please follow these steps for initial setup of the project 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. 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) +Note: Please keep the project name as it is `oppia-android`, changing the project folder name might lead to failure. 3. Set up `Java` with the latest version. Install from [here](https://www.java.com/en/download/).
If you are on Windows, please set up the environment path correctly for `Java`. From efa039af576789eef2743619040b2314617867ec Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Sat, 13 Feb 2021 12:46:37 +0530 Subject: [PATCH 156/374] nit formatting --- Home.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Home.md b/Home.md index 0574efbccd4..4ba1540f051 100644 --- a/Home.md +++ b/Home.md @@ -21,6 +21,7 @@ Please follow these steps for initial setup of the project 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. 2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) + Note: Please keep the project name as it is `oppia-android`, changing the project folder name might lead to failure. 3. Set up `Java` with the latest version. Install from [here](https://www.java.com/en/download/).
From 2ea491f8918fa792335e65be6b184607c97afbd1 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 16 Feb 2021 11:56:25 +0530 Subject: [PATCH 157/374] added prerequisite --- Oppia-Bazel-Setup-Instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index e48181ed2eb..34af0aed0c7 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -6,6 +6,8 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. **We recommend contributor having Windows OS, not to follow this installation guide as Oppia-Bazel doesn't support on Windows OS as for now.**
For Linux or macOS, install Bazel from [here](https://docs.bazel.build/versions/master/install.html). +**Prerequisite** - Android SDK Platform 28 must present in the `~/Android/sdk` directory where Android Studio keeps all the downloaded SDK. + After installing the original Bazel version, you need to setup Oppia's Bazel version.
1. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From dd61a75f2398f84952bf6a97e4a275520c27da1c Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 23 Feb 2021 12:38:38 -0800 Subject: [PATCH 158/374] Create initial best practices & FAQ from Jan's document. --- ...-Bazel-Migration-Best-Practices-and-FAQ.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 Gradle--Bazel-Migration-Best-Practices-and-FAQ.md diff --git a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md new file mode 100644 index 00000000000..18094c23dfe --- /dev/null +++ b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md @@ -0,0 +1,37 @@ +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. + +![Before diagram](https://user-images.githubusercontent.com/12983742/108904850-deb6c000-75d3-11eb-9156-c01ea8e8e471.png) + +When we create a new library, we can move this set of dependencies to the new library. + +![After diagram](https://user-images.githubusercontent.com/12983742/108904926-f42bea00-75d3-11eb-88f0-37247d7f284b.png) + +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: + +![Alternative after diagram](https://user-images.githubusercontent.com/12983742/108904987-0148d900-75d4-11eb-81f9-0887b95749ce.png) + +## 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 ///src/main/java/org/oppia/app//:all``. + - After the new libraries contain all of the files they need to, their dependencies are correct, and they build, make sure the app also builds by running: ``bazel build //:oppia``. + + +## FAQ + +### I've finished writing a BUILD.bazel file containing new libraries. What now? + +1. Remove all source files from the module's BUILD.bazel file that are now contained in the new BUILD.bazel file +2. Add the new BUILD.bazel file libraries as dependencies for the module's top-level library (these dependencies should be changed in the same library whose source files were updated in #1). +3. Try to remove the dependencies that the new BUILD.bazel file's libraries depend on from the old libraries whose source files were changed (note that these may still be needed by existing source files in those libraries). This can be done by removing each dependency one-at-a-time and trying to rebuild the library to see if the library builds. + From c1042377144d13fcbe60cb608d33be3c08279131 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 8 Mar 2021 10:12:14 +0530 Subject: [PATCH 159/374] temporary remove windows command --- Home.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/Home.md b/Home.md index 4ba1540f051..36b61a0e82d 100644 --- a/Home.md +++ b/Home.md @@ -33,15 +33,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. 2. Move to `opensource/oppia-android/` 3. Run a script `bash scripts/setup.sh` - - For Windows - 1. Install [Git Bash Command Line](https://gitforwindows.org/) - 2. Open git bash command line - 3. Move to `opensource/oppia-android/` - 4. Run a 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. - 6. Copy it to directory where `Git` is installed (usually `C:/Program Files/Git/`). - - - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
+ - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`.
- If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) From d81f585818694d94132d535e79cc02d2099055ea Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 9 Mar 2021 13:34:08 +0530 Subject: [PATCH 160/374] added windows support --- Home.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 36b61a0e82d..ac771d2cae0 100644 --- a/Home.md +++ b/Home.md @@ -33,8 +33,17 @@ If you are on Windows, please set up the environment path correctly for `Java`. 2. Move to `opensource/oppia-android/` 3. Run a script `bash scripts/setup.sh` + - For Windows + 1. Install [Git Bash Command Line](https://gitforwindows.org/) + 2. Open git bash command line + 3. Move to `opensource/oppia-android/` + 4. Run a 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. + 6. Copy it to directory where Git is installed (usually C:/Program Files/Git/). + + - If you find any error related to `cURL`, please set up cURL at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line. - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`.
- - If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and environment path variable is also set up. + - 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 is also set up. - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) ## Instructions for making a code change From d0f02137131a1baea912288b2f26c76d1c95bb29 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Mar 2021 09:33:32 +0530 Subject: [PATCH 161/374] nit formatting --- Ktlint-Guide.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index 477ffb2bcf7..77705b992e7 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -1,17 +1,26 @@ +# 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 -* `ktlint --version` - Check the version of your installed ktlint. As of now on CircleCI we are using `0.37.1`. -* `ktlint --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` +**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 -
`ktlint --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
- * Specific Directory - `ktlint --android "utility/src/**/*.kt"` + * Specific File
`../oppia-android-tools/ktlint --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * Specific Directory
`../oppia-android-tools/ktlint --android "utility/src/**/*.kt"` -* `ktlint -F --android "path/of/your/kotlin/file"` - Android Kotlin Style Guide using `--android` with Ktlint Auto Formatter `-F`. This will fix some of the issues automatically. +* 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 -
`ktlint -F --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
- * Specific Directory - `ktlint -F --android "utility/src/**/*.kt"` + * Specific File
`../oppia-android-tools/ktlint -F --android "app/src/sharedTest/java/org/oppia/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. From 2201c64f53871ceb89e31928314eb3d03984653f Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Wed, 10 Mar 2021 09:43:20 +0530 Subject: [PATCH 162/374] not formatting --- Ktlint-Guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Ktlint-Guide.md b/Ktlint-Guide.md index 77705b992e7..aedd09d9933 100644 --- a/Ktlint-Guide.md +++ b/Ktlint-Guide.md @@ -12,14 +12,14 @@ Once you had completed all the [installation steps](https://github.com/oppia/opp `../oppia-android-tools/ktlint --android "path/of/your/kotlin/file"` * Examples
- * Specific File
`../oppia-android-tools/ktlint --android "app/src/sharedTest/java/org/oppia/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * 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/app/walkthrough/WalkthroughWelcomeFragmentTest.kt"`
+ * 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 From e54278ae9987024dbad38004628a386c71f3b128 Mon Sep 17 00:00:00 2001 From: Jan Date: Fri, 12 Mar 2021 08:55:48 +0000 Subject: [PATCH 163/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 22 +++------------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 34af0aed0c7..c306fca4415 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -3,32 +3,16 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. ## Installation -**We recommend contributor having Windows OS, not to follow this installation guide as Oppia-Bazel doesn't support on Windows OS as for now.**
-For Linux or macOS, install Bazel from [here](https://docs.bazel.build/versions/master/install.html). +**We don't officially support Windows for now so the Windows instructions may not be complete any may require additional tweaking.**
-**Prerequisite** - Android SDK Platform 28 must present in the `~/Android/sdk` directory where Android Studio keeps all the downloaded SDK. +1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). -After installing the original Bazel version, you need to setup Oppia's Bazel version.
1. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
- macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` -2. Clone https://github.com/oppia/bazel (note that this is very large and will take a bit to download) to a specific directory,
e.g.: - `git clone https://github.com/oppia/bazel oppia-bazel` +1. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools) -3. Move you command line head to oppia-bazel dir
`cd ~/oppia-bazel` - -4. Run the command to extract folders (note that this command will probably take 5-10 minutes)
`bazel build //src:bazel //tools/android/runtime_deps:android_tools.tar.gz` - -5. Create dir if it is not created from the above command
`mkdir android_tools` - -6. `tar -xf bazel-bin/tools/android/runtime_deps/android_tools.tar.gz -C ./android_tools` - -7. `cp ~/oppia-bazel/bazel-bin/src/bazel ./bazel` - -8. Linux : `echo build --override_repository=android_tools=~/oppia-bazel/android_tools > ~/.bazelrc`
- - macOS: `echo build --override_repository=android_tools=../oppia-bazel/android_tools > ../oppia-bazel/.bazelrc` #### Possible Error: ``` From e1637f46ee94649470f83e662b52f44a84f829c1 Mon Sep 17 00:00:00 2001 From: Jan Date: Fri, 12 Mar 2021 08:56:28 +0000 Subject: [PATCH 164/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index c306fca4415..5b4dbe511b6 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -3,7 +3,7 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. ## Installation -**We don't officially support Windows for now so the Windows instructions may not be complete any may require additional tweaking.**
+**We don't officially support Windows for now so the Windows instructions may not be complete and may require additional tweaking.**
1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). @@ -13,7 +13,6 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. 1. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools) - #### Possible Error: ``` ERROR: While parsing option --override_repository=android_tools=~/oppia-bazel/android_tools: Repository From 4099795deaede493fed5fa5ac70d3e4a50af0ab3 Mon Sep 17 00:00:00 2001 From: Jan Date: Fri, 12 Mar 2021 08:56:40 +0000 Subject: [PATCH 165/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 5b4dbe511b6..1aaa8bfd4f5 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -11,7 +11,7 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. - Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
- macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` -1. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools) +1. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). #### Possible Error: ``` From 1642b4e80ec91e29352582d1e9a1b3b38c74808a Mon Sep 17 00:00:00 2001 From: Jan Date: Fri, 12 Mar 2021 09:03:22 +0000 Subject: [PATCH 166/374] Updated Gradle Bazel Migration Best Practices and FAQ (markdown) --- Gradle--Bazel-Migration-Best-Practices-and-FAQ.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md index 18094c23dfe..dd0a06eb7af 100644 --- a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md +++ b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md @@ -35,3 +35,13 @@ This is not always possible, since there might be other files relying on the sam 2. Add the new BUILD.bazel file libraries as dependencies for the module's top-level library (these dependencies should be changed in the same library whose source files were updated in #1). 3. Try to remove the dependencies that the new BUILD.bazel file's libraries depend on from the old libraries whose source files were changed (note that these may still be needed by existing source files in those libraries). This can be done by removing each dependency one-at-a-time and trying to rebuild the library to see if the library builds. +## I'm getting a Bazel error: "Error while obtaining the sha256 checksum of." + +If you are getting something similar to this: +``` + Traceback (most recent call last): + File "/home/titan/.cache/bazel/_bazel_titan/d2121258671c00ac2cf78dbca73dac8b/external/rules_jvm_external/coursier.bzl", line 467, column 17, in _coursier_fetch_impl + fail("Error while obtaining the sha256 checksum of " +Error in fail: Error while obtaining the sha256 checksum of v1/https/maven.google.com/android/arch/core/common/1.1.1/common-1.1.1.jar: src/main/tools/process-wrapper-legacy.cc:80: "execvp(python, ...)": No such file or directory +``` +From the error trace, we see that the tool can't find python. Make sure that you have python in your PATH. \ No newline at end of file From c7a49321714a2de4da47acf41ab5d59983424fd9 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Sat, 13 Mar 2021 08:25:28 +0530 Subject: [PATCH 167/374] Removed repeated lines --- Home.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Home.md b/Home.md index ac771d2cae0..6c1e567f857 100644 --- a/Home.md +++ b/Home.md @@ -41,8 +41,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. 5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/14005e371803bd52dff429904b354dc3e72638c0/src/main/resources/google_checks.xml) file. 6. Copy it to directory where Git is installed (usually C:/Program Files/Git/). - - If you find any error related to `cURL`, please set up cURL at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line. - - If you find any error related to `cURL`, please set up `cURL` at your machine. For Linux, you can use `sudo apt install curl`.
+ - If you find any error related to `cURL`, please set up cURL at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- 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 is also set up. - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) From c7204d0d9649bf391904a100dc4ede08d20f935a Mon Sep 17 00:00:00 2001 From: Jan Date: Mon, 15 Mar 2021 20:45:36 +0100 Subject: [PATCH 168/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 1aaa8bfd4f5..a028564b5b5 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -25,25 +25,25 @@ After the installation completes you can build the app using Bazel. Move you com #### Building the app ``` -~/oppia-bazel/bazel build //:oppia +bazel build //:oppia ``` #### Building + installing the app ``` -~/oppia-bazel/bazel mobile-install //:oppia +bazel mobile-install //:oppia ``` #### Running specific module (app) Robolectric tests ``` -~/oppia-bazel/bazel test //app/... +bazel test //app/... ``` #### Running all Robolectric tests (slow) ``` -~/oppia-bazel/bazel test //... +bazel test //... ``` ## Concepts and Terminology From 10ba52213fbc02cffed45c18b035583eb0099242 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 16 Mar 2021 07:03:46 +0530 Subject: [PATCH 169/374] adding steps for m1 --- Home.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Home.md b/Home.md index 6c1e567f857..ebd09d2345e 100644 --- a/Home.md +++ b/Home.md @@ -32,6 +32,13 @@ If you are on Windows, please set up the environment path correctly for `Java`. 1. Open terminal 2. Move to `opensource/oppia-android/` 3. Run a 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. For the Terminal x86 right-click and click Get info and check the option Open using Rosetta + 4. Move to `opensource/oppia-android/` + 5. Now run `bash scripts/setup.sh` in Terminal x86 and all the required files will be generated as they should - For Windows 1. Install [Git Bash Command Line](https://gitforwindows.org/) From 1a56f2526a8cb6816598c504288062fbce96c1f5 Mon Sep 17 00:00:00 2001 From: Jan Date: Tue, 23 Mar 2021 20:36:25 +0100 Subject: [PATCH 170/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index a028564b5b5..7d335e98003 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -1,8 +1,10 @@ ## Overview Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. It uses a human-readable, high-level build language. - ## Installation + +**WARNING: Do not use the Android Studio Bazel plugin, since it's currently not compatible with the project.** + **We don't officially support Windows for now so the Windows instructions may not be complete and may require additional tweaking.**
1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). From 96f0013224d0a66b669871292cddc4312895fc93 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 25 Mar 2021 17:27:40 +0530 Subject: [PATCH 171/374] Created Frequent Errors and Solutions (markdown) --- Frequent-Errors-and-Solutions.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 Frequent-Errors-and-Solutions.md diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md new file mode 100644 index 00000000000..00be131acf9 --- /dev/null +++ b/Frequent-Errors-and-Solutions.md @@ -0,0 +1,9 @@ +### Unresolved reference Dagger +**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. + +### Push failed +**Error**: Failed to push some refs to `git@github.com:/oppia-android.git` + +**Solution**: From 452eee1ca6d33a2578bbd848a9ab0c63bc8fa8a5 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 25 Mar 2021 17:27:57 +0530 Subject: [PATCH 172/374] Updated Frequent Errors and Solutions (markdown) --- Frequent-Errors-and-Solutions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md index 00be131acf9..d0862646ab1 100644 --- a/Frequent-Errors-and-Solutions.md +++ b/Frequent-Errors-and-Solutions.md @@ -1,9 +1,9 @@ -### Unresolved reference Dagger +## Unresolved reference Dagger **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. -### Push failed +## Push failed **Error**: Failed to push some refs to `git@github.com:/oppia-android.git` **Solution**: From 6fed8e90456293de2a687194ff661a58f4cf96e1 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 25 Mar 2021 08:29:11 -0700 Subject: [PATCH 173/374] Soften warnings for Bazel Android Studio & Windows users. --- Oppia-Bazel-Setup-Instructions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 7d335e98003..642722e103d 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -3,9 +3,9 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. ## Installation -**WARNING: Do not use the Android Studio Bazel plugin, since it's currently not compatible with the project.** +**WARNING: We recommend to not use the Android Studio Bazel plugin since it currently has compatibility issues with the project.** -**We don't officially support Windows for now so the Windows instructions may not be complete and may require additional tweaking.**
+**We don't officially support Windows for now so the Windows instructions may not be complete and may require additional tweaking.** Note that it's fine to try to use Windows but keep in mind that you might not receive help much. If you plan on contributing to the project with Bazel-specific work, we suggest either sideloading or virtualizing Ubuntu (e.g. with VirtualBox).
1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). From 0fe97f783d7bb38d686c85f2eb4d7301d5bbbec3 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Fri, 26 Mar 2021 05:25:57 +0530 Subject: [PATCH 174/374] nit info added --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index ebd09d2345e..9d3c6065eee 100644 --- a/Home.md +++ b/Home.md @@ -45,7 +45,7 @@ If you are on Windows, please set up the environment path correctly for `Java`. 2. Open git bash command line 3. Move to `opensource/oppia-android/` 4. Run a 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. + 5. Download the [google_checks.xml](https://github.com/checkstyle/checkstyle/blob/14005e371803bd52dff429904b354dc3e72638c0/src/main/resources/google_checks.xml) file. To download this file, you can simply right-click on the `Raw` button and click on `Save Link as`. 6. Copy it to directory where Git is installed (usually C:/Program Files/Git/). - If you find any error related to `cURL`, please set up cURL at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
From a5f3d726049dfcd7eaa85d28223ae767389e8437 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Tue, 6 Apr 2021 16:57:59 +0530 Subject: [PATCH 175/374] added push fail solution --- Frequent-Errors-and-Solutions.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md index d0862646ab1..636961af7a7 100644 --- a/Frequent-Errors-and-Solutions.md +++ b/Frequent-Errors-and-Solutions.md @@ -6,4 +6,9 @@ ## Push failed **Error**: Failed to push some refs to `git@github.com:/oppia-android.git` -**Solution**: +**Solution**: If you are using Android Studio or other UI based git to push and got the above error, this might not provide many details. Try to push using the command line. Also, we suggest using the command line, as all our scripts, project building, APK building is done using the command line as we are moving towards the Bazel build system and removing the Gradle build system. + + + +If there is any error with any of the lint failure it will be detailed in the command line itself. + From 54c2e2303848f0df7123d481bbdaf56a34b86a9a Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 8 Apr 2021 14:35:59 -0700 Subject: [PATCH 176/374] Write-up on the team's concurrency & coroutine best practices, including when & why to use DataProviders/LiveData and other utilities. --- ...in-Android---DataProviders-&-Coroutines.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md diff --git a/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md b/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md new file mode 100644 index 00000000000..0b97f792be1 --- /dev/null +++ b/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md @@ -0,0 +1,126 @@ +## 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 + +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. + +### 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. + +### 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). + +### 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 + +Best practices: +- 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. + +### 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 From cc65a6ab2081a528fe922a85c3a70825f69090f1 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Sat, 10 Apr 2021 02:03:38 +0530 Subject: [PATCH 177/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 642722e103d..eabdcb43133 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -22,7 +22,7 @@ override directory must be an absolute path ``` Try to delete the `.bazelrc` file to solve the above. error. -After the installation completes you can build the app using Bazel. Move you command line head to the `~/opensource/oppia-android` and run the below bazel command: +After the installation completes you can build the app using Bazel. Move your command line head to the `~/opensource/oppia-android` and run the below bazel command: #### Building the app From 887b17f75d1dae0ae5ae042a9882fe30883bb020 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 21 Apr 2021 17:18:43 -0700 Subject: [PATCH 178/374] Switch installation command to 'adb install' rather than 'mobile-install' since the latter is currently broken in Python 2 environments. --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index eabdcb43133..388f8be9ffe 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -33,7 +33,7 @@ bazel build //:oppia #### Building + installing the app ``` -bazel mobile-install //:oppia +bazel build //:oppia && adb install -r bazel-bin/oppia.apk ``` #### Running specific module (app) Robolectric tests From 6d6bee63233e874435565d1c26576ed8178d458d Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 21 Apr 2021 17:22:24 -0700 Subject: [PATCH 179/374] Added a section for downgrade/incompatible installation errors & how to mitigate them. --- ...--Bazel-Migration-Best-Practices-and-FAQ.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md index dd0a06eb7af..98ff63f4278 100644 --- a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md +++ b/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md @@ -35,7 +35,7 @@ This is not always possible, since there might be other files relying on the sam 2. Add the new BUILD.bazel file libraries as dependencies for the module's top-level library (these dependencies should be changed in the same library whose source files were updated in #1). 3. Try to remove the dependencies that the new BUILD.bazel file's libraries depend on from the old libraries whose source files were changed (note that these may still be needed by existing source files in those libraries). This can be done by removing each dependency one-at-a-time and trying to rebuild the library to see if the library builds. -## I'm getting a Bazel error: "Error while obtaining the sha256 checksum of." +### I'm getting a Bazel error: "Error while obtaining the sha256 checksum of." If you are getting something similar to this: ``` @@ -44,4 +44,18 @@ If you are getting something similar to this: fail("Error while obtaining the sha256 checksum of " Error in fail: Error while obtaining the sha256 checksum of v1/https/maven.google.com/android/arch/core/common/1.1.1/common-1.1.1.jar: src/main/tools/process-wrapper-legacy.cc:80: "execvp(python, ...)": No such file or directory ``` -From the error trace, we see that the tool can't find python. Make sure that you have python in your PATH. \ No newline at end of file +From the error trace, we see that the tool can't find python. Make sure that you have python in your PATH. + +### When installing the app, I see INSTALL_FAILED_VERSION_DOWNGRADE or INSTALL_FAILED_UPDATE_INCOMPATIBLE + +In the event that, when trying to install a Bazel-built version of the app, you see one of the following errors: +- ``adb: failed to install bazel-bin/oppia.apk: Failure [INSTALL_FAILED_VERSION_DOWNGRADE]`` +- ``adb: failed to install bazel-bin/oppia.apk: Failure [INSTALL_FAILED_UPDATE_INCOMPATIBLE]`` + +You will need to uninstall the existing version of the Oppia Android app and then try the installation again. You can either uninstall through the system's package menu UI, or run the following command: + +``` +adb shell pm uninstall org.oppia.android +``` + +(If the command above works correctly, you will see 'Success' in the output). \ No newline at end of file From 0a9a71ac3d100dcabcecf4ede2520bbe6aa5ee33 Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Mon, 3 May 2021 15:25:50 +0530 Subject: [PATCH 180/374] installation and commands updated --- Buf-Guide.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Buf-Guide.md b/Buf-Guide.md index fb39dcfd5ef..e6931d53a92 100644 --- a/Buf-Guide.md +++ b/Buf-Guide.md @@ -1,24 +1,24 @@ -## Installation - -Install `buf` from [here](https://buf.build/docs/installation). +# Installation +Once you had completed all the [installation steps](https://github.com/oppia/oppia-android/wiki#prerequisites), you will be having a `buf` file in your `opensource/oppia-android-tools` folder.
+**Note: Currently, Buf is not available for windows.** ## Commands -* `buf --version` - to check the version of the buf you had installed -* `buf --help` - help command of buf -* `buf check lint --input=model/src/main/proto --input-config buf.yaml` - this is where we do lint check - +* 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` in the root of the project. Following is the list of things we are checking and list of things we are excluding from our check. +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 same package name should be in 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;` @@ -38,8 +38,8 @@ We have a configuration file `buf.yaml` in the root of the project. Following is * `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 with have a package defined. - * All proto files must have a package name specify in it, example - `package model;` +* `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` @@ -54,20 +54,20 @@ We have a configuration file `buf.yaml` in the root of the project. Following is * Message should be in Pascal case, example - `ProfileAvatar` * `ONEOF_LOWER_SNAKE_CASE` checks that oneof names are lower_snake_case. - * Oneof should be 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` (suffix is configurable). +* `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, example - `topic.proto` + * All the proto file names are should be in lower snake case, for example - `topic.proto` #### Excluding: -* `PACKAGE_DIRECTORY_MATCH` checks that all files with are in a directory that matches their package name. - * this verifies that all files that declare a given package foo.bar.baz.v1 are in the directory foo/bar/baz/v1 relative to the root +* `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; }` From 17f825ce1ea08bec29197fce901014f0450f0086 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 11 Jun 2021 17:04:05 +0530 Subject: [PATCH 181/374] Created Developing Oppia Android (markdown) --- Developing-Oppia-Android.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Developing-Oppia-Android.md diff --git a/Developing-Oppia-Android.md b/Developing-Oppia-Android.md new file mode 100644 index 00000000000..69ec7b115b1 --- /dev/null +++ b/Developing-Oppia-Android.md @@ -0,0 +1 @@ +Updating Maven Dependencies \ No newline at end of file From 3722bf2ba2a85956ee6655389f515dfaea2238f3 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 11 Jun 2021 17:04:55 +0530 Subject: [PATCH 182/374] Destroyed Developing Oppia Android (markdown) --- Developing-Oppia-Android.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Developing-Oppia-Android.md diff --git a/Developing-Oppia-Android.md b/Developing-Oppia-Android.md deleted file mode 100644 index 69ec7b115b1..00000000000 --- a/Developing-Oppia-Android.md +++ /dev/null @@ -1 +0,0 @@ -Updating Maven Dependencies \ No newline at end of file From 59dd275c6ed8d5fd3743fd0e36d17dfbab3b4a55 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Tue, 29 Jun 2021 01:44:25 +0530 Subject: [PATCH 183/374] Add instructions to update maven_install.json --- Updating-Maven-Dependencies.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 Updating-Maven-Dependencies.md diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md new file mode 100644 index 00000000000..a2f7634f28d --- /dev/null +++ b/Updating-Maven-Dependencies.md @@ -0,0 +1,6 @@ +All the third-party Maven dependencies used in Oppia-Android along with their versions are mentioned in the `versions.bzl` file that resides in the `third_party` package. To add/delete/update any dependency, please follow the below steps - + +1. Ensure that after making changes in the list of dependencies, the final list is always lexicographically sorted. +2. After updating dependency, run the command + `$ REPIN=1 bazel run @unpinned_maven//:pin` + From e3d02662115bceb325528e8529ea2ad0f12a540e Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Tue, 29 Jun 2021 11:34:39 +0530 Subject: [PATCH 184/374] Add link to versions.bzl --- Updating-Maven-Dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index a2f7634f28d..74e882d757d 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -1,4 +1,4 @@ -All the third-party Maven dependencies used in Oppia-Android along with their versions are mentioned in the `versions.bzl` file that resides in the `third_party` package. To add/delete/update any dependency, please follow the below steps - +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, please follow the below steps - 1. Ensure that after making changes in the list of dependencies, the final list is always lexicographically sorted. 2. After updating dependency, run the command From 0a646b3d96714561d15acdd4c661e63f98dea93d Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 2 Jul 2021 10:07:40 +0530 Subject: [PATCH 185/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 49 ++++++++++++++++++++++++++++++----- 1 file changed, 42 insertions(+), 7 deletions(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 7e9a90ac291..2c333372d96 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -10,23 +10,30 @@ Making sure that the Oppia app is accessible by all resonates with overall Oppia Note: In short we can write Accessibility as **A11Y**. -## Useful Resources +## How to test the app for a11y users? +* All the screens in the app should pass on [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) +* Screen Reader (Talkback) should be able to navigate to all the UI items and should have logical descriptions. +* [AccessibilityChecks](https://developer.android.com/guide/topics/ui/accessibility/testing#automated) are enabled for all Espresso based test cases + +## Setting up Accessibility Scanner and Talkback + +### Useful Resources * [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) * [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) * [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) * [Display speech output as Text: Talkback](https://developer.android.com/guide/topics/ui/accessibility/testing#optional_talkback_developer_settings) -## Setup Play Store in mobile emulator +### Setup Play Store in mobile emulator 1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. 2. Open "Play Store" app and sign-in. -## Setup Play Store in tablet emulator +### Setup Play Store in tablet emulator By default tablet emulators do not contain **Play Store** app and therefore you will need to make some changes to make it available. 1. Follow the steps mentioned [here](https://stackoverflow.com/a/62680014). -2. Once above steps are done, start the emulator. -3. Open "Play Store" app and sign-in. +2. Once the above steps are done, start the emulator. +3. Open the "Play Store" app and sign-in. -## Using a11y scanner in android +### Using a11y scanner in android [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) scans your screen and provides suggestions to improve the accessibility of your app, based on: * Content labels * Touch target size @@ -45,7 +52,7 @@ By default tablet emulators do not contain **Play Store** app and therefore you **Result**: You will notice that the scanner analyses the screen and give errors if there are any or else it will show that no errors were found. -## Using Talkback in android +### Using Talkback in android TalkBack is the Google **screen reader** included on Android devices. TalkBack gives you spoken feedback so that you can use your device without looking at the screen. #### How to use? @@ -57,3 +64,31 @@ TalkBack is the Google **screen reader** included on Android devices. TalkBack g 6. Turn on **Use Service** -> **Allow** Now you can use talkback. For more information visit [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677). + +## Using AccessibilityTestRule in Espresso Tests +[AccessibilityTestRule](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/AccessibilityTestRule.kt) is a JUnit rule to enable `AccessibilityChecks` in all Espresso Tests. This rule covers all errors shown by Accessibility Scanner and more but only for all those UI elements which are getting used in the test case. + +(**Note: If this file is not available then it has been merged with OppiaTestRule as per #3351**) + +#### How to use? +Simply use the `AccessibilityTestRule` in Espresso Test file like this: +``` +@get: Rule +val accessiblityTestRule = AccessibilityTestRule() +``` + +This will enable the `AccessibilityChecks` on all Espresso tests inside this file. + +To disable `AccessibilityChecks` on any individual test case use [DisableAccessibilityChecks](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/DisableAccessibilityChecks.kt) as annotation with the test. + +In case of test failure there are two options to fix it: +* Solve the test case by updating the UI as per the error details. +* If by solving the error the user experience will become worse than we should actually suppress that error instead of changing the UI. This can be done in [AccessibilityTestRule](https://github.com/oppia/oppia-android/blob/fe553d32e0161f6efa6e465109306b909dbcc476/testing/src/main/java/org/oppia/android/testing/AccessibilityTestRule.kt#L34) + +## General Tips to make app Accessible +* All Clickable items should have a minimum size of `48x48dp`. +* Buttons should use `android:enabled` instead of `android:clickable` to disable/enable it. +* All views should have a `foreground:background` contrast ratio of `4.5:1` and above. +* Texts should have a minimum `12sp` text size. +* Images/icons should have a meaningful content description. + From 7561b275e7fd4bfce0f6637ad66810aa28945305 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 2 Jul 2021 10:15:21 +0530 Subject: [PATCH 186/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 2c333372d96..6777f4d224c 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -85,6 +85,16 @@ In case of test failure there are two options to fix it: * Solve the test case by updating the UI as per the error details. * If by solving the error the user experience will become worse than we should actually suppress that error instead of changing the UI. This can be done in [AccessibilityTestRule](https://github.com/oppia/oppia-android/blob/fe553d32e0161f6efa6e465109306b909dbcc476/testing/src/main/java/org/oppia/android/testing/AccessibilityTestRule.kt#L34) +## Auditing the app +The app should be audited by covering different use cases across 23 different manual tests mentioned [here](https://docs.google.com/spreadsheets/d/1lFQo2XE0dSGZcMvr7paxdL3zXB3FVcRnZOqD70DT3a4/edit?usp=sharing). +This sheet has been divided based on `primary` and `secondary` use cases and `basic` and `advanced` test cases. +* Level 1 = `Primary + Basic`, which means that all primary use cases passes all `Basic` tests. +* Level 2 = `Secondary + Basic`, which means that all secondary use cases passes all `Basic` tests. +* Level 3 = `Primary + Advanced`, which means that all primary use cases passes all `Advanced` tests. +* Level 4 = `Secondary + Advanced`, which means that all secondary use cases passes all `Advanced` tests. + +This entire sheet should be filled with each release as a part of audit process. + ## General Tips to make app Accessible * All Clickable items should have a minimum size of `48x48dp`. * Buttons should use `android:enabled` instead of `android:clickable` to disable/enable it. From cd406b750684c97f4147c5938a486845c1b07c6f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Fri, 2 Jul 2021 15:27:27 +0530 Subject: [PATCH 187/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 6777f4d224c..1d392f68bb9 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -11,17 +11,16 @@ Making sure that the Oppia app is accessible by all resonates with overall Oppia Note: In short we can write Accessibility as **A11Y**. ## How to test the app for a11y users? -* All the screens in the app should pass on [Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en) -* Screen Reader (Talkback) should be able to navigate to all the UI items and should have logical descriptions. -* [AccessibilityChecks](https://developer.android.com/guide/topics/ui/accessibility/testing#automated) are enabled for all Espresso based test cases +There are various manual and automated tests to check if app is accessible by all or not. All of the below mentioned tests are required to make sure that app is accessible in most cases. -## Setting up Accessibility Scanner and Talkback +**[Accessibility Scanner](https://support.google.com/accessibility/android/answer/6376570?hl=en)** : Using Accessibility Scanner we can take screenshots of each and every screen in the Oppia-app manually and the Accessibility Scanner app will give the output for the individual screenshot mentioning all the errors. -### Useful Resources -* [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) -* [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) -* [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) -* [Display speech output as Text: Talkback](https://developer.android.com/guide/topics/ui/accessibility/testing#optional_talkback_developer_settings) +**Screen Reader**: Screen readers like **Talkback** can be used to test the app manually. Talkback app is used by blind people to navigate to different items in the screen and get audio based output. This app will not give any error like Accessibility Scanner. + +**[AccessibilityChecks](https://developer.android.com/guide/topics/ui/accessibility/testing#automated)**: Developers can activate the `AccessibilityChecks` in all `Espresso` test cases which will give errors related to accessibility. + + +## Setting up Accessibility Scanner and Talkback ### Setup Play Store in mobile emulator 1. Create a new emulator device which contains **Google Play Store** in it. Example: Nexus 5, Nexus 5A, Pixel, Pixel 2, Pixel 3, Pixel 3a, Pixel 4. @@ -63,7 +62,13 @@ TalkBack is the Google **screen reader** included on Android devices. TalkBack g 5. Read all the instructions written on the screen as using Talkback requires specific steps. 6. Turn on **Use Service** -> **Allow** -Now you can use talkback. For more information visit [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677). + +### Useful Resources +* [Android A11Y Overview](https://support.google.com/accessibility/android/answer/6006564) +* [Using A11Y Menu](https://support.google.com/accessibility/android/answer/9078941) +* [Getting started with Talkback](https://support.google.com/accessibility/android/answer/6283677) +* [Display speech output as Text: Talkback](https://developer.android.com/guide/topics/ui/accessibility/testing#optional_talkback_developer_settings) + ## Using AccessibilityTestRule in Espresso Tests [AccessibilityTestRule](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/AccessibilityTestRule.kt) is a JUnit rule to enable `AccessibilityChecks` in all Espresso Tests. This rule covers all errors shown by Accessibility Scanner and more but only for all those UI elements which are getting used in the test case. From 9467aa9187951ff87d95c1696f4de9969e4e7cfc Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 7 Jul 2021 16:17:21 -0700 Subject: [PATCH 188/374] Document process for getting Bazel builds to work on Windows 10 --- Bazel-Setup-Instructions-for-Windows.md | 163 ++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 Bazel-Setup-Instructions-for-Windows.md diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md new file mode 100644 index 00000000000..8c22eb3e9e7 --- /dev/null +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -0,0 +1,163 @@ +## 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) if you do. + +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. Once downloaded, copy the zip file to the new SDK location (note that the ``/mnt/c/...`` path is based on ``C:\Users\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: + +```sh +cp /c/mnt/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk +``` + +After that, change to the directory, unzip the archive, and remove it: + +```sh +cd $HOME/Android/Sdk +unzip commandlinetools*.zip +rm commandlinetools*.zip +``` + +From there, the command line tools need to be moved in order to indicate to the tools themselves that they're relative to the Android SDK root directory: + +```sh +cd cmdline-tools/ +mkdir tools +mv -i * tools +cd .. +``` + +(The above may give a warning for the ``mv`` command since it will try moving ``tools`` into ``tools``--this can be ignored). + +At this point, we can define the ``ANDROID_HOME`` variable to point to the new SDK root, and also update the ``PATH`` to point to cmdnline-tools so that we can actually install the SDK. To do this, run the following commands to append new lines to ``~/.bashrc``: + +```sh +echo "export ANDROID_HOME=\$HOME/Android/Sdk" >> ~/.bashrc +echo "export PATH=\$ANDROID_HOME/cmdline-tools/tools/bin/:\$PATH >> ~/.bashrc +source ~/.bashrc +``` + +(The last line reloads your Bash configuration file so that the variable adjustments above become live in your local terminal). + +The ``sdkmanager`` command can now be used to install the necessary packages. Run each of the following commands in succession (you may need to accept licenses for the SDK packages in the same way you would when using Android Studio): + +```sh +sdkmanager +sdkmanager --install "platform-tools" +sdkmanager --install "platforms;android-28" +sdkmanager --install "build-tools;29.0.2" +``` + +When the commands above are finished running, the Android SDK should now be installed in your subsystem & be accessible to Bazel. + +### 4. Installing Bazel + +Follow [these instructions](https://docs.bazel.build/versions/main/install-ubuntu.html#install-on-ubuntu) to install Bazel using ``apt`` rather than Bazelisk (Bazelisk might work, but it's untested with these instructions). + +### 5. Preparing build environment for Oppia Android + +The Oppia Android repository generally expects to live under an 'opensource' directory. While we recommend doing that in practice, we run into one complication when building the app on Windows: the repository itself lives under the native Windows filesystem & most of everything else needed to build lives under the Linux subsystem. To help simplify things, we prefer keeping just the repository on Windows and everything else on Linux, including the the Oppia Bazel toolchain. To prepare for this, we suggest making an 'opensource' directory in your Ubuntu subsystem: + +```sh +mkdir $HOME/opensource +``` + +From there, follow [these instructions](https://github.com/oppia/oppia-bazel-tools#readme) in order to prepare your environment to support Oppia Android builds. + +### 6. Verifying the build + +At this point, your system should be able to build Oppia Android. To verify, try building the APK (from your subsystem terminal): + +```sh +bazel build //:oppia +``` + +(Note that this command may take 10-20 minutes to complete depending on the performance of your machine). + +If everything is working, you should see output like the following: + +``` +Target //:oppia up-to-date: + bazel-bin/oppia_deploy.jar + bazel-bin/oppia_unsigned/apk + bazel-bin/oppia/apk +INFO: Elapsed time: ... +INFO: 1 process... +INFO: Build completed successfully, ... +``` + +If you see the above, you can proceed to use your subsystem for Bazel commands while developing Oppia. If you instead see an error, please [file an issue](https://github.com/oppia/oppia-android/issues/new/choose). + +Note also that the ``oppia.apk`` under the ``bazel-bin`` directory of your local copy of Oppia Android should be a fully functioning development version of the app that can be installed using ``adb`` (though we recommend using ADB from within a Windows command prompt or shell since the Ubuntu subsystem may not have correct support to access devices or emulators connected to the native Windows machine). + +### 7. Next steps + +At this point, commands listed on the other [Bazel setup instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions#building-the-app) page should now work locally. Keep in mind that your development will continue on Windows via Android Studio and that the subsystem is only needed to execute Bazel commands (Gradle should continue to work through Windows). + +## Appendix + +### Limitations +Known limitations with using an Ubuntu subsystem on Windows: +- Android Studio must run on native Windows: this is a current limitation. However, https://github.com/microsoft/wslg is a WIP project that may provide an alternative option which allows full development to take place within the subsystem. +- The subsystem is very slow: unfortunately, this is just a limitation with how the subsystem works on Windows. Until we fix the actual build pipeline to work natively, this is likely going to be a limitation that we have to live with. Note that installing an Ubuntu VM or dual-booting Ubuntu may lead to less issues & better performance than using a subsystem, but this hasn't yet been investigated or documented yet (see [#3437](https://github.com/oppia/oppia-android/issues/3437) for the WIP issue). +- ADB is limited within the subsystem and thus must be used from within a Windows CLI like Command Prompt, Powershell, or Git Bash (if it's installed) in order to deploy the Bazel-built test or APK binary to an emulator or real device +- Emulators likely cannot be launched from the subsystem (headless might be possible, but this hasn't been tested) From 876c212bd7f9b9002e02eb15913a89b0b5b2dab7 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 7 Jul 2021 16:18:57 -0700 Subject: [PATCH 189/374] Link to Windows instructions rather than indicating we don't support Windows. --- Oppia-Bazel-Setup-Instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 388f8be9ffe..616f269a61d 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -5,7 +5,9 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. **WARNING: We recommend to not use the Android Studio Bazel plugin since it currently has compatibility issues with the project.** -**We don't officially support Windows for now so the Windows instructions may not be complete and may require additional tweaking.** Note that it's fine to try to use Windows but keep in mind that you might not receive help much. If you plan on contributing to the project with Bazel-specific work, we suggest either sideloading or virtualizing Ubuntu (e.g. with VirtualBox).
+**NOTE: If you're using Windows, please follow [these instructions](https://github.com/oppia/oppia-android/wiki/Bazel-Setup-Instructions-for-Windows) instead.** + +Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). From edab9bec92a0df3ba445c944193fe210a07a1102 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 14 Jul 2021 10:26:45 +0530 Subject: [PATCH 190/374] Updated Bazel Setup Instructions for Windows (markdown) --- Bazel-Setup-Instructions-for-Windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index 8c22eb3e9e7..b5c19dad326 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -1,6 +1,6 @@ ## 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) if you do. +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) if you do or 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. From b0366a3690b8f34c3fa77f6c1f0bf45de400893b Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 14 Jul 2021 11:03:51 +0530 Subject: [PATCH 191/374] Updated Bazel Setup Instructions for Windows (markdown) --- Bazel-Setup-Instructions-for-Windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index b5c19dad326..da66f68184b 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -1,6 +1,6 @@ ## 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) if you do or contact us at [gitter](https://gitter.im/oppia/oppia-android) +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. From b432abd2db46b43b0cb9cd9941a38ba1337bcc95 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Mon, 19 Jul 2021 23:10:05 +0530 Subject: [PATCH 192/374] Add instructions to run the first script and handle exceptions --- Updating-Maven-Dependencies.md | 128 ++++++++++++++++++++++++++++++++- 1 file changed, 126 insertions(+), 2 deletions(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index 74e882d757d..531665119f2 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -1,6 +1,130 @@ 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, 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 dependency, run the command - `$ REPIN=1 bazel run @unpinned_maven//:pin` +2. After updating dependency, run the command - +``` +REPIN=1 bazel run @unpinned_maven//:pin +``` + +## Updating `maven_dependencies.textproto` +If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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 in order 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/_edit#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 ~/` ). + +Then run the bazel run command to execute the Kotlin script - +``` +bazel run //scripts:generate_maven_dependencies_list -- $(pwd) third_party/maven_install.json scripts/assets/maven_dependencies.textproto scripts/assets/maven_dependencies.pb +``` + +## Handling Exception: `Licenses details are not completed` +The script can take about a minute to execute, and if the script fails with the exception: `Licenses details are not completed`, you will need to do some manual work in `maven_dependencies.textproto`. +The script would call out specific dependencies that need to be updated manually, e.g - + +``` +Please verify the license link(s) for the following license(s) manually in +maven_dependencies.textproto, note that only the first dependency that contains the license +needs to be updated and also re-run the script to update the license details at all places: + +license_name: Android Software Development Kit License +original_link: https://developer.android.com/studio/terms.html +verified_link_case: VERIFIEDLINK_NOT_SET +is_original_link_invalid: false +The first dependency that should be updated with the license: com.google.firebase:firebase-analytics:17.5.0 + +``` + +Go to `maven_dependencies.textproto` and find the dependency that is mentioned as `The first dependency that should be updated with the license` in the output. For example, in the above case, look for `com.google.firebase:firebase-analytics:17.5.0` in maven_dependencies.textproto and open the `original_link` of its license in your browser and check if the link points to any valid license or not. If the link does not point to a valid license, set the 'is_original_link_invalid' field of the license to 'true'. +For example, if the original_link https://www.xyz.com is invalid, then set `is_original_link_invalid` to true. + +``` +maven_dependency { + artifact_name: "artifact:name" + artifact_version: "1.0" + license { + license_name: "XYZ License" + original_link: "https://www.xyz.com" + is_original_link_invalid: true + } +} +``` + +### Categorizing the license link + +If the link does point to a valid license then choose the most appropriate category for the link: +1. scrapable_link: If the license text is plain text and the URL mentioned can be scraped directly from the original_link of the license. + e.g - https://www.apache.org/licenses/LICENSE-2.0.txt +2. extracted_copy_link: If the license text is plain text but it can not be scraped directly from the original_link of the license. + e.g - https://www.opensource.org/licenses/bsd-license +3. direct_link_only: If the license text is not plain text, it's best to display only the link of the license. + e.g - https://developer.android.com/studio/terms.html + +After identifying the category of the license, modify the license to include one of the above-mentioned 'url'. e.g - +``` +license { + license_name: "The Apache Software License, Version 2.0" + original_link: "https://www.apache.org/licenses/LICENSE-2.0.txt" + scrapable_link { + url: "https://www.apache.org/licenses/LICENSE-2.0.txt" + } +} +``` + +Also, if the license falls in the `extracted_copy_link` category, then go to [Oppia-android-licenses](https://github.com/oppia/oppia-android-licenses) and find if there exists a copy of the license already in the repository. If there exists a copy of the license, perform the following steps to get the link for the license that can be scraped easily - +1. Click on the appropriate license file. +2. Now click on the raw button positioned in the left of the edit and delete button. +3. Copy the URL from the browser and mention it at the appropriate place. + +If the license does not exist in Oppia-android-licenses repository, then coordinate with Oppia Android team and raise a PR to add a new license text file. Then repeat the above steps to update maven_dependencies.textproto. + + + + +After modifying `maven_dependencies.textproto` for all the called out licenses in the console output, re-run the script and see if any other error occurs. + +## Handling Exception: `License links are invalid or not available for some dependencies` + +If the script throws `License links are invalid or not available for some dependencies` exception, then the output would look something like this - + +``` +Please remove all the invalid links (if any) from maven_dependencies.textproto for the below mentioned dependencies and provide the valid license links manually. + +maven_dependency { + artifact_name: "io.fabric.sdk.android:fabric:1.4.7" + artifact_version: "1.4.7" + license { + license_name: "Terms of Service for Firebase Services" + original_link: "https://fabric.io/terms" + is_original_link_invalid: true + } +} + +maven_dependency { + artifact_name: "com.google.guava:failureaccess:1.0.1" + artifact_version: "1.0.1" +} +``` + +To fix the error, consider the above example. For the first maven_dependency: "io.fabric.sdk.android:fabric:1.4.7", the original_link is invalid, and hence we need to find a valid link for this dependency. Please coordinate with the Oppia Android team and find a valid link for this dependency, once you have a valid link for this license then categorize it as mentioned [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies/_edit#categorizing-the-license-link). + +For the second maven_dependency: "com.google.guava:failureaccess:1.0.1", you need to find a license by coordinating with Oppia Android team and then specify it under the artifact_version field of the dependency. e.g - + +``` +maven_dependency { + artifact_name: "com.google.guava:failureaccess:1.0.1" + artifact_version: "1.0.1" + license { + license_name: "The Apache Software License, Version 2.0" + scrapable_link { + url: "https://www.apache.org/licenses/LICENSE-2.0.txt" + } + } +} +``` +After updating maven_dependencies.textproto for all the called out dependencies, re-run the script. The script would pass if all the dependencies are updated successfully, and if it doesn't identify the exception being thrown and try to fix it with the help of the above-mentioned details. \ No newline at end of file From ae0faf497db5ab5dc3cf92477e405f5c8e0fa3f1 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Mon, 19 Jul 2021 23:20:38 +0530 Subject: [PATCH 193/374] Update wiki to include exception - Too few arguments passed --- Updating-Maven-Dependencies.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index 531665119f2..0c6303c3565 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -17,11 +17,21 @@ 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 ~/` ). -Then run the bazel run command to execute the Kotlin script - +#### Running `GenerateMavenDependenciesList.kt` script +After the terminal points to the Oppia-android repository, run the bazel run command to execute the Kotlin script - ``` bazel run //scripts:generate_maven_dependencies_list -- $(pwd) third_party/maven_install.json scripts/assets/maven_dependencies.textproto scripts/assets/maven_dependencies.pb ``` +## Handling Exception: `Too few arguments passed` +If after running the script the exception message says: **Too few arguments passed**, then please ensure that you copied the command correctly from [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies/_edit#running-generatemavendependencieslistkt-script). +The scripts exccepts 4 parameters to be passed to run successfully: +1. **_path_to_directory_root_**: directory path to the root of the Oppia Android repository, e.g - `home//opensource/oppia-android` +2. **_path_to_maven_install_json_**: relative path to the maven_install.json file, e.g - `third_party/maven_install.json` +3. **_path_to_maven_dependencies_textproto_**: relative path to the maven_dependencies.textproto, e.g - `scripts/assets/maven_dependencies.textproto` +4. **_path_to_maven_dependencies_pb_**: relative path to the maven_dependencies.pb file, e.g - `scripts/assets/maven_dependencies.pb` + + ## Handling Exception: `Licenses details are not completed` The script can take about a minute to execute, and if the script fails with the exception: `Licenses details are not completed`, you will need to do some manual work in `maven_dependencies.textproto`. The script would call out specific dependencies that need to be updated manually, e.g - From 82695dd3bbcb4bd1bcac88cf1efc4730291db8f2 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Wed, 21 Jul 2021 12:35:45 +0530 Subject: [PATCH 194/374] Fix links to not point to the edit mode --- Updating-Maven-Dependencies.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index 0c6303c3565..bf4b67c642c 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -1,16 +1,16 @@ -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, please follow the below steps - +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, 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 dependency, run the command - +2. After updating dependency, run the following command. ``` REPIN=1 bazel run @unpinned_maven//:pin ``` ## Updating `maven_dependencies.textproto` -If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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 in order 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/_edit#updating-maven_installjson). -To run this script, run the following commands - +If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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 in order 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 @@ -18,14 +18,14 @@ 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 ~/` ). #### Running `GenerateMavenDependenciesList.kt` script -After the terminal points to the Oppia-android repository, run the bazel run command to execute the Kotlin script - +After the terminal points to the Oppia-android repository, run the bazel run command to execute the Kotlin script. ``` bazel run //scripts:generate_maven_dependencies_list -- $(pwd) third_party/maven_install.json scripts/assets/maven_dependencies.textproto scripts/assets/maven_dependencies.pb ``` ## Handling Exception: `Too few arguments passed` -If after running the script the exception message says: **Too few arguments passed**, then please ensure that you copied the command correctly from [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies/_edit#running-generatemavendependencieslistkt-script). -The scripts exccepts 4 parameters to be passed to run successfully: +If after running the script the exception message says: **Too few arguments passed**, then please ensure that you copied the command correctly from [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies#running-generatemavendependencieslistkt-script). +The script accepts 4 parameters to be passed to run successfully: 1. **_path_to_directory_root_**: directory path to the root of the Oppia Android repository, e.g - `home//opensource/oppia-android` 2. **_path_to_maven_install_json_**: relative path to the maven_install.json file, e.g - `third_party/maven_install.json` 3. **_path_to_maven_dependencies_textproto_**: relative path to the maven_dependencies.textproto, e.g - `scripts/assets/maven_dependencies.textproto` @@ -85,12 +85,12 @@ license { } ``` -Also, if the license falls in the `extracted_copy_link` category, then go to [Oppia-android-licenses](https://github.com/oppia/oppia-android-licenses) and find if there exists a copy of the license already in the repository. If there exists a copy of the license, perform the following steps to get the link for the license that can be scraped easily - +Also, if the license falls in the `extracted_copy_link` category, then go to [Oppia-android-licenses](https://github.com/oppia/oppia-android-licenses) and find if there exists a copy of the license already in the repository. If there exists a copy of the license, perform the following steps to get the link for the license that can be scraped easily. 1. Click on the appropriate license file. 2. Now click on the raw button positioned in the left of the edit and delete button. 3. Copy the URL from the browser and mention it at the appropriate place. -If the license does not exist in Oppia-android-licenses repository, then coordinate with Oppia Android team and raise a PR to add a new license text file. Then repeat the above steps to update maven_dependencies.textproto. +If the license does not exist in the Oppia-android-licenses repository, then coordinate with the Oppia Android team and raise a PR to add a new license text file. Then repeat the above steps to update maven_dependencies.textproto. @@ -99,7 +99,7 @@ After modifying `maven_dependencies.textproto` for all the called out licenses i ## Handling Exception: `License links are invalid or not available for some dependencies` -If the script throws `License links are invalid or not available for some dependencies` exception, then the output would look something like this - +If the script throws `License links are invalid or not available for some dependencies` exception, then the output would look something like this: ``` Please remove all the invalid links (if any) from maven_dependencies.textproto for the below mentioned dependencies and provide the valid license links manually. @@ -120,9 +120,9 @@ maven_dependency { } ``` -To fix the error, consider the above example. For the first maven_dependency: "io.fabric.sdk.android:fabric:1.4.7", the original_link is invalid, and hence we need to find a valid link for this dependency. Please coordinate with the Oppia Android team and find a valid link for this dependency, once you have a valid link for this license then categorize it as mentioned [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies/_edit#categorizing-the-license-link). +To fix the error, consider the above example. For the first maven_dependency: "io.fabric.sdk.android:fabric:1.4.7", the original_link is invalid, and hence we need to find a valid link for this dependency. Please coordinate with the Oppia Android team and find a valid link for this dependency, once you have a valid link for this license then categorize it as mentioned [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies#categorizing-the-license-link). -For the second maven_dependency: "com.google.guava:failureaccess:1.0.1", you need to find a license by coordinating with Oppia Android team and then specify it under the artifact_version field of the dependency. e.g - +For the second maven_dependency: "com.google.guava:failureaccess:1.0.1", you need to find a license by coordinating with the Oppia Android team and then specify it under the artifact_version field of the dependency. e.g - ``` maven_dependency { From fa118944de2f10c4aed3ab834412d188777e97a0 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Wed, 21 Jul 2021 12:55:18 +0530 Subject: [PATCH 195/374] Rephrase "coordinating with Oppia Anroid team" sentence --- Updating-Maven-Dependencies.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index bf4b67c642c..4afbfc7a312 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -3,13 +3,13 @@ All the third-party Maven dependencies used in Oppia-Android along with their ve ## 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 dependency, run the following command. +2. After updating the dependencies, run the following command. ``` REPIN=1 bazel run @unpinned_maven//:pin ``` ## Updating `maven_dependencies.textproto` -If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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 in order 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). +If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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. ``` @@ -50,7 +50,7 @@ The first dependency that should be updated with the license: com.google.firebas ``` Go to `maven_dependencies.textproto` and find the dependency that is mentioned as `The first dependency that should be updated with the license` in the output. For example, in the above case, look for `com.google.firebase:firebase-analytics:17.5.0` in maven_dependencies.textproto and open the `original_link` of its license in your browser and check if the link points to any valid license or not. If the link does not point to a valid license, set the 'is_original_link_invalid' field of the license to 'true'. -For example, if the original_link https://www.xyz.com is invalid, then set `is_original_link_invalid` to true. +For example, if the original_link https://www.example.com is invalid, then set `is_original_link_invalid` to true. ``` maven_dependency { @@ -69,7 +69,7 @@ maven_dependency { If the link does point to a valid license then choose the most appropriate category for the link: 1. scrapable_link: If the license text is plain text and the URL mentioned can be scraped directly from the original_link of the license. e.g - https://www.apache.org/licenses/LICENSE-2.0.txt -2. extracted_copy_link: If the license text is plain text but it can not be scraped directly from the original_link of the license. +2. extracted_copy_link: If the license text is plain text but can not be scraped directly from the original_link of the license. e.g - https://www.opensource.org/licenses/bsd-license 3. direct_link_only: If the license text is not plain text, it's best to display only the link of the license. e.g - https://developer.android.com/studio/terms.html @@ -90,7 +90,7 @@ Also, if the license falls in the `extracted_copy_link` category, then go to [Op 2. Now click on the raw button positioned in the left of the edit and delete button. 3. Copy the URL from the browser and mention it at the appropriate place. -If the license does not exist in the Oppia-android-licenses repository, then coordinate with the Oppia Android team and raise a PR to add a new license text file. Then repeat the above steps to update maven_dependencies.textproto. +If the license does not exist in the Oppia-android-licenses repository, then coordinate with the Oppia Android team to fix it. Then repeat the above steps to update maven_dependencies.textproto. @@ -120,7 +120,7 @@ maven_dependency { } ``` -To fix the error, consider the above example. For the first maven_dependency: "io.fabric.sdk.android:fabric:1.4.7", the original_link is invalid, and hence we need to find a valid link for this dependency. Please coordinate with the Oppia Android team and find a valid link for this dependency, once you have a valid link for this license then categorize it as mentioned [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies#categorizing-the-license-link). +To fix the error, consider the above example. For the first maven_dependency: "io.fabric.sdk.android:fabric:1.4.7", the original_link is invalid, and hence we need to find a valid link for this dependency. Please coordinate with the Oppia Android team and find a valid link for this dependency. Once you have a valid link for this license then categorize it as mentioned [here](https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies#categorizing-the-license-link). For the second maven_dependency: "com.google.guava:failureaccess:1.0.1", you need to find a license by coordinating with the Oppia Android team and then specify it under the artifact_version field of the dependency. e.g - From 262fbf6cdc32e13426f5ffa6beecd859a88272dd Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 21 Jul 2021 14:32:58 -0700 Subject: [PATCH 196/374] Add mitigation instructions for the dex issue if people run into it locally. --- Oppia-Bazel-Setup-Instructions.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 616f269a61d..8ec39326b71 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -50,6 +50,12 @@ bazel test //app/... bazel test //... ``` +## Known issues + +#### 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. + ## Concepts and Terminology **[Workspace](https://github.com/oppia/oppia-android/blob/develop/WORKSPACE)**
A workspace is a directory where we add targetted 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. From 17bcb2731a63bf5194af5df0f0f328d48e76554b Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Thu, 22 Jul 2021 19:46:36 +0530 Subject: [PATCH 197/374] Specify dicts names --- Updating-Maven-Dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index 4afbfc7a312..498ee31535f 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -1,4 +1,4 @@ -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, please follow the below steps. +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` From 6a749614ba3cd1bdba771cdc4a55e83051ffff7e Mon Sep 17 00:00:00 2001 From: Akshay Nandwana Date: Sun, 25 Jul 2021 18:20:37 +0530 Subject: [PATCH 198/374] added Facing error while debugging code --- Frequent-Errors-and-Solutions.md | 35 ++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md index 636961af7a7..bb6cb230a52 100644 --- a/Frequent-Errors-and-Solutions.md +++ b/Frequent-Errors-and-Solutions.md @@ -1,14 +1,41 @@ -## Unresolved reference Dagger +## 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. +**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. ## Push failed **Error**: Failed to push some refs to `git@github.com:/oppia-android.git` -**Solution**: If you are using Android Studio or other UI based git to push and got the above error, this might not provide many details. Try to push using the command line. Also, we suggest using the command line, as all our scripts, project building, APK building is done using the command line as we are moving towards the Bazel build system and removing the Gradle build system. +**Solution**: If you are using Android Studio or another UI-based git to push and got the above error, this might not provide many details. Try to push using the command line. Also, we suggest using the command line, as all our scripts, project building, APK building are done using the command line as we are moving towards the Bazel build system and removing the Gradle build system. -If there is any error with any of the lint failure it will be detailed in the command line itself. +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 From 66b019661d6ee4f31bca92cc55189221797370c4 Mon Sep 17 00:00:00 2001 From: Abhay Garg <54636525+prayutsu@users.noreply.github.com> Date: Sat, 31 Jul 2021 23:57:45 +0530 Subject: [PATCH 199/374] Updated Updating Maven Dependencies (markdown) --- Updating-Maven-Dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Updating-Maven-Dependencies.md b/Updating-Maven-Dependencies.md index 498ee31535f..cb08415d296 100644 --- a/Updating-Maven-Dependencies.md +++ b/Updating-Maven-Dependencies.md @@ -9,7 +9,7 @@ REPIN=1 bazel run @unpinned_maven//:pin ``` ## Updating `maven_dependencies.textproto` -If the update is performed in the `MAVEN_PRODUCTION_DEPENDENCY_VERSIONS` dictionary of the `versions.bzl` file, 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). +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. ``` From 8fc7e749e273ced49d14c657085169d1e10b8903 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 13 Aug 2021 11:54:58 -0700 Subject: [PATCH 200/374] Create initial placeholder for Static Analysis Checks. --- Static-Analysis-Checks.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 Static-Analysis-Checks.md diff --git a/Static-Analysis-Checks.md b/Static-Analysis-Checks.md new file mode 100644 index 00000000000..7e9922646e4 --- /dev/null +++ b/Static-Analysis-Checks.md @@ -0,0 +1 @@ +TODO: Will be filled in by Sparsh. \ No newline at end of file From d522dacf8eece04c44f93617630676defbda18a0 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Sun, 15 Aug 2021 21:17:57 +0530 Subject: [PATCH 201/374] Created Platform Parameters & Feature Flags (markdown) --- Platform-Parameters-&-Feature-Flags.md | 137 +++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 Platform-Parameters-&-Feature-Flags.md diff --git a/Platform-Parameters-&-Feature-Flags.md b/Platform-Parameters-&-Feature-Flags.md new file mode 100644 index 00000000000..80dc4cfa74a --- /dev/null +++ b/Platform-Parameters-&-Feature-Flags.md @@ -0,0 +1,137 @@ +# Platform Parameters & Feature Flags +## 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 Prameters 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 constants here. First will be a Qualifier Anotation which will help us to distinguish our Platform Parameter from others. Second constant will be the name of the Platform Parameter in String format and third constant will be the default value for the Platform Parameter. For eg - here we define a **SyncUpTimePeriod** platform parameter and its constants. + +``` +/** + * Qualifier for the platform parameter that defines the time period in hours, after which the + * [PlatformParameterSyncUpWorker] will run again. + */ +@Qualifier +annotation class SyncUpWorkerTimePeriod + +/** + * 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" + +/** + * 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\, PlatformPrameterValue\ Or PlatformPrameterValue\ depending on the data type of the Platform Parameter you intend to create. For eg- here we provide **SyncUpTimePeriod** platform parameter, which is actually of integer type. + +``` +/* Dagger module that provides values for individual Platform Parameters. */ +@Module +class PlatformParameterModule { +... + @Provides + @SyncUpWorkerTimePeriod + fun provideSyncUpWorkerTimePeriod(platformParameterSingleton: PlatformParameterSingleton): PlatformParameterValue { + return platformParameterSingleton.getIntegerPlatformParameter( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS + ) ?: PlatformParameterValue.createDefaultParameter( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE + ) + } +} +``` + +Note: If the Platform Parameter that you are creating will be only be a Compile Time platform parameter then we do not need to follow the third step. + +3. Add Platform Parameters to Feature Gating Console + - Add the name and the value of our Platform Parameter. This change will make our Compile-Time Platform Parameter to be a Run-Time Platform Parameter. Which actualy means now we can control its value from backend. + - As this console is very important for Oppia therefore for security purpose you would probably be needing to ask for some permission to use the Feature Gating Console. + + +## How to consume a Platform Parameter +To consume a Platform Parameter in any file, we just need to inject the specific PlatformParameterValue\ instance along with the Qualifier Anotation defined for that Parameter. For eg - we are injecting the **SyncUpTimePeriod** platform parameter in **PlatformParameterSyncUpWorkManagerInitializer** + +``` +class PlatformParameterSyncUpWorkManagerInitializer @Inject constructor( + private val context: Context, + @SyncUpWorkerTimePeriod private val syncUpWorkerTimePeriod : PlatformParameterValue +) : ApplicationStartupListener { + ... + fun exampleFunction(){ + val time: Int = syncUpWorkerTimePeriod.value + // now we can use the value in the "time" variable, which will be an integer. + } +} +``` + +## How to write tests related Platform Parameter +Before writing a test we must check what is the actual need for platform parameter in our class/classes (that needs to be tested). After verifying this we can divide testing procedures into following groups - + +### 1. We actually don't test for platform parameter(s) +We just need specific platform parameter(s) in the dagger graph because our class needs it, but our test cases are not actually verifying the behaviour of class based on different values of the platform parameter. These are the simplest cases to write tests for. We will only need to create a TestModule inside the Test class and then include this into the @Component for the TestApplicationComponent. For eg - + +``` +@Module +class TestModule { + @Provides + @SyncUpWorkerTimePeriod + fun provideSyncUpWorkerTimePeriod(): PlatformParameterValue { + return PlatformParameterValue.createDefaultParameter( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE + ) + } +} + +@Singleton +@Component(modules = [TestModule::class, ... ]) +interface TestApplicationComponent { + @Component.Builder + interface Builder { + @BindsInstance + fun setApplication(application: Application): Builder + fun build(): TestApplicationComponent + } + fun inject(platformParameterSyncUpWorkManagerInitializerTest: PlatformParameterSyncUpWorkManagerInitializerTest) +} +``` + +### 2. We test for different values of platform parameter(s) +We need to test the behaviour of the target class/classses based on different values of the platform parameter. Same platform parameter can have different values because of the difference between its compile-time/default and runtime/server value. To test for this case we can a set up a fake singleton class and provide the seed values that we want to be injected into target classes. For eg - + +``` +@Test +fun testSyncUpWorker_checkIfServerValueOfSyncUpTimePeriodIsUsed(){ + val seedValues = mapOf( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS to SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_SERVER_VALUE + ) + setUpTestApplicationComponent(seedValues) + // Continue your normal testing +} + +private fun setUpTestApplicationComponent(seedValues: Map) { + MockPlatformParameterSingleton.seedPlatformParameterMap.putAll(seedValues) + ApplicationProvider.getApplicationContext().inject(this) +} + +@Module +class TestModule { + @Provides + fun provideMockPlatformParameterSingleton( + platformParameterSingletonImpl: PlatformParameterSingletonImpl + ) : PlatformParameterSingleton { + return MockPlatformParameterSingleton(platformParameterSingletonImpl) + } +} +``` + +Note : To understand how does this way of testing with PlatformParameterSingleton works, you will need to understand about how actually does these platform parameters reach the dagger graph. You can refer to this [document](https://docs.google.com/document/d/1o8MtAO8e8bX7UtWFYx-T9G4vCGRfvY9oIwDutDn4pVM/edit#heading=h.m1q1hwhhqigf) for detailed explanation over what is the flow for the platform parameter architecture. From 1d15dcac3861e048b737e790b592ec6aca428cdd Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Sun, 15 Aug 2021 21:18:50 +0530 Subject: [PATCH 202/374] Updated Platform Parameters & Feature Flags (markdown) --- Platform-Parameters-&-Feature-Flags.md | 1 - 1 file changed, 1 deletion(-) diff --git a/Platform-Parameters-&-Feature-Flags.md b/Platform-Parameters-&-Feature-Flags.md index 80dc4cfa74a..b4233b6c39f 100644 --- a/Platform-Parameters-&-Feature-Flags.md +++ b/Platform-Parameters-&-Feature-Flags.md @@ -1,4 +1,3 @@ -# Platform Parameters & Feature Flags ## 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). From c62f40d5af0e31982a7940405144488fb383e5bb Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Mon, 16 Aug 2021 20:01:03 +0530 Subject: [PATCH 203/374] Updated Platform Parameters & Feature Flags (markdown) --- Platform-Parameters-&-Feature-Flags.md | 120 ++++++++++++++----------- 1 file changed, 68 insertions(+), 52 deletions(-) diff --git a/Platform-Parameters-&-Feature-Flags.md b/Platform-Parameters-&-Feature-Flags.md index b4233b6c39f..ae585394b55 100644 --- a/Platform-Parameters-&-Feature-Flags.md +++ b/Platform-Parameters-&-Feature-Flags.md @@ -5,60 +5,77 @@ In order to release these types of features in a smooth manner, we need to be ab ## 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 Prameters 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 constants here. First will be a Qualifier Anotation which will help us to distinguish our Platform Parameter from others. Second constant will be the name of the Platform Parameter in String format and third constant will be the default value for the Platform Parameter. For eg - here we define a **SyncUpTimePeriod** platform parameter and its constants. - -``` -/** - * Qualifier for the platform parameter that defines the time period in hours, after which the - * [PlatformParameterSyncUpWorker] will run again. - */ -@Qualifier -annotation class SyncUpWorkerTimePeriod - -/** - * 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" - -/** - * 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 -``` + - 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 SyncUpWorkerTimePeriod + ``` + + 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 **SyncUpTimePeriod** 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\, PlatformPrameterValue\ Or PlatformPrameterValue\ depending on the data type of the Platform Parameter you intend to create. For eg- here we provide **SyncUpTimePeriod** platform parameter, which is actually of integer type. - -``` -/* Dagger module that provides values for individual Platform Parameters. */ -@Module -class PlatformParameterModule { -... - @Provides - @SyncUpWorkerTimePeriod - fun provideSyncUpWorkerTimePeriod(platformParameterSingleton: PlatformParameterSingleton): PlatformParameterValue { - return platformParameterSingleton.getIntegerPlatformParameter( - SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS - ) ?: PlatformParameterValue.createDefaultParameter( - SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE - ) - } -} -``` - -Note: If the Platform Parameter that you are creating will be only be a Compile Time platform parameter then we do not need to follow the third step. - -3. Add Platform Parameters to Feature Gating Console - - Add the name and the value of our Platform Parameter. This change will make our Compile-Time Platform Parameter to be a Run-Time Platform Parameter. Which actualy means now we can control its value from backend. - - As this console is very important for Oppia therefore for security purpose you would probably be needing to ask for some permission to use the Feature Gating Console. + - The return type for this @Provides annotated method will be equal to either PlatformPrameterValue\, PlatformPrameterValue\ Or PlatformPrameterValue\ depending on the data type of the Platform Parameter you intend to create. Any other type will cause the platform parameter sync to fail. For eg- here we provide **SyncUpTimePeriod** platform parameter, which is actually of integer type. + +
+ + ``` + /* Dagger module that provides values for individual Platform Parameters. */ + @Module + class PlatformParameterModule { + ... + @Provides + @SyncUpWorkerTimePeriod + fun provideSyncUpWorkerTimePeriod(platformParameterSingleton: PlatformParameterSingleton): PlatformParameterValue { + return platformParameterSingleton.getIntegerPlatformParameter( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS + ) ?: PlatformParameterValue.createDefaultParameter( + SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE + ) + } + } + ``` + +Note: If the Platform Parameter that you are creating will only be a Compile Time platform parameter then we do not need to follow the third step. + +3. Add Platform Parameters to Feature Gating Console (only for runtime parameters) + - Add the name and the value of our Platform Parameter. This change will make our Compile-Time Platform Parameter to be a Run-Time Platform Parameter. This means that we can control its value from backend. + - Note that permission will be required before accessing the Feature Gating console in the Oppia backend. ## How to consume a Platform Parameter -To consume a Platform Parameter in any file, we just need to inject the specific PlatformParameterValue\ instance along with the Qualifier Anotation defined for that Parameter. For eg - we are injecting the **SyncUpTimePeriod** platform parameter in **PlatformParameterSyncUpWorkManagerInitializer** +To consume a Platform Parameter in any file, we need to inject the specific PlatformParameterValue\ instance along with the Qualifier Annotation defined for that Parameter. For eg - we are injecting the **SyncUpTimePeriod** platform parameter in **PlatformParameterSyncUpWorkManagerInitializer** ``` class PlatformParameterSyncUpWorkManagerInitializer @Inject constructor( @@ -74,7 +91,7 @@ class PlatformParameterSyncUpWorkManagerInitializer @Inject constructor( ``` ## How to write tests related Platform Parameter -Before writing a test we must check what is the actual need for platform parameter in our class/classes (that needs to be tested). After verifying this we can divide testing procedures into following groups - +Before writing a test we must understand the purpose of the platform parameter in our class/classes (that needs to be tested). After verifying this we can divide testing procedures into following groups - ### 1. We actually don't test for platform parameter(s) We just need specific platform parameter(s) in the dagger graph because our class needs it, but our test cases are not actually verifying the behaviour of class based on different values of the platform parameter. These are the simplest cases to write tests for. We will only need to create a TestModule inside the Test class and then include this into the @Component for the TestApplicationComponent. For eg - @@ -105,8 +122,7 @@ interface TestApplicationComponent { ``` ### 2. We test for different values of platform parameter(s) -We need to test the behaviour of the target class/classses based on different values of the platform parameter. Same platform parameter can have different values because of the difference between its compile-time/default and runtime/server value. To test for this case we can a set up a fake singleton class and provide the seed values that we want to be injected into target classes. For eg - - +We need to test the behaviour of the target class/classes based on different values of the platform parameter. Same platform parameter can have different values because of the difference between its compile-time/default and runtime/server value. To test for this case we can set up a fake singleton class and provide the seed values that we want to be injected into target classes. For eg - ``` @Test fun testSyncUpWorker_checkIfServerValueOfSyncUpTimePeriodIsUsed(){ @@ -133,4 +149,4 @@ class TestModule { } ``` -Note : To understand how does this way of testing with PlatformParameterSingleton works, you will need to understand about how actually does these platform parameters reach the dagger graph. You can refer to this [document](https://docs.google.com/document/d/1o8MtAO8e8bX7UtWFYx-T9G4vCGRfvY9oIwDutDn4pVM/edit#heading=h.m1q1hwhhqigf) for detailed explanation over what is the flow for the platform parameter architecture. +Note : To understand the underlying mechanism of this test, you will need to understand how these platform parameters reach the dagger graph. You can refer to this [document](https://docs.google.com/document/d/1o8MtAO8e8bX7UtWFYx-T9G4vCGRfvY9oIwDutDn4pVM/edit#heading=h.m1q1hwhhqigf) for detailed explanation about the flow for the platform parameter architecture. From df86f1352dd78d3b0ce9785e7849d838c2a43b54 Mon Sep 17 00:00:00 2001 From: Sparsh Agrawal <55937724+Sparsh1212@users.noreply.github.com> Date: Tue, 17 Aug 2021 06:25:27 +0530 Subject: [PATCH 204/374] Updated Static Analysis Checks (markdown) --- Static-Analysis-Checks.md | 189 +++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 1 deletion(-) diff --git a/Static-Analysis-Checks.md b/Static-Analysis-Checks.md index 7e9922646e4..ff45590a6f3 100644 --- a/Static-Analysis-Checks.md +++ b/Static-Analysis-Checks.md @@ -1 +1,188 @@ -TODO: Will be filled in by Sparsh. \ No newline at end of file +# Background +Static analysis is a method of debugging by examining source code before a program is run. It’s done by analyzing a set of code against a set (or multiple sets) of coding rules. + +The primary benefit is that it increases our ability to reliably enforce best practices. This is because humans make mistakes. Humans can unknowingly miss some places while reviewing, but with static analysis, this scenario will never happen. + +It takes time for developers to do manual code reviews. Automated tools are much faster. +Static code checking helps to detect problems early on by pinpointing exactly where the error is in the code before a reviewer even looks at it. + +Development flow without static analysis + + +Development flow without static analysis + +Development flow with 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 , e.g.: +``` +filename_checks { + prohibited_filename_regex: "^((?!(app|testing)).)+/src/main/.+?Activity.kt" + failure_message: "Activities cannot be placed outside the app or testing module" + exempted_file_name: "testing/src/main/SampleActivity.kt" +} +``` +2. Add an explanation to your PR description detailing why this exemption is correct + +### Generic regex pattern matching against file contents +This check ensures that there are no prohibited file contents present in the repository. + +### Purpose & adding new patterns +This check is needed so as to prevent the use of any prohibited content in a file which allows the team to introduce specific best practices checks. + +For example: If we want to prevent the use of support library in the repository, then we have to add its regex pattern in the [scripts/assets/file_content_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/file_content_validation_checks.textproto) file like this: +``` +file_content_checks { + filename_regex: ".+?.kt" + prohibited_content_regex: "^import .+?support.+?$" + failure_message: "AndroidX should be used instead of the support library" +} +``` +### Fixing failures +In general, failures for this check should be fixed by not using the prohibited content in the repository (the error message of the failure should explain what should be used, instead). +In cases where that can’t happen or the check is wrong, please: +1. Add the file as an exemption in [scripts/assets/file_content_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/file_content_validation_checks.textproto) for the particular check which is failing. +For example: a file which has relative path to root as app/src/main/java/org/oppia/android/home/SampleActivity.kt, should be added as follows to the corresponding failing check: +``` +file_content_checks { + filename_regex: ".+?.kt" + prohibited_content_regex: "^import .+?support.+?$" + failure_message: "AndroidX should be used instead of the support library" + exempted_file_name: "app/src/main/java/org/oppia/android/home/SampleActivity.kt" +} +``` +2. Add an explanation to your PR description detailing why this exemption is correct + +## XML syntax check +This check ensures that all the XML files present in the repository are syntactically correct. +### Purpose +There are no linters to evaluate XML correctness. This check performs a fast check of correctness before any attempts to build the app will complete, allowing for a faster feedback cycle for potential XML issues. +### Fixing failures +To fix failures for this check: correct the syntax of the XML file which is failing the check. + +## Test file presence check +This check ensures that all the production (file which is not a test file) Kotlin files must have a corresponding test file present. +### Purpose +To ensure that we are not missing tests for any production file being added to the codebase, this check is needed. It helps us to ensure production files have corresponding tests and reminds the contributor to add tests for new code added. +### Fixing failures +In general, failures for this check should be fixed by: adding a corresponding test file which has tests for the file which fails this check. Note that: the file name of the added test file must be file_name without extension + “Test.kt”. +For example: For a file named as “SampleFragment.kt” failing this check, the name of the added test file should be “SampleFragmentTest.kt”. + +In cases where a test can’t be added, or the check is wrong, please: +1. Add it as an exemption by providing its relative path to root in [script/assets/test_file_exemptions.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/test_file_exemptions.textproto). +Also, note that the file paths in the textproto file are maintained in lexicographical order. While adding any new file, please add it only at the correct lexicographical position, so that the list remains sorted. +For example if we want to add the 'ActivityComponent.kt' file to the exemption list, add: +``` +exempted_file_path: "app/src/main/java/org/oppia/android/app/activity/ActivityComponent.kt" +``` +at the correct lexicographical position in the textproto file. +2. Add an explanation to your PR description detailing why this exemption is correct. + +Following are the cases where its valid to have test file exemptions: +1. Interface files +2. Files with only constants defined (no logic) + +## Accessibility label check +This check ensures that activities are defined with accessibility labels. +### Purpose +For users requiring accessibility assistance (e.g. using a screen reader), activity labels are very important since they are read by screen readers to provide context on where the user is within the app. Suppose, on the button click, the app transits to a new activity. An unassisted user will likely face no barriers in understanding that a new screen/activity has opened, but accessibility users need an indication so that they can be notified that the transition to a new activity has been successfully made. For this reason, all activities must be defined with accessibility labels. +### Fixing failures +If it’s a production activity, add a label. + +If it’s a test activity or an activity that can’t/shouldn’t have a label, add an exemption by providing its relative path to root in [script/assets/accessibility_label_exemptions.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/accessibility_label_exemptions.textproto). If an exemption is added, please include a rationale in your PR description explaining why this exemption is correct. +Also, note that the exemptions in the textproto file are maintained in lexicographical order. While adding any new Activity, please add it only at the correct lexicographical position, so that the list remains sorted. + +For example if we want to add the 'RecentlyPlayedActivity' to the exemption list, add: +``` +exempted_activity: "app/src/main/java/org/oppia/android/app/home/HomeActivity" +``` +at the correct lexicographical position in the textproto file. + +## KDoc validity check +This check ensures that all non-private declarations/members are documented with KDocs. +### Purpose +To ensure that we are not missing the documentation for any non-private decorations or members, this check is needed. Documentation is very important as it helps team members understand specific contexts within the codebase. Therefore, we should document as much as we can. Further, to ensure consistency we generally expect that all non-private members within Kotlin files are documented (per our [style guide](https://developer.android.com/kotlin/style-guide#usage)). +### Fixing failures +To fix failures for this check is to add a KDoc at the member which is missing it. Please refer to the failure logs to get the exact location (file path and line number) of the failure. For guidance on how to write KDocs, please look at our [style guide](https://developer.android.com/kotlin/style-guide#usage). + +## TODO open checks +This check ensures that every TODO present in the codebase corresponds to open issues on GitHub and is also correctly formatted as per the convention. +### Purpose +To avoid scenarios where a TODO was added not corresponding to an open issue on GitHub, this check is particularly needed. Having a corresponding issue for a TODO helps us to track its progress. Also, in order to maintain consistency we want all the TODOs to be formatted as per the convention. +### Fixing failures + +#### TODO formatting failure +To fix the formatting failure, please make sure that the added TODO is strictly as per this format (please pay attention to the whitespaces): + +Kotlin & Java files: +``` +// TODO(#ISSUE_NUMBER): +``` +Shell & BUILD/Bazel files: +``` +# TODO(#ISSUE_NUMBER): +``` +XML files: +``` + +``` +#### TODO Open issue failure +To fix this failure: there are 3 ways: +1. Repurpose the TODO to a new issue. +2. If the TODO has been resolved then please remove it from the repository. +3. Reopen the issue. +#### Case when using ‘TODO’ keyword for documentation purposes +If it’s a case where a ‘TODO’ keyword has been used for documentation purposes or if it's not meant to correspond to a future work, then please add an exemption for it. Add a new TODO exemption in the [scripts/assets/todo_open_exemptions.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/todo_open_exemptions.textproto). +Example: +``` +todo_open_exemption { + exempted_file_path: , + line_number: +} +``` + +## TODO issue resolved check +The check ensures that a TODO issue is not closed until all of its corresponding TODO items are resolved. +### Purpose +We need this check to avoid scenarios like missing a TODO item not being resolved and its issue being mistakenly closed, since this should result in confusing contexts where a team member looking up a particular TODO from code sees that the issue is closed and isn’t sure whether the issue has actually been resolved. If a TODO issue is closed without resolving all of its TODO items, then it will be reopened automatically by the GitHub actions bot with a comment containing the unresolved TODOs. +### Fixing failures +To fix the failures for this check: resolve the TODO items and then close the issue. If the TODO items are not resolved the issue will remain in the open state. + +## Java lint check +// TODO([#3690](https://github.com/oppia/oppia-android/issues/3690)): Complete static checks Wiki + +## Kotlin lint check +// TODO([#3690](https://github.com/oppia/oppia-android/issues/3690)): Complete static checks Wiki + +## Protobuf lint check +// TODO([#3690](https://github.com/oppia/oppia-android/issues/3690)): Complete static checks Wiki + +## Bazel lint check +// TODO([#3690](https://github.com/oppia/oppia-android/issues/3690)): Complete static checks Wiki + +# How to add a new Static analysis check +// TODO([#3690](https://github.com/oppia/oppia-android/issues/3690)): Complete static checks Wiki From 442d9af08f381a88a1764d0d870d61184efadfaf Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 16 Aug 2021 18:19:16 -0700 Subject: [PATCH 205/374] Some fixes and cleanup. --- Static-Analysis-Checks.md | 51 ++++++++++++++++++++++++++++++--------- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/Static-Analysis-Checks.md b/Static-Analysis-Checks.md index ff45590a6f3..0a988854067 100644 --- a/Static-Analysis-Checks.md +++ b/Static-Analysis-Checks.md @@ -6,15 +6,23 @@ The primary benefit is that it increases our ability to reliably enforce best pr It takes time for developers to do manual code reviews. Automated tools are much faster. Static code checking helps to detect problems early on by pinpointing exactly where the error is in the code before a reviewer even looks at it. -Development flow without static analysis +
+

+Development flow without static analysis figure -Development flow without static analysis +

Development flow without static analysis
+

-Development flow with static analysis +


+

+Development flow with static analysis figure -Development flow with 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. @@ -26,18 +34,22 @@ This page outlines the static analysis checks implemented in Oppia Android, inst ### 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 + +#### 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 + +#### 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 , e.g.: ``` filename_checks { @@ -51,10 +63,11 @@ filename_checks { ### Generic regex pattern matching against file contents This check ensures that there are no prohibited file contents present in the repository. -### Purpose & adding new patterns +#### Purpose & adding new patterns This check is needed so as to prevent the use of any prohibited content in a file which allows the team to introduce specific best practices checks. For example: If we want to prevent the use of support library in the repository, then we have to add its regex pattern in the [scripts/assets/file_content_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/file_content_validation_checks.textproto) file like this: + ``` file_content_checks { filename_regex: ".+?.kt" @@ -62,9 +75,12 @@ file_content_checks { failure_message: "AndroidX should be used instead of the support library" } ``` -### Fixing failures + +#### Fixing failures In general, failures for this check should be fixed by not using the prohibited content in the repository (the error message of the failure should explain what should be used, instead). + In cases where that can’t happen or the check is wrong, please: + 1. Add the file as an exemption in [scripts/assets/file_content_validation_checks.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/file_content_validation_checks.textproto) for the particular check which is failing. For example: a file which has relative path to root as app/src/main/java/org/oppia/android/home/SampleActivity.kt, should be added as follows to the corresponding failing check: ``` @@ -79,27 +95,30 @@ file_content_checks { ## XML syntax check This check ensures that all the XML files present in the repository are syntactically correct. + ### Purpose There are no linters to evaluate XML correctness. This check performs a fast check of correctness before any attempts to build the app will complete, allowing for a faster feedback cycle for potential XML issues. + ### Fixing failures To fix failures for this check: correct the syntax of the XML file which is failing the check. ## Test file presence check This check ensures that all the production (file which is not a test file) Kotlin files must have a corresponding test file present. + ### Purpose To ensure that we are not missing tests for any production file being added to the codebase, this check is needed. It helps us to ensure production files have corresponding tests and reminds the contributor to add tests for new code added. + ### Fixing failures In general, failures for this check should be fixed by: adding a corresponding test file which has tests for the file which fails this check. Note that: the file name of the added test file must be file_name without extension + “Test.kt”. For example: For a file named as “SampleFragment.kt” failing this check, the name of the added test file should be “SampleFragmentTest.kt”. In cases where a test can’t be added, or the check is wrong, please: + 1. Add it as an exemption by providing its relative path to root in [script/assets/test_file_exemptions.textproto](https://github.com/oppia/oppia-android/blob/2da95a53928bc989f5959fbac211f7f7ca0a753f/scripts/assets/test_file_exemptions.textproto). -Also, note that the file paths in the textproto file are maintained in lexicographical order. While adding any new file, please add it only at the correct lexicographical position, so that the list remains sorted. -For example if we want to add the 'ActivityComponent.kt' file to the exemption list, add: +Also, note that the file paths in the textproto file are maintained in lexicographical order. While adding any new file, please add it only at the correct lexicographical position, so that the list remains sorted. For example if we want to add the 'ActivityComponent.kt' file to the exemption list, at the correct lexicographical position in the textproto file add: ``` exempted_file_path: "app/src/main/java/org/oppia/android/app/activity/ActivityComponent.kt" ``` -at the correct lexicographical position in the textproto file. 2. Add an explanation to your PR description detailing why this exemption is correct. Following are the cases where its valid to have test file exemptions: @@ -108,8 +127,10 @@ Following are the cases where its valid to have test file exemptions: ## Accessibility label check This check ensures that activities are defined with accessibility labels. + ### Purpose For users requiring accessibility assistance (e.g. using a screen reader), activity labels are very important since they are read by screen readers to provide context on where the user is within the app. Suppose, on the button click, the app transits to a new activity. An unassisted user will likely face no barriers in understanding that a new screen/activity has opened, but accessibility users need an indication so that they can be notified that the transition to a new activity has been successfully made. For this reason, all activities must be defined with accessibility labels. + ### Fixing failures If it’s a production activity, add a label. @@ -124,15 +145,19 @@ at the correct lexicographical position in the textproto file. ## KDoc validity check This check ensures that all non-private declarations/members are documented with KDocs. + ### Purpose To ensure that we are not missing the documentation for any non-private decorations or members, this check is needed. Documentation is very important as it helps team members understand specific contexts within the codebase. Therefore, we should document as much as we can. Further, to ensure consistency we generally expect that all non-private members within Kotlin files are documented (per our [style guide](https://developer.android.com/kotlin/style-guide#usage)). + ### Fixing failures -To fix failures for this check is to add a KDoc at the member which is missing it. Please refer to the failure logs to get the exact location (file path and line number) of the failure. For guidance on how to write KDocs, please look at our [style guide](https://developer.android.com/kotlin/style-guide#usage). +To fix failures for this check is to add a KDoc at the member which is missing it. Please refer to the failure logs to get the exact location (file path and line number) of the failure. For guidance on how to write KDocs, please look at our [style guide](https://developer.android.com/kotlin/style-guide). ## TODO open checks This check ensures that every TODO present in the codebase corresponds to open issues on GitHub and is also correctly formatted as per the convention. + ### Purpose To avoid scenarios where a TODO was added not corresponding to an open issue on GitHub, this check is particularly needed. Having a corresponding issue for a TODO helps us to track its progress. Also, in order to maintain consistency we want all the TODOs to be formatted as per the convention. + ### Fixing failures #### TODO formatting failure @@ -167,8 +192,10 @@ todo_open_exemption { ## TODO issue resolved check The check ensures that a TODO issue is not closed until all of its corresponding TODO items are resolved. + ### Purpose We need this check to avoid scenarios like missing a TODO item not being resolved and its issue being mistakenly closed, since this should result in confusing contexts where a team member looking up a particular TODO from code sees that the issue is closed and isn’t sure whether the issue has actually been resolved. If a TODO issue is closed without resolving all of its TODO items, then it will be reopened automatically by the GitHub actions bot with a comment containing the unresolved TODOs. + ### Fixing failures To fix the failures for this check: resolve the TODO items and then close the issue. If the TODO items are not resolved the issue will remain in the open state. From 23ec078daa9c83f6393cb159cc6df8a8bcac8076 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Sat, 21 Aug 2021 15:12:39 +0530 Subject: [PATCH 206/374] Updated Platform Parameters & Feature Flags (markdown) --- Platform-Parameters-&-Feature-Flags.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Platform-Parameters-&-Feature-Flags.md b/Platform-Parameters-&-Feature-Flags.md index ae585394b55..0ce92cb7d10 100644 --- a/Platform-Parameters-&-Feature-Flags.md +++ b/Platform-Parameters-&-Feature-Flags.md @@ -17,7 +17,7 @@ In order to release these types of features in a smooth manner, we need to be ab * [PlatformParameterSyncUpWorker] will run again. */ @Qualifier - annotation class SyncUpWorkerTimePeriod + annotation class SyncUpWorkerTimePeriodInHours ``` 2. The name of the Platform Parameter in String format @@ -32,7 +32,7 @@ In order to release these types of features in a smooth manner, we need to be ab 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 **SyncUpTimePeriod** platform parameter and its constants. + 3. The default value for the Platform Parameter. For eg - here we define a `SyncUpTimePeriodInHours` platform parameter and its constants.
@@ -45,8 +45,8 @@ In order to release these types of features in a smooth manner, we need to be ab ``` 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\, PlatformPrameterValue\ Or PlatformPrameterValue\ depending on the data type of the Platform Parameter you intend to create. Any other type will cause the platform parameter sync to fail. For eg- here we provide **SyncUpTimePeriod** platform parameter, which is actually of integer type. + - 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\`, `PlatformPrameterValue\` Or `PlatformPrameterValue\` depending on the data type of the Platform Parameter you intend to create. Any other type will cause the platform parameter sync to fail. For eg- here we provide `SyncUpTimePeriodInHours` platform parameter, which is actually of integer type.
@@ -56,7 +56,7 @@ In order to release these types of features in a smooth manner, we need to be ab class PlatformParameterModule { ... @Provides - @SyncUpWorkerTimePeriod + @SyncUpWorkerTimePeriodInHours fun provideSyncUpWorkerTimePeriod(platformParameterSingleton: PlatformParameterSingleton): PlatformParameterValue { return platformParameterSingleton.getIntegerPlatformParameter( SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS @@ -75,12 +75,12 @@ Note: If the Platform Parameter that you are creating will only be a Compile Tim ## How to consume a Platform Parameter -To consume a Platform Parameter in any file, we need to inject the specific PlatformParameterValue\ instance along with the Qualifier Annotation defined for that Parameter. For eg - we are injecting the **SyncUpTimePeriod** platform parameter in **PlatformParameterSyncUpWorkManagerInitializer** +To consume a Platform Parameter in any file, we need to inject the specific `PlatformParameterValue\` instance along with the Qualifier Annotation defined for that Parameter. For eg - we are injecting the `SyncUpTimePeriodInHours` platform parameter in `PlatformParameterSyncUpWorkManagerInitializer` ``` class PlatformParameterSyncUpWorkManagerInitializer @Inject constructor( private val context: Context, - @SyncUpWorkerTimePeriod private val syncUpWorkerTimePeriod : PlatformParameterValue + @SyncUpWorkerTimePeriodInHours private val syncUpWorkerTimePeriod : PlatformParameterValue ) : ApplicationStartupListener { ... fun exampleFunction(){ @@ -94,13 +94,13 @@ class PlatformParameterSyncUpWorkManagerInitializer @Inject constructor( Before writing a test we must understand the purpose of the platform parameter in our class/classes (that needs to be tested). After verifying this we can divide testing procedures into following groups - ### 1. We actually don't test for platform parameter(s) -We just need specific platform parameter(s) in the dagger graph because our class needs it, but our test cases are not actually verifying the behaviour of class based on different values of the platform parameter. These are the simplest cases to write tests for. We will only need to create a TestModule inside the Test class and then include this into the @Component for the TestApplicationComponent. For eg - +We just need specific platform parameter(s) in the dagger graph because our class needs it, but our test cases are not actually verifying the behaviour of class based on different values of the platform parameter. These are the simplest cases to write tests for. We will only need to create a `TestModule` inside the Test class and then include this into the @Component for the `TestApplicationComponent`. For eg - ``` @Module class TestModule { @Provides - @SyncUpWorkerTimePeriod + @SyncUpWorkerTimePeriodInHours fun provideSyncUpWorkerTimePeriod(): PlatformParameterValue { return PlatformParameterValue.createDefaultParameter( SYNC_UP_WORKER_TIME_PERIOD_IN_HOURS_DEFAULT_VALUE From d946d7f8619f8a604d5555e6acd24d1e7e16d3cb Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 22 Aug 2021 11:02:57 +0530 Subject: [PATCH 207/374] Created End-to-End testing (markdown) --- End-to-End-testing.md | 90 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 End-to-End-testing.md diff --git a/End-to-End-testing.md b/End-to-End-testing.md new file mode 100644 index 00000000000..3d7a6c59859 --- /dev/null +++ b/End-to-End-testing.md @@ -0,0 +1,90 @@ +## 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. [Setup 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//Android/Sdk/platform-tools:$PATH + ``` +3. download and install [test-services-1.1.0.apk](https://mvnrepository.com/artifact/androidx.test.services/test-services/1.1.0) and [orchestrator-1.1.0.apk](https://mvnrepository.com/artifact/androidx.test/orchestrator/1.1.0) in the emulator. (run command in the directory where both apk are downloaded) + ``` + adb install -r test-services-1.1.0.apk && adb install -r orchestrator-1.1.0.apk + ``` + +4. java version 8 (Optional, only for uiautomatorviewer) + ``` + java -version + ``` + *output:* + openjdk version "1.8.0_292" + OpenJDK Runtime Environment (build 1.8.0_292-8u292-b10-0ubuntu1~18.04-b10) + OpenJDK 64-Bit Server VM (build 25.292-b10, mixed mode) + +#### Steps to run the tests + +1. Build the oppia_test and test suite android_binary from the instrumentation module + ``` + bazel build :oppia_test && bazel build //instrumentation: + ``` + e.g.: + ``` + bazel build :oppia_test && bazel build //instrumentation/src/javatests/org/oppia/android/instrumentation/player:ExplorationPlayerTestBinary + ``` +2. install the oppia_test.apk and the test suite’s APK + ``` + adb install -r bazel-bin/oppia_test.apk && adb install -r bazel-bin/instrumentation/.apk + ``` + e.g.: + ``` + adb install -r bazel-bin/oppia_test.apk && adb install -r bazel-bin/instrumentation/src/javatests/org/oppia/android/instrumentation/player/ExplorationPlayerTestBinary.apk + ``` +3. Run the instrumentation tests using am instrument command + ``` + adb shell 'CLASSPATH=$(pm path androidx.test.services) app_process / \ + androidx.test.services.shellexecutor.ShellMain am instrument -w -e clearPackageData true \ + -e targetInstrumentation org.oppia.android.app.instrumentation/androidx.test.runner.AndroidJUnitRunner \ + androidx.test.orchestrator/.AndroidTestOrchestrator' + ``` + **Note:** "-e clearPackageData true" is used to clear your app's data in between runs. + +### Best practices when writing End-to-End tests +1. Each test suite should use the macro [oppia_instrumentation_test](https://github.com/oppia/oppia-android/blob/develop/instrumentation/oppia_instrumentation_test.bzl#L7) which generates the necessary targets required for each test suite. +2. Tests should follow the best practices for [writing good tests in Oppia Android](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing), including ensuring that tests are focused on a single, high-level behavior that the suite wishes to verify as working (such as being able to play fully through an exploration). +3. Repetitive actions should be factored into helper methods. When these are generally useful for other end-to-end tests, they should be moved to [EndToEndTestHelper](https://github.com/oppia/oppia-android/blob/854071ab6adec35192be6d517ae16d2f3300ebb0/instrumentation/src/java/org/oppia/android/instrumentation/testing/EndToEndTestHelper.kt). +4. Prefer using existing helpers from ``EndToEndTestHelper`` rather than reimplementing them. +5. Prefer testing whole end-to-end flows rather than specific behaviors. For example: opening the app, downloading a topic, and being able to play it is an excellent end-to-end test since it’s verifying multiple cross-stack behaviors. Conversely, testing that a thumbnail is aligned correctly on the home screen is less useful and ought to be tested in Robolectric or Espresso local to the component showing that image. +6. Use uiautomatorviewer to get details of each view such as resource ID, content description, class, and other properties. From 7d263a3bf498fcc113cf063076fd797e2ecc1ed9 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Sat, 21 Aug 2021 22:35:19 -0700 Subject: [PATCH 208/374] Some small tweaks. --- End-to-End-testing.md => End-to-End-Testing-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename End-to-End-testing.md => End-to-End-Testing-Guide.md (98%) diff --git a/End-to-End-testing.md b/End-to-End-Testing-Guide.md similarity index 98% rename from End-to-End-testing.md rename to End-to-End-Testing-Guide.md index 3d7a6c59859..2544a7a6d05 100644 --- a/End-to-End-testing.md +++ b/End-to-End-Testing-Guide.md @@ -35,7 +35,7 @@ The android_binary of a test suite generates a test apk with the same name as th ### How to run an End-to-End test #### Prerequisites: -1. [Setup Bazel for Oppia](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions#installation) +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//Android/Sdk/platform-tools:$PATH From 72aa4a5136318c5da74d9c234bb0e01bcedb161b Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Sat, 21 Aug 2021 22:35:31 -0700 Subject: [PATCH 209/374] Updated End to End Testing Guide (markdown) From 696dfb6823a1d5bdf1a8879f7f3a1c4fd70aab79 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 24 Aug 2021 13:50:14 +0530 Subject: [PATCH 210/374] Added "Undo unnecessary changes" section --- Guidance-on-submitting-a-PR.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 6fb06df3ef8..345217aa46f 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -9,7 +9,7 @@ The following instructions will help you submit a PR effectively and in a clean 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. ## Clarification regarding **Assignees** and **Reviewers** section. -1. **Reviewers**: In this section, add one or more people who should review this PR. Once this section is filled out, it generally should not change throughout the timeline of the PR. +1. **Reviewers**: This section will be filled automatically by Oppia-Bot. Once this section is filled out, it generally should not change throughout the timeline of the PR. 2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More 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. @@ -18,14 +18,20 @@ The following instructions will help you submit a PR effectively and in a clean ## Checklist before submitting a PR Note: This checklist should be embedded in your every PR explanation with appropriate ticks. Please tick the relevant boxes by putting an "x" in them -- [ ] The PR title starts with "Fix #bugnum: ", followed by a short, clear summary of the changes. (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) -- [ ] The PR explanation includes the words "Fixes #bugnum: ..." (or "Fixes part of #bugnum" if the PR only partially fixes an issue). +- [ ] The PR title and explanation each start with "Fix #bugnum: " (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) +- [ ] Any changes to [scripts/assets](https://github.com/oppia/oppia-android/tree/develop/scripts/assets) files have their rationale included in the PR explanation. - [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). -- [ ] The PR does not contain any unnecessary auto-generated code or unnecessary files from Android Studio. -- [ ] The PR is made from a branch that's **not** called "develop". -- [ ] The PR is made from a branch that is up-to-date with "develop". -- [ ] The PR's branch is based on "develop" and **not** on any other branch. -- [ ] The PR is **assigned** to an appropriate reviewer in **Assignees** as well as **Reviewers** section. +- [ ] The PR does not contain any unnecessary code changes from Android Studio. +- [ ] The PR is made from a branch that's **not** called "develop" and is up-to-date with "develop". +- [ ] The PR is **assigned** to the appropriate reviewers ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#clarification-regarding-assignees-and-reviewers-section)). + +## 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: +1. Once you PR is created, go to `Files changed` section available on top of your pull request. For example: + + +2. Now 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. ## Tips for getting your PR merged after submission From 60e143ebd446f3b1c046c9b8de6b6ed8a78a109f Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 24 Aug 2021 13:51:25 +0530 Subject: [PATCH 211/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 345217aa46f..1114cd86b18 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -21,7 +21,7 @@ Note: This checklist should be embedded in your every PR explanation with approp - [ ] The PR title and explanation each start with "Fix #bugnum: " (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) - [ ] Any changes to [scripts/assets](https://github.com/oppia/oppia-android/tree/develop/scripts/assets) files have their rationale included in the PR explanation. - [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). -- [ ] The PR does not contain any unnecessary code changes from Android Studio. +- [ ] The PR does not contain any unnecessary code changes from Android Studio ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#undo-unnecessary-changes)). - [ ] The PR is made from a branch that's **not** called "develop" and is up-to-date with "develop". - [ ] The PR is **assigned** to the appropriate reviewers ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#clarification-regarding-assignees-and-reviewers-section)). From ef57bd1b72b47bd3ad049ece463f200c51627d6a Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 1 Sep 2021 12:13:02 -0700 Subject: [PATCH 212/374] Clarify that Bazel 4.0.0 is currently required. --- Bazel-Setup-Instructions-for-Windows.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index da66f68184b..18e384b1165 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -111,7 +111,11 @@ When the commands above are finished running, the Android SDK should now be inst ### 4. Installing Bazel -Follow [these instructions](https://docs.bazel.build/versions/main/install-ubuntu.html#install-on-ubuntu) to install Bazel using ``apt`` rather than Bazelisk (Bazelisk might work, but it's untested with these instructions). +Follow [these instructions](https://docs.bazel.build/versions/main/install-ubuntu.html#install-on-ubuntu) to install Bazel using ``apt`` rather than Bazelisk (Bazelisk might work, but it's untested with these instructions). Note that Oppia requires Bazel 4.0.0, so you'll likely need to run the following command: + +```sh +sudo apt install bazel-4.0.0 +``` ### 5. Preparing build environment for Oppia Android From 69b09f33d87bfa8ee9f0121e1e8d7a64265d4711 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 30 Sep 2021 17:16:07 -0700 Subject: [PATCH 213/374] Add missing escape quote. --- Bazel-Setup-Instructions-for-Windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index 18e384b1165..d0a1e0c3ab8 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -92,7 +92,7 @@ At this point, we can define the ``ANDROID_HOME`` variable to point to the new S ```sh echo "export ANDROID_HOME=\$HOME/Android/Sdk" >> ~/.bashrc -echo "export PATH=\$ANDROID_HOME/cmdline-tools/tools/bin/:\$PATH >> ~/.bashrc +echo "export PATH=\$ANDROID_HOME/cmdline-tools/tools/bin/:\$PATH" >> ~/.bashrc source ~/.bashrc ``` From 7c00256c1ae4e57bec6e1ab5a50419ede84c2e68 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Tue, 5 Oct 2021 00:16:53 +0530 Subject: [PATCH 214/374] Updated Home (markdown) --- Home.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Home.md b/Home.md index 9d3c6065eee..670e6eb565c 100644 --- a/Home.md +++ b/Home.md @@ -52,6 +52,27 @@ If you are on Windows, please set up the environment path correctly for `Java`. - 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 is also set up. - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) +## Troubleshooting Installation +**General** + +Here are some general troubleshooting tips for oppia-android. The platform specific are Linux, Windows and Mac OS. +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. + +**Can’t find the particular issue?** + +If the error you get is not in the troubleshooting page, create an issue providing us all the necessary information. + + ## Instructions for making a code change **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). From 28b99bd14beff04b6d9f808e940645771919ea35 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Tue, 5 Oct 2021 00:24:40 +0530 Subject: [PATCH 215/374] Created Interpreting CI Results (markdown) --- Interpreting-CI-Results.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 Interpreting-CI-Results.md diff --git a/Interpreting-CI-Results.md b/Interpreting-CI-Results.md new file mode 100644 index 00000000000..b0135d27293 --- /dev/null +++ b/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. + +![image](https://user-images.githubusercontent.com/54740946/135907913-3e542b99-ff10-420e-819c-dac818033679.png) + + +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 + +![image](https://user-images.githubusercontent.com/54740946/135908001-eb46d5f1-2c1c-43ec-be62-8fab58bb00ec.png) + + +Navigate to logs or search the keyword ‘error’ to find the error message to understand what might have caused the failure in the checks. From 3701b88a7e1b182e2ea3f5af5952fb5897f763ce Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Tue, 5 Oct 2021 00:29:57 +0530 Subject: [PATCH 216/374] Updated Home (markdown) --- Home.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Home.md b/Home.md index 670e6eb565c..0e395bd21cd 100644 --- a/Home.md +++ b/Home.md @@ -178,6 +178,28 @@ The following instructions describe how to make a one-off code change using a fe By using this command git will detect the file as a renamed file. +## Finding something to do +**Starter projects for new contributors** + +Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. After that, we’d strongly recommend tackling some part of one of the following starter issues. + +**UI** + + - [RTL Exempted files](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+RTL+Exempted+file) + - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) + +**Bazel** + + - [Create bazel subpackage](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22Bazel+Stage+2%22+label%3A%22good+first+issue%22) + +**Accessibility** + + - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) + +**Testing** + + - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) + ## Communication channels ### Mailing lists From ebb6cb54eab6ce6b7f479cddae80fc0106516e78 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Tue, 5 Oct 2021 00:37:32 +0530 Subject: [PATCH 217/374] Created Developing skills (markdown) --- Developing-skills.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 Developing-skills.md diff --git a/Developing-skills.md b/Developing-skills.md new file mode 100644 index 00000000000..562b07e321e --- /dev/null +++ b/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! From 7408a3243c951a59b941e2f81e07d725ee06567a Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 12 Oct 2021 18:29:48 +0530 Subject: [PATCH 218/374] Updated image 1 to depict a fork. --- Android-Studio-UI-based-Github-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index 47dc361a46b..bb6bab7dae6 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -2,7 +2,7 @@ Navigate to your fork, e.g. ``https://github.com//oppia-android``. Click on **Clone or download** and copy the link (the URL will look different since you should be using your fork, **not** https://github.com/oppia/oppia-android). -1 +1 Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git** From fadc1beb60081619f012d55baac571c4f1f892d1 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 12 Oct 2021 18:42:36 +0530 Subject: [PATCH 219/374] addition of image for describing how t0 pull changes. --- Android-Studio-UI-based-Github-workflow.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index bb6bab7dae6..abd7d9e65e2 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -88,7 +88,8 @@ Refer [comment](https://github.com/oppia/oppia-android/pull/2101#issuecomment-75 Once you push your new branch to "develop" you are ready to merge new changes from remote(upstream). Make sure the new branch's base branch is "develop" and the new branch is up-to-date with changes in "develop". -17 +17a +17b If you are not getting the below options of selecting upstream.Please log in your GitHub account. From 32d0c6cec7e30705b6767b93fc43c828ac15de55 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 12 Oct 2021 19:30:20 +0530 Subject: [PATCH 220/374] Stacking Pull Requests --- Android-Studio-UI-based-Github-workflow.md | 35 ++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md index abd7d9e65e2..3c8da47a16b 100644 --- a/Android-Studio-UI-based-Github-workflow.md +++ b/Android-Studio-UI-based-Github-workflow.md @@ -140,3 +140,38 @@ Now you will find the merged file changes locally in your Android Studio code. 31 +# Stacking Pull Requests + +Stacked PRs, also know as dependent, incremental, or chained PRs, are pull requests that branch off from other pull requests. In `git` terms, they are feature branches that are checked out from other feature branches to build small and coherent units to represent changes. + +## When and why should you use stacked PRs? +* To split large PRs +* To share a piece of code between multiple feature branches +* To make it easy for two people to work on the same feature + +Stacked PRs are useful when wanting to split large pull requests. The other situation where stacked PRs really shine is when you want to use a particular change in two or more branches. + +## How to stack PRs? +* Check-out a new branch from `develop`. Let's call this `BranchA`. +* Check-out a new branch from `BranchA`. Let's call this `BranchB`. + +Here, `BranchA` depends on `develop` but `BranchB` is stacked on top of `BranchA`. So whenever you create a pull request: + +* for BranchA: `source branch = BranchA, base branch = develop` +* for BranchB (if BranchA hasn't been merged into develop): `source branch = BranchB, base branch = BranchA ` +* for BranchB (if BranchA has been merged into develop): `source branch = BranchB, base branch = develop ` + +## Steps to merge stacked PRs +- Merge `BranchA` PR into `develop`. +- Locally, check out `develop` +- Pull latest `develop` (should include your PR's changes) +- Check out BranchA +- Merge develop into BranchA +- Check out BranchB +- Merge BranchA into BranchB +- Push BranchB. You're now based off of develop without conflicts. +- Change BranchB PR to be based on develop on GitHub. + +This results in the history being replicated, but doesn't result in loss of commits. For what it's worth, GitHub also sometimes automatically will change the derive PR's base branch when the base branch PR gets merged. + + From 02c6e21d9e121c41ad4c214611c792c1ea2573b6 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 12 Oct 2021 19:52:56 +0530 Subject: [PATCH 221/374] Updated Firebase Console Guide (markdown) --- Firebase-Console-Guide.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index 2821e1c2d97..3501eca953a 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -1,4 +1,5 @@ This document is made as a guide for viewing and customising the Firebase project(s) of Oppia-Android. It is recommended to fully read this doc before making any changes to the Firebase project. If you only want to view the Firebase console then this doc can help you in viewing exactly the thing that you want to see. It must also be noted that appropriate permissions are required for viewing/editing anything in the console. For permissions, please contact oppia-android-dev@googlegroups.com. + ## Table of Contents * [Viewing the Console](#viewing-the-console) * [Crashlytics](#crashlytics) @@ -10,10 +11,12 @@ This document is made as a guide for viewing and customising the Firebase projec * [Your own Firebase Project](#your-own-firebase-project) * [Setting it up](#setting-it-up) * [App registration](#app-registration) + ## Viewing the Console * Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account (if you haven't) -> Select Oppia Android Dev Project. * You will be welcomed by the following screen : > + ### Crashlytics * Scroll down the left nav bar and select Crashlytics. You will see the following dashboard : > @@ -25,6 +28,7 @@ This document is made as a guide for viewing and customising the Firebase projec * 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 : > @@ -40,15 +44,18 @@ This document is made as a guide for viewing and customising the Firebase projec * 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 package_name` in your command line while the app runs on your emulator/device. +* 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. > @@ -62,6 +69,7 @@ This document is made as a guide for viewing and customising the Firebase projec 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'. @@ -69,17 +77,21 @@ This document is made as a guide for viewing and customising the Firebase projec > * 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 : > From 1cead2d667827e38a95172ec792af3e386ce65d4 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 12 Oct 2021 20:09:38 +0530 Subject: [PATCH 222/374] View events in the Android Studio debug log --- Firebase-Console-Guide.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/Firebase-Console-Guide.md b/Firebase-Console-Guide.md index 3501eca953a..e25da5475c1 100644 --- a/Firebase-Console-Guide.md +++ b/Firebase-Console-Guide.md @@ -11,6 +11,7 @@ This document is made as a guide for viewing and customising the Firebase projec * [Your own Firebase Project](#your-own-firebase-project) * [Setting it up](#setting-it-up) * [App registration](#app-registration) +* [View events in the Android Studio debug log](#view-events-in-the-android-studio-debug-log) ## Viewing the Console * Go to the [Firebase Console](https://console.firebase.google.com) -> Log in to your gmail account (if you haven't) -> Select Oppia Android Dev Project. @@ -99,4 +100,15 @@ This document is made as a guide for viewing and customising the Firebase projec * 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. \ No newline at end of file +* 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 From 94ba88ab07bf3761baeae4740122882e105e084c Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 14 Oct 2021 22:57:21 -0700 Subject: [PATCH 223/374] Updated Home (markdown) --- Home.md | 96 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 35 deletions(-) diff --git a/Home.md b/Home.md index 0e395bd21cd..cf243a8add2 100644 --- a/Home.md +++ b/Home.md @@ -1,61 +1,77 @@ Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! ## Onboarding instructions -We're still working on setting up the basics of the Android project, but we are starting to welcome new contributors who'd like to help out. For now, if you're interested in contributing, please follow the following steps: +If you'd like to help out with the Android project, please follow the following steps to get started: 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). 2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** -3. Check out the oppia-android codebase to become familiar with the project! -4. Check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally, so that you can connect to a local instance of the web app when developing locally. -5. Read the Oppia Android coding style guide: https://github.com/oppia/oppia-android/wiki/Coding-style-guide +3. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). +4. 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). +5. In Android Studio, open Tools > SDK Manager. + - In the "SDK Platforms" tab (which is the default), select `API Level 28`. + - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). + Then, click "Apply" to download and install these two SDKs/Tools. -## Prerequisites -1. Good internet connectivity is required as this project uses third party libraries which will be needed to build the app. -2. Download/Install latest [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). +**Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. -## Installation +## Install oppia-android -Please follow these steps for initial setup of the project on your local machine. +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. -2. Navigate to `opensource/oppia-android/` and run the project in Android Studio. or follow [Android Studio UI based Github workflow](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow) + **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. -Note: Please keep the project name as it is `oppia-android`, changing the project folder name might lead to failure. +2. Run the setup script, which adds some development tools for Oppia Android (ktlint, checkstyle, etc.): -3. Set up `Java` with the latest version. Install from [here](https://www.java.com/en/download/).
-If you are on Windows, please set up the environment path correctly for `Java`. + - For Mac or Linux + 1. Open a terminal and navigate to `opensource/oppia-android/`. + 2. Run the script `bash scripts/setup.sh`. -4. Run the script - - For Mac or Linux - 1. Open terminal - 2. Move to `opensource/oppia-android/` - 3. Run a 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. For the Terminal x86 right-click and click Get info and check the option Open using Rosetta - 4. Move to `opensource/oppia-android/` - 5. Now run `bash scripts/setup.sh` in Terminal x86 and all the required files will be generated as they should + 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. Move to `opensource/oppia-android/` - 4. Run a 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 download this file, you can simply right-click on the `Raw` button and click on `Save Link as`. - 6. Copy it to directory where Git is installed (usually C:/Program Files/Git/). + 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 > AVD Manager, click "Create Virtual Device...". Then: + - Select a preferred device definition. In general, any device is fine, but you can use Pixel 3a as a default (if you're developing for phones) or Nexus 7 (if you're developing for tablets). After selecting a device, click "Next" at the bottom right to continue. + - Select a system image (in general, API Level 28, unless you're an M1 Mac user, in which case use API Level 29). Then click "Next". + - 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. + + +## Installing the Oppia web app + +If you need to connect to a local version of the Oppia web application, check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally. This will allow you to connect to a local instance of the web app when developing locally. + +For now, you generally won't need to do this, until the Android app supports on-the-fly lesson downloading (which we're currently working on). - - If you find any error related to `cURL`, please set up cURL at your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- - 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 is also set up. - - If you find any error while pushing the code, related to kotlin or Java/Checkstyle, please check [here](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures) ## Troubleshooting Installation -**General** -Here are some general troubleshooting tips for oppia-android. The platform specific are Linux, Windows and Mac OS. +Here are some general troubleshooting tips for oppia-android. The specific platforms are Linux, Windows and Mac OS. + 1. No matching toolchains (sdk_toolchain_type) ``` ERROR: While resolving toolchains for target //:oppia: no matching toolchains found for types @@ -68,19 +84,29 @@ Here are some general troubleshooting tips for oppia-android. The platform speci ``` [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 find any error related to `cURL`, please set up cURL on your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
+ +3. 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. + +4. 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). + **Can’t find the particular issue?** -If the error you get is not in the troubleshooting page, create an issue providing us all the necessary information. +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 **@FareesHussain**. ## Instructions for making a code change +**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: From 995319b66a7ad150181abcbb3213a7fb543b0334 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 14 Oct 2021 22:59:03 -0700 Subject: [PATCH 224/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 8ec39326b71..6089249568c 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -24,7 +24,9 @@ override directory must be an absolute path ``` Try to delete the `.bazelrc` file to solve the above. error. -After the installation completes you can build the app using Bazel. Move your command line head to the `~/opensource/oppia-android` and run the below bazel command: +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: #### Building the app From 960ddc80a7d27fd0167dbb93aa16a27d67e1d260 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 15 Oct 2021 12:35:58 -0700 Subject: [PATCH 225/374] Clarify installation instructions slightly around installing JDK 8 & Bazel 4.0.0. --- Oppia-Bazel-Setup-Instructions.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 6089249568c..fc3a5b698a6 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -9,9 +9,14 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. Instructions for setting up Bazel on Unix-based machines: -1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). +1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). -1. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
+1. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include sections on installing OpenJDK on different platforms. For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: +```sh +sudo apt install openjdk-8-jdk +``` + +3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
- macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` From f38ef524372f521d2246f984ac6132a86885ffba Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Fri, 15 Oct 2021 18:44:19 -0700 Subject: [PATCH 226/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index fc3a5b698a6..1cf1542413d 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -15,6 +15,7 @@ Instructions for setting up Bazel on Unix-based machines: ```sh sudo apt install openjdk-8-jdk ``` + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out, showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From 50d93878efb9a9b79ed8cd22d821234cace2fdb4 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Fri, 15 Oct 2021 18:44:35 -0700 Subject: [PATCH 227/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 1cf1542413d..46f61a3749a 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -15,7 +15,7 @@ Instructions for setting up Bazel on Unix-based machines: ```sh sudo apt install openjdk-8-jdk ``` - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out, showing "openjdk version "1.8.0_292". + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From ad82cceb12d77aadfb4cfd7797ec4f46cd43863d Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Fri, 15 Oct 2021 18:44:50 -0700 Subject: [PATCH 228/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 46f61a3749a..e9c6e249190 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -12,10 +12,10 @@ Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). 1. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include sections on installing OpenJDK on different platforms. For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: -```sh -sudo apt install openjdk-8-jdk -``` - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". + ```sh + sudo apt install openjdk-8-jdk + ``` + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From b84959fc8f2d7d956a509b731f704153bd09222b Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 17 Oct 2021 15:11:52 +0530 Subject: [PATCH 229/374] Created Troubleshooting Installation (markdown) --- Troubleshooting-Installation.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 Troubleshooting-Installation.md diff --git a/Troubleshooting-Installation.md b/Troubleshooting-Installation.md new file mode 100644 index 00000000000..ff2bf4e9ccc --- /dev/null +++ b/Troubleshooting-Installation.md @@ -0,0 +1,23 @@ +Here are some general troubleshooting tips for oppia-android. The specific platforms are Linux, Windows and Mac OS. + +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 find any error related to `cURL`, please set up cURL on your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
+ +3. 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. + +4. 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). + +**Can’t find the 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 **@FareesHussain**. From a8333ca268fd626eb8784f42ef4fef1f6b1b793b Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 17 Oct 2021 15:13:38 +0530 Subject: [PATCH 230/374] Created Instructions for making a code change (markdown) --- Instructions-for-making-a-code-change.md | 79 ++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 Instructions-for-making-a-code-change.md diff --git a/Instructions-for-making-a-code-change.md b/Instructions-for-making-a-code-change.md new file mode 100644 index 00000000000..ca91ee920ff --- /dev/null +++ b/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! From 853fb39ec23c5842809f2ded3e43c0501b237392 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 17 Oct 2021 15:14:19 +0530 Subject: [PATCH 231/374] Updated Home (markdown) --- Home.md | 109 -------------------------------------------------------- 1 file changed, 109 deletions(-) diff --git a/Home.md b/Home.md index cf243a8add2..941d5df80a0 100644 --- a/Home.md +++ b/Home.md @@ -68,115 +68,6 @@ If you need to connect to a local version of the Oppia web application, check ou For now, you generally won't need to do this, until the Android app supports on-the-fly lesson downloading (which we're currently working on). -## Troubleshooting Installation - -Here are some general troubleshooting tips for oppia-android. The specific platforms are Linux, Windows and Mac OS. - -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 find any error related to `cURL`, please set up cURL on your machine. For Linux, you can use `sudo apt install curl`. No need to set up `cURL` for Windows as you are using git bash command line.
- -3. 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. - -4. 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). - -**Can’t find the 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 **@FareesHussain**. - - -## Instructions for making a code change - -**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! - ### Notes * Our central development branch is `develop`, which should be clean and ready for release at any time. All changes should be done in feature branches based off of `develop`. From 259ebda311f53d1bd419e62465f540c0fe145893 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 17 Oct 2021 15:33:57 +0530 Subject: [PATCH 232/374] Created _Sidebar (markdown) --- _Sidebar.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 _Sidebar.md diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 00000000000..1cfe7a97043 --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,41 @@ +**Core documentation** + * [Oppia's mission](https://github.com/oppia/oppia/wiki/Oppia's-Mission) + * [Code of Conduct](https://github.com/oppia/oppia/blob/develop/.github/CODE_OF_CONDUCT.md) + * **[[Get involved!|Home]]** + * [Coders](https://github.com/oppia/oppia-android/wiki#onboarding-instructions) + +--- +**Developing Oppia** + * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki]] + * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] + * 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]] + * [[Fork and Clone Oppia Android|https://github.com/oppia/oppia-android/wiki/Fork-and-Clone-Oppia-Android]] + * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] + * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] + * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] + * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] + * 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 Skils|https://github.com/oppia/oppia-android/wiki/Developing-skills]] + * [[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]] + * [[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]] +--- +**Developer Reference** + * [[Background Concurrent processing in Android DataProviders & Coroutines|https://github.com/oppia/oppia-android/wiki/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines]] + * [[Buf Guide|https://github.com/oppia/oppia-android/wiki/Buf-Guide]] + * [[Coding style guide|https://github.com/oppia/oppia-android/wiki/Coding-style-guide]] + * [[Firebase Console Guide|https://github.com/oppia/oppia-android/wiki/Firebase-Console-Guide]] + * [[Gradle Bazel Migration Best Practices and FAQ|https://github.com/oppia/oppia-android/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ]] + * [[Ktlint Guide|https://github.com/oppia/oppia-android/wiki/Ktlint-Guide]] + * [[Platform Parameters & Feature Flags|https://github.com/oppia/oppia-android/wiki/Platform-Parameters-&-Feature-Flags]] + * [[Revert & regression policy|https://github.com/oppia/oppia-android/wiki/Revert-&-regression-policy]] + * [[SLoP 2020|https://github.com/oppia/oppia-android/wiki/SLoP-2020]] + * [[Static Analysis Checks|https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks]] + * [[Updating Maven Dependencies|https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies]] + * [[XML code style format|https://github.com/oppia/oppia-android/wiki/XML-code-style-format]] \ No newline at end of file From cbd078e1a50c4be65fe9e2b9d24710187fa4f705 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sun, 17 Oct 2021 10:27:26 -0700 Subject: [PATCH 233/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 1cfe7a97043..d2de95a2715 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,11 +7,11 @@ --- **Developing Oppia** * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki]] + * [[Fork and Clone Oppia Android|https://github.com/oppia/oppia-android/wiki/Fork-and-Clone-Oppia-Android]] * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] * 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]] - * [[Fork and Clone Oppia Android|https://github.com/oppia/oppia-android/wiki/Fork-and-Clone-Oppia-Android]] * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] From 91afcb9484fb0a48e47a87483efd1b937255a17c Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sun, 17 Oct 2021 10:28:29 -0700 Subject: [PATCH 234/374] Updated _Sidebar (markdown) --- _Sidebar.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_Sidebar.md b/_Sidebar.md index d2de95a2715..627b9a206a6 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,14 +7,13 @@ --- **Developing Oppia** * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki]] - * [[Fork and Clone Oppia Android|https://github.com/oppia/oppia-android/wiki/Fork-and-Clone-Oppia-Android]] + * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] * 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]] * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] - * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] * Testing * [[Oppia Android Testing|https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing]] From b87b0d4175501710203150bfc1f8375f19ef8ced Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sun, 17 Oct 2021 10:29:16 -0700 Subject: [PATCH 235/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 627b9a206a6..cd7d450fb44 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -12,8 +12,8 @@ * 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]] - * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] + * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] * Testing * [[Oppia Android Testing|https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing]] From 0cd7cf8f6aa29a4a5fdc01dd01da5b9633780743 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sun, 17 Oct 2021 10:32:29 -0700 Subject: [PATCH 236/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index cd7d450fb44..2fabc679c50 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -18,7 +18,7 @@ * 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 Skils|https://github.com/oppia/oppia-android/wiki/Developing-skills]] + * [[Developing Skills|https://github.com/oppia/oppia-android/wiki/Developing-skills]] * [[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]] * [[Frequent Errors and Solutions|https://github.com/oppia/oppia-android/wiki/Frequent-Errors-and-Solutions]] From 98c97e97b3e21e8ebf9970236762d364f5db3c26 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 19 Oct 2021 23:16:04 -0700 Subject: [PATCH 237/374] Updated _Sidebar (markdown) --- _Sidebar.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/_Sidebar.md b/_Sidebar.md index 2fabc679c50..1b039e45c34 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -8,33 +8,38 @@ **Developing Oppia** * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] - * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] * 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]] - * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] - * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] + * Key Workflows + * [[Guidance on submitting a PR|https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR]] + * [[Interpreting CI Results|https://github.com/oppia/oppia-android/wiki/Interpreting-CI-Results]] + * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] + * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] + * [[Creating a screenshot|https://github.com/oppia/oppia-android/wiki/Creating-a-screenshot]] * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] * 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]] - * [[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]] * [[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]] --- **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]] + * [[XML code style format|https://github.com/oppia/oppia-android/wiki/XML-code-style-format]] + * [[Static Analysis Checks|https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks]] * [[Background Concurrent processing in Android DataProviders & Coroutines|https://github.com/oppia/oppia-android/wiki/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines]] * [[Buf Guide|https://github.com/oppia/oppia-android/wiki/Buf-Guide]] - * [[Coding style guide|https://github.com/oppia/oppia-android/wiki/Coding-style-guide]] * [[Firebase Console Guide|https://github.com/oppia/oppia-android/wiki/Firebase-Console-Guide]] - * [[Gradle Bazel Migration Best Practices and FAQ|https://github.com/oppia/oppia-android/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ]] - * [[Ktlint Guide|https://github.com/oppia/oppia-android/wiki/Ktlint-Guide]] * [[Platform Parameters & Feature Flags|https://github.com/oppia/oppia-android/wiki/Platform-Parameters-&-Feature-Flags]] * [[Revert & regression policy|https://github.com/oppia/oppia-android/wiki/Revert-&-regression-policy]] - * [[SLoP 2020|https://github.com/oppia/oppia-android/wiki/SLoP-2020]] - * [[Static Analysis Checks|https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks]] - * [[Updating Maven Dependencies|https://github.com/oppia/oppia-android/wiki/Updating-Maven-Dependencies]] - * [[XML code style format|https://github.com/oppia/oppia-android/wiki/XML-code-style-format]] \ No newline at end of file + * 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]] + * 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 From fadc55ac1afacae2ae3577454939fcba0abf9dc6 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Wed, 3 Nov 2021 16:49:52 +0530 Subject: [PATCH 238/374] Updated Home (markdown) --- Home.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 941d5df80a0..f316740eda7 100644 --- a/Home.md +++ b/Home.md @@ -6,8 +6,10 @@ If you'd like to help out with the Android project, please follow the following 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). 2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** 3. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). -4. Install **Java 8** using the links from [the Java website](https://www.java.com/en/download/). +4. 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. 5. In Android Studio, open Tools > SDK Manager. - In the "SDK Platforms" tab (which is the default), select `API Level 28`. - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). From 7320e5e2d2369cc928b297f56b66879651aa048e Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Wed, 3 Nov 2021 16:50:59 +0530 Subject: [PATCH 239/374] Created Oppia's Mission (markdown) --- Oppia's-Mission.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 Oppia's-Mission.md diff --git a/Oppia's-Mission.md b/Oppia's-Mission.md new file mode 100644 index 00000000000..dd6959ef733 --- /dev/null +++ b/Oppia's-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. + From f8023e153de31b392cabcbc4042d99d0f0cd6ed8 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Wed, 3 Nov 2021 16:51:28 +0530 Subject: [PATCH 240/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 1b039e45c34..685b9503361 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,5 +1,5 @@ **Core documentation** - * [Oppia's mission](https://github.com/oppia/oppia/wiki/Oppia's-Mission) + * [Oppia's mission](https://github.com/oppia/oppia-android/wiki/Oppia's-Mission) * [Code of Conduct](https://github.com/oppia/oppia/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|Home]]** * [Coders](https://github.com/oppia/oppia-android/wiki#onboarding-instructions) From d8bb0a65c218e58f7dd16a81271106a10c68c178 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Wed, 3 Nov 2021 16:52:00 +0530 Subject: [PATCH 241/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 685b9503361..ebd0b1282c8 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,6 +1,6 @@ **Core documentation** * [Oppia's mission](https://github.com/oppia/oppia-android/wiki/Oppia's-Mission) - * [Code of Conduct](https://github.com/oppia/oppia/blob/develop/.github/CODE_OF_CONDUCT.md) + * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|Home]]** * [Coders](https://github.com/oppia/oppia-android/wiki#onboarding-instructions) From 6c020d861eb6f59039b8db29016f1a17c7fb2377 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Wed, 3 Nov 2021 17:09:14 +0530 Subject: [PATCH 242/374] Created Contributing to Oppia-android (markdown) --- Contributing-to-Oppia-android.md | 138 +++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 Contributing-to-Oppia-android.md diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md new file mode 100644 index 00000000000..c9a2523f887 --- /dev/null +++ b/Contributing-to-Oppia-android.md @@ -0,0 +1,138 @@ +_These instructions are for developers who'd like to contribute code to improve the Oppia platform. If you'd prefer to help out with other things, please see our [[general contribution guidelines|Home]]._ + +Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! +## Table of Contents + +* [Onboarding instructions](#onboarding-instructions) +* [Install oppia-android](#install-oppia-android) +* [Run the app from Android Studio](#run-the-app-from-android-studio) +* [Notes](#notes) +* [Developing skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) +* [Finding something to do](#finding-something-to-do) +* [Communication channels](#communication-channels) + + +## Onboarding instructions +If you'd like to help out with the Android project, please follow the following steps to get started: + +1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). +2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** +3. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). +4. 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. +5. In Android Studio, open Tools > SDK Manager. + - In the "SDK Platforms" tab (which is the default), select `API Level 28`. + - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). + + Then, click "Apply" to download and install these two SDKs/Tools. + +**Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. + +## 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 > AVD Manager, click "Create Virtual Device...". Then: + - Select a preferred device definition. In general, any device is fine, but you can use Pixel 3a as a default (if you're developing for phones) or Nexus 7 (if you're developing for tablets). After selecting a device, click "Next" at the bottom right to continue. + - Select a system image (in general, API Level 28, unless you're an M1 Mac user, in which case use API Level 29). Then click "Next". + - 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. + + +## Installing the Oppia web app + +If you need to connect to a local version of the Oppia web application, check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally. This will allow you to connect to a local instance of the web app when developing locally. + +For now, you generally won't need to do this, until the Android app supports on-the-fly lesson downloading (which we're currently working on). + + +### Notes + +* Our central development branch is `develop`, which should be clean and ready for release at any time. All changes should be done in feature branches based off of `develop`. + +* To find the author of a particular change in a file, run this command: + + ``` + git blame file-name + ``` + The output will show the latest commit SHA, author, date, and time of commit for each line. + + To confine the search of an author between particular lines in a file, you can use: + + ``` + git blame -L 40,60 file-name + ``` + The output will then show lines 40 to 60 of the particular file. + + For more `git blame` options, you can visit the [git blame documentation](https://git-scm.com/docs/git-blame). + +* If your PR includes changing the location of the file, if you simply move the file by cut and paste method, then the git will track it as a new file. So to prevent this, use: + ``` + git mv old_file_path new_file_path + ``` + By using this command git will detect the file as a renamed file. + + +## Finding something to do +**Starter projects for new contributors** + +Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. After that, we’d strongly recommend tackling some part of one of the following starter issues. + +**UI** + + - [RTL Exempted files](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+RTL+Exempted+file) + - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) + +**Bazel** + + - [Create bazel subpackage](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22Bazel+Stage+2%22+label%3A%22good+first+issue%22) + +**Accessibility** + + - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) + +**Testing** + + - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) + +## Communication channels + +### Mailing lists + +We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! From e1a92c9aef1581b2b9c7e0ad21d3600edb075420 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 9 Nov 2021 18:55:52 +0530 Subject: [PATCH 243/374] screenshots for in-built android studio options, instructions for xml formatting. --- Coding-style-guide.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Coding-style-guide.md b/Coding-style-guide.md index c64fdfbbc69..37773d4305e 100644 --- a/Coding-style-guide.md +++ b/Coding-style-guide.md @@ -18,6 +18,10 @@ Reformat all edited files automatically in android studio using the following co - 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`. + +Screenshot 2021-11-09 at 6 25 26 PM + NOTE: This does not guarantee 100% formatting of code as per guidelines but will be very helpful in indentation and extra spaces. ## Comments @@ -29,12 +33,22 @@ NOTE: This does not guarantee 100% formatting of code as per guidelines but will - 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; use e.g. a dimens.xml file instead. In general, avoid using hard-coded strings. Similar case for colors and strings +- 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. -- Order imports alphabetically. Remove unused imports. - 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`. + +Screenshot 2021-11-09 at 6 25 05 PM + ## Layout files - Each layout file should be named according to how they are used, where all layouts fall in the following buckets: From 8e893f9732fad3f0c182c6c95e9e9be91c7b79ae Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 9 Nov 2021 20:12:52 +0530 Subject: [PATCH 244/374] addition of screenshots. --- Creating-a-screenshot.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot.md index fad0a85619b..772808a500c 100644 --- a/Creating-a-screenshot.md +++ b/Creating-a-screenshot.md @@ -19,7 +19,13 @@ The default location for the screenshot, video and gif would be on Desktop. If you are running Oppia on a local Android device, you can take a screenshot using the Logcat window of Android Studio. * Go to Tools > Windows > Logcat. You will see the Logcat window open up at the bottom. * On the left hand side there is a column of icons, hover on the expand icon at the bottom and you will see a camera icon: . -* Click on that and Android studio will take a screenshot and open up a Screenshot Editor + +Screenshot 2021-11-09 at 7 54 36 PM + +* Click on that and Android studio will take a screenshot and open up a Screenshot Editor. + +Screenshot 2021-11-09 at 7 50 53 PM + * You can then save your image from the Screenshot Editor. For more details, see the [Android documentation](https://developer.android.com/studio/debug/am-screenshot) @@ -29,4 +35,4 @@ If you would like to take a screenshot but cannot use Android Studio, you can in * 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 +* You can now upload the image on to Github. \ No newline at end of file From 184a987d92c089b8f1340f6fab67911f77fcebd4 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 9 Nov 2021 20:23:59 +0530 Subject: [PATCH 245/374] updated instructions for taking screenshot using Android Studio on a local device --- Creating-a-screenshot.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Creating-a-screenshot.md b/Creating-a-screenshot.md index 772808a500c..abba5a08f7d 100644 --- a/Creating-a-screenshot.md +++ b/Creating-a-screenshot.md @@ -26,7 +26,13 @@ If you are running Oppia on a local Android device, you can take a screenshot us Screenshot 2021-11-09 at 7 50 53 PM -* You can then save your image from the 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) From 95fb23fa902874db2c7811e82f2244e2cf20b221 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 14 Nov 2021 17:17:37 +0530 Subject: [PATCH 246/374] Updated Home (markdown) --- Home.md | 127 +++----------------------------------------------------- 1 file changed, 6 insertions(+), 121 deletions(-) diff --git a/Home.md b/Home.md index f316740eda7..af50a4d3911 100644 --- a/Home.md +++ b/Home.md @@ -1,126 +1,11 @@ -Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! +Thanks for your interest in contributing to the Oppia project, and making it easier for students to learn online in an effective and enjoyable way! -## Onboarding instructions -If you'd like to help out with the Android project, please follow the following steps to get started: +There are lots of 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/). Don't worry if you're new to "open source", or if you're 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 around the world to learn things better, and that you're responsible and reliable. -1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). -2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** -3. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). -4. 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. -5. In Android Studio, open Tools > SDK Manager. - - In the "SDK Platforms" tab (which is the default), select `API Level 28`. - - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). +To make it easier to get started, we've catalogued some of the different ways to help out. Please feel free to take a look through them, and see if any interest you: - Then, click "Apply" to download and install these two SDKs/Tools. + * [Coders](https://github.com/oppia/oppia-android/wiki/Contributing-code-to-Oppia-android) -**Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. +If you are interested in working on Oppia's web repository, you should also take a look at the [oppia/oppia repository](https://github.com/oppia/oppia). -## 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 > AVD Manager, click "Create Virtual Device...". Then: - - Select a preferred device definition. In general, any device is fine, but you can use Pixel 3a as a default (if you're developing for phones) or Nexus 7 (if you're developing for tablets). After selecting a device, click "Next" at the bottom right to continue. - - Select a system image (in general, API Level 28, unless you're an M1 Mac user, in which case use API Level 29). Then click "Next". - - 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. - - -## Installing the Oppia web app - -If you need to connect to a local version of the Oppia web application, check out a copy of the [Oppia web app repository](https://github.com/oppia/oppia) and get it running locally. This will allow you to connect to a local instance of the web app when developing locally. - -For now, you generally won't need to do this, until the Android app supports on-the-fly lesson downloading (which we're currently working on). - - -### Notes - -* Our central development branch is `develop`, which should be clean and ready for release at any time. All changes should be done in feature branches based off of `develop`. - -* To find the author of a particular change in a file, run this command: - - ``` - git blame file-name - ``` - The output will show the latest commit SHA, author, date, and time of commit for each line. - - To confine the search of an author between particular lines in a file, you can use: - - ``` - git blame -L 40,60 file-name - ``` - The output will then show lines 40 to 60 of the particular file. - - For more `git blame` options, you can visit the [git blame documentation](https://git-scm.com/docs/git-blame). - -* If your PR includes changing the location of the file, if you simply move the file by cut and paste method, then the git will track it as a new file. So to prevent this, use: - ``` - git mv old_file_path new_file_path - ``` - By using this command git will detect the file as a renamed file. - - -## Finding something to do -**Starter projects for new contributors** - -Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. After that, we’d strongly recommend tackling some part of one of the following starter issues. - -**UI** - - - [RTL Exempted files](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+RTL+Exempted+file) - - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - -**Bazel** - - - [Create bazel subpackage](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22Bazel+Stage+2%22+label%3A%22good+first+issue%22) - -**Accessibility** - - - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) - -**Testing** - - - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) - -## Communication channels - -### Mailing lists - -We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! +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! From b31ae28d7669e1c98e811205a44d0889bc0e5706 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 14 Nov 2021 17:18:23 +0530 Subject: [PATCH 247/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index af50a4d3911..7cceb41585b 100644 --- a/Home.md +++ b/Home.md @@ -4,7 +4,7 @@ There are lots of ways to help out and become an Oppia contributor, from joining To make it easier to get started, we've catalogued some of the 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-code-to-Oppia-android) + * [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 take a look at the [oppia/oppia repository](https://github.com/oppia/oppia). From 9887af0ed0c051ea4b80135bda0f35e560228f18 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Tue, 23 Nov 2021 17:37:57 +0530 Subject: [PATCH 248/374] Updated Android Studio UI based Github workflow (markdown) --- Android-Studio-UI-based-Github-workflow.md | 177 ------------------ Making-a-code-change.md | 206 +++++++++++++++++++++ 2 files changed, 206 insertions(+), 177 deletions(-) delete mode 100644 Android-Studio-UI-based-Github-workflow.md create mode 100644 Making-a-code-change.md diff --git a/Android-Studio-UI-based-Github-workflow.md b/Android-Studio-UI-based-Github-workflow.md deleted file mode 100644 index 3c8da47a16b..00000000000 --- a/Android-Studio-UI-based-Github-workflow.md +++ /dev/null @@ -1,177 +0,0 @@ -# Clone Oppia-Android using Android Studio -Navigate to your fork, e.g. ``https://github.com//oppia-android``. -Click on **Clone or download** and copy the link (the URL will look different since you should be using your fork, **not** https://github.com/oppia/oppia-android). - -1 - -Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git** - - -2 -Log in GitHub with your credentials. - -Paste the **URL** and click on **Clone** button. -Wait for a few minutes until Gradle build completes. - -4 - -# Create New Branch - -Now the local copy of Oppia-Android is ready on your Android Studio -Right side bottom of your android studio screen you will find a **develop** branch. -Click on **develop** > **New Branch** > _Enter your new branch name_ > **OK** - -10 -12 - - -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 - -11 - -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. - -5 - -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) - -8 - -Click on the green tick symbol to commit your files. - -9 - -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. - -13 - -## Push Changes - -Now we need to Push the code changes to local branch(origin) and upstream(remote) -Right click **app > Git > Repository > Push** - -15 - -Your new branch needs to be added to both origin and upstream remote. -Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. - -16 - -### How to Fix Push Failures? - -If you are using Command line to push and if you have any file formatting issues, the code will not get pushed and it will show you an error like this: - - - -

-If you are using Android Studio VCS>Git to push the code, you will get the failure result like this: - - - -While using Android Studio VCS>Git you will not be able to see much detail on what the failure is, but you can try running below commands to checks the failure details: - -If you are using Windows, please use [Git Bash Command Line](https://gitforwindows.org/) to run these scripts. - -If you have failure related to kotlin, then use this script to get a detailed failure result: -``` -scripts/ktlint_lint_check.sh -``` - -If you have failure related to checkstyle/java, then use this script to get a detailed failure result: -``` -scripts/checkstyle_lint_check.sh -``` -Refer [comment](https://github.com/oppia/oppia-android/pull/2101#issuecomment-759331732) here for error related to `google_checks.xml` config file. - -## Pull changes from Develop - -Once you push your new branch to "develop" you are ready to merge new changes from remote(upstream). Make sure the new branch's base branch is "develop" and the new branch is up-to-date with changes in "develop". - -17a -17b - -If you are not getting the below options of selecting upstream.Please log in your GitHub account. - -18 - -For log in Go to **Android Studio>Preference>Version Control >GitHub>Add Account** - -19 - -Fill all the credentials asked and log in. -Now Click **VCS>Git>Fetch** - -20 - -21 - -Now select the upstream to pull changes from "develop" -Select upstream in pull changes **dialog>select branch develop>Pull** -you will find all the new changes pulled from "develop" in version control update info. - -23 - -## Merge and resolve conflict -Follow these steps mentioned below (Note: The image is just for reference in this case) -* Select remote branch as **upstream** -* Select **develop** branch -25 - -* Select **your_branch_name** -* Click on **Pull** - -27 - -You will get the dialog of conflicted files. You need to resolve the conflicts by merging the file changes. -select **file>merge** - -28 - -Now the local changes, result and remote changes are displayed, should merge changes. - -29 - -Once all conflicts are resolved, "All changes have been processed" pop up appears. Now click on **Apply** - -30 - -Now you will find the merged file changes locally in your Android Studio code. - -31 - -# Stacking Pull Requests - -Stacked PRs, also know as dependent, incremental, or chained PRs, are pull requests that branch off from other pull requests. In `git` terms, they are feature branches that are checked out from other feature branches to build small and coherent units to represent changes. - -## When and why should you use stacked PRs? -* To split large PRs -* To share a piece of code between multiple feature branches -* To make it easy for two people to work on the same feature - -Stacked PRs are useful when wanting to split large pull requests. The other situation where stacked PRs really shine is when you want to use a particular change in two or more branches. - -## How to stack PRs? -* Check-out a new branch from `develop`. Let's call this `BranchA`. -* Check-out a new branch from `BranchA`. Let's call this `BranchB`. - -Here, `BranchA` depends on `develop` but `BranchB` is stacked on top of `BranchA`. So whenever you create a pull request: - -* for BranchA: `source branch = BranchA, base branch = develop` -* for BranchB (if BranchA hasn't been merged into develop): `source branch = BranchB, base branch = BranchA ` -* for BranchB (if BranchA has been merged into develop): `source branch = BranchB, base branch = develop ` - -## Steps to merge stacked PRs -- Merge `BranchA` PR into `develop`. -- Locally, check out `develop` -- Pull latest `develop` (should include your PR's changes) -- Check out BranchA -- Merge develop into BranchA -- Check out BranchB -- Merge BranchA into BranchB -- Push BranchB. You're now based off of develop without conflicts. -- Change BranchB PR to be based on develop on GitHub. - -This results in the history being replicated, but doesn't result in loss of commits. For what it's worth, GitHub also sometimes automatically will change the derive PR's base branch when the base branch PR gets merged. - - diff --git a/Making-a-code-change.md b/Making-a-code-change.md new file mode 100644 index 00000000000..bde10cac51f --- /dev/null +++ b/Making-a-code-change.md @@ -0,0 +1,206 @@ +**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial to pull requests.](https://www.atlassian.com/git/tutorials/making-a-pull-request) + +Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc.](https://github.com/oppia/oppia/wiki/Writing-design-docs) This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. + +To make code changes, please follow the following instructions carefully! Otherwise, your code review may be delayed. + - [Creating a pull request using the terminal](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-request-using-the-terminal) + - [Creating a pull request using android studio's UI based Github workflow](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-requeset-using-android-studios-ui-based-github-workflow) + +### Making a code change using the terminal + +**Step 1: Update your repository** +The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: +``` +git fetch upstream +git checkout develop +git merge upstream/develop +``` + +**Step 2: Create a new branch with a descriptive name** +Then create a new branch. In this example the branch is named `your-branch-name`. 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.` + +``` +git checkout -b your-branch-name +``` + +**Step 2: Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. + +You can change your most recent commit message using `git commit --amend`. + +*Note: It is difficult to change any commit messages other than your most recent one or messages on commits that have been pushed, so write your commit messages carefully!* + +Before making the commit, do some sanity-checks: +- Ensure that your code follows the style rules. +- Run robolectric and espresso tests to make sure you haven't broken anything! If you would to know more about testing on oppia-android check out [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) + + +Run git status to check that your changes are what you expect. To inspect the changes made to any particular file, use git diff your-file-name. + +Stage all your changes: +``` +git add . +``` +(`.` refers to your current directory) +To actually make the commit, run: + +``` +git commit -m "{{YOUR COMMIT MESSAGE HERE}}" +``` +*Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* + +**Step 3: Push changes to your GitHub fork** + +Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: + +Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. + +Use a tool like `git diff upstream/develop` 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 like debugging code. + +We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. + +When you're ready to push, run: +``` +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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. + +### Making a code change using android studio's UI based Github workflow + +**Step 1: Update your repository** +The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: + +On the bottom right side of your android studio screen you will find you branch name. + +Click on **branch_name** > **develop** > **Update** + +10 + +**Step 2: Create a new branch with a descriptive name** + +On the bottom right side of your android studio screen your branch. +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.` + +12 + + +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 + +11 + +**Step 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. + +5 + +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) + +8 + +Click on the green tick symbol to commit your files. + +9 + +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. + +13 + +**Step 4: Push changes to your GitHub fork** + +Now we need to Push the code changes to local branch(origin) and upstream(remote) +Right click **app > Git > Repository > Push** + +15 + +Your new branch needs to be added to both origin and upstream remote. +Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. + +16 + + +### Create a pull request + +Once your feature is ready, you can open a pull request (PR)! + +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. + + +### Important Points + +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. + +### Clarification regarding **Assignees** and **Reviewers** section. +1. **Reviewers**: This section will be filled automatically by Oppia-Bot. Once this section is filled out, it generally should not change throughout the timeline of the PR. +2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More 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. + + +### 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: +1. Once you PR is created, go to `Files changed` section available on top of your pull request. For example: + + +2. Now 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. + + + +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. + +### 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 in two ways: +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 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. + +2. 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 +git commit -a +git push origin new-branch-name + ``` + +Once you've finished addressing everything, and would like the reviewer to take another look, 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. + +### Tidy up! +After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository + +### Celebrate. :confetti_ball: +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. + + +### Tips for getting your PR merged after submission +1. Keep track of **Assignees** section and reply to comments in the PR itself. +2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. +3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. +4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). +5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. +6. 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. \ No newline at end of file From 4e27d4313514d560ebe62137e17144e358440e12 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Tue, 23 Nov 2021 18:46:53 +0530 Subject: [PATCH 249/374] Updated Fork and Clone Oppia Android (markdown) --- Fork-and-Clone-Oppia-Android.md | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/Fork-and-Clone-Oppia-Android.md b/Fork-and-Clone-Oppia-Android.md index 9ab01c91d30..dc0d9237e35 100644 --- a/Fork-and-Clone-Oppia-Android.md +++ b/Fork-and-Clone-Oppia-Android.md @@ -1,6 +1,13 @@ + _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)._ -## How to fork and clone the Oppia Android repository +## 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. @@ -16,6 +23,19 @@ _For a detailed explanation of the fork-and-clone process, please see this [GitH - `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) -## Updating your local repository +### Using android studio's UI based GitHub workflow +1. Navigate to your fork, e.g. ``https://github.com//oppia-android``. +Click on **Clone or download** and copy the link (the URL will look different since you should be using your fork, **not** https://github.com/oppia/oppia-android). + +1 + +2. Now, go to **Android Studio**>**File**>**New**>**Project from Version Control**>**Git** + +2 + +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. -If you need to update your local branch with the latest changes in the main Oppia Android repository on develop (e.g. in cases when your PR is showing extra commits that you didn't create), follow the steps listed [here](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). Note that Oppia Android uses 'develop' not 'main' for its mainline branch. \ No newline at end of file +4 \ No newline at end of file From d89634e498bcab40cc2de49e6d57e67550150b0b Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Tue, 23 Nov 2021 18:54:48 +0530 Subject: [PATCH 250/374] Updated _Sidebar (markdown) --- _Sidebar.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/_Sidebar.md b/_Sidebar.md index ebd0b1282c8..1800ba4fd1c 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -12,11 +12,9 @@ * [[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]] - * [[Interpreting CI Results|https://github.com/oppia/oppia-android/wiki/Interpreting-CI-Results]] - * [[Instructions for making a code change|https://github.com/oppia/oppia-android/wiki/Instructions-for-making-a-code-change]] - * [[Android Studio UI based Github workflow|https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow]] + * [[Making a code change|https://github.com/oppia/oppia-android/wiki/making-a-code-change]] * [[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]] * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] * Testing * [[Oppia Android Testing|https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing]] From 4aeaf0d921a2483e87863b114dc3ce816048302c Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Tue, 23 Nov 2021 21:33:01 +0530 Subject: [PATCH 251/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 1800ba4fd1c..84f8a36555c 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -2,7 +2,7 @@ * [Oppia's mission](https://github.com/oppia/oppia-android/wiki/Oppia's-Mission) * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|Home]]** - * [Coders](https://github.com/oppia/oppia-android/wiki#onboarding-instructions) + * [Coders](https://github.com/oppia/oppia-android/wiki#Contributing-to-Oppia-android) --- **Developing Oppia** From 46f9ea74cb267a87b8732ccf44b719c0077a48bc Mon Sep 17 00:00:00 2001 From: Vinita Murthi Date: Tue, 23 Nov 2021 21:33:57 +0530 Subject: [PATCH 252/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 84f8a36555c..3c2f56da30b 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -2,7 +2,7 @@ * [Oppia's mission](https://github.com/oppia/oppia-android/wiki/Oppia's-Mission) * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|Home]]** - * [Coders](https://github.com/oppia/oppia-android/wiki#Contributing-to-Oppia-android) + * [Coders](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android) --- **Developing Oppia** From 5aacc880da97b26f541aa6c1f45b9c1b37352728 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:19:01 +0530 Subject: [PATCH 253/374] Created PersistentCacheStore & In-Memory Blocking Cache (markdown) --- ...stentCacheStore-&-In-Memory-Blocking-Cache.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 PersistentCacheStore-&-In-Memory-Blocking-Cache.md diff --git a/PersistentCacheStore-&-In-Memory-Blocking-Cache.md b/PersistentCacheStore-&-In-Memory-Blocking-Cache.md new file mode 100644 index 00000000000..f7c70dfad05 --- /dev/null +++ b/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 From 4212cd4f9fa14f5cf55729410683472913eb4f46 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:19:48 +0530 Subject: [PATCH 254/374] Created Kotlin Coroutines (markdown) --- Kotlin-Coroutines.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 Kotlin-Coroutines.md diff --git a/Kotlin-Coroutines.md b/Kotlin-Coroutines.md new file mode 100644 index 00000000000..6173dc5bd53 --- /dev/null +++ b/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). From e5e27b917c1577944b805b857423d4123248f4b2 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:20:35 +0530 Subject: [PATCH 255/374] Created DataProvider & LiveData (markdown) --- DataProvider-&-LiveData.md | 48 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 DataProvider-&-LiveData.md diff --git a/DataProvider-&-LiveData.md b/DataProvider-&-LiveData.md new file mode 100644 index 00000000000..8f93c6b254c --- /dev/null +++ b/DataProvider-&-LiveData.md @@ -0,0 +1,48 @@ +### 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 + +Best practices: +- 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. From 56eeee40ad86cbe970fe639f64a95a157a167f9e Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:20:53 +0530 Subject: [PATCH 256/374] Updated DataProvider & LiveData (markdown) --- DataProvider-&-LiveData.md | 1 - 1 file changed, 1 deletion(-) diff --git a/DataProvider-&-LiveData.md b/DataProvider-&-LiveData.md index 8f93c6b254c..a3da67cef61 100644 --- a/DataProvider-&-LiveData.md +++ b/DataProvider-&-LiveData.md @@ -16,7 +16,6 @@ All ``DataProvider``s are convertible to ``LiveData`` using an extension functio ### Best practices/antipractices -Best practices: - 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) From 8e2be4594c59299727c751045a74ef3d2577ae52 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:29:50 +0530 Subject: [PATCH 257/374] Created Background Processing (markdown) --- Background-Processing.md | 46 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 Background-Processing.md diff --git a/Background-Processing.md b/Background-Processing.md new file mode 100644 index 00000000000..c7a4aecb665 --- /dev/null +++ b/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 From 6740959c8904603be166bd38d2eebad1478aa649 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:36:53 +0530 Subject: [PATCH 258/374] Divided the Background Processing wiki into individual pages --- _Sidebar.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 3c2f56da30b..0b309d746cf 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -30,7 +30,10 @@ * [[Ktlint Guide|https://github.com/oppia/oppia-android/wiki/Ktlint-Guide]] * [[XML code style format|https://github.com/oppia/oppia-android/wiki/XML-code-style-format]] * [[Static Analysis Checks|https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks]] - * [[Background Concurrent processing in Android DataProviders & Coroutines|https://github.com/oppia/oppia-android/wiki/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines]] + * [[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]] * [[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]] From 2245facc01a42877e4022854cbec3553fc6e4ed8 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 30 Nov 2021 14:38:23 +0530 Subject: [PATCH 259/374] Destroyed Background Concurrent processing in Android DataProviders & Coroutines (markdown) --- ...in-Android---DataProviders-&-Coroutines.md | 126 ------------------ 1 file changed, 126 deletions(-) delete mode 100644 Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md diff --git a/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md b/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md deleted file mode 100644 index 0b97f792be1..00000000000 --- a/Background-Concurrent-processing-in-Android---DataProviders-&-Coroutines.md +++ /dev/null @@ -1,126 +0,0 @@ -## 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 - -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. - -### 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. - -### 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). - -### 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 - -Best practices: -- 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. - -### 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 From 28dd7fea7f9d7619632e038c2fbcf0ab1e44eb8b Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 5 Dec 2021 15:51:15 +0530 Subject: [PATCH 260/374] Updated Frequent Errors and Solutions (markdown) --- Frequent-Errors-and-Solutions.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md index bb6cb230a52..7e101064e07 100644 --- a/Frequent-Errors-and-Solutions.md +++ b/Frequent-Errors-and-Solutions.md @@ -3,6 +3,14 @@ **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 table +**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:/oppia-android.git` From 29466f7f8728c49144302d14fb647e433e762f60 Mon Sep 17 00:00:00 2001 From: Sarthak Agarwal Date: Tue, 7 Dec 2021 19:17:46 +0530 Subject: [PATCH 261/374] What is RTL, What changes in RTL and Reference Docs. --- RTL-Guidelines.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/RTL-Guidelines.md b/RTL-Guidelines.md index f1814c72bc8..5e74e943213 100644 --- a/RTL-Guidelines.md +++ b/RTL-Guidelines.md @@ -1,3 +1,37 @@ +# What is RTL? +The main difference between left-to-right (LTR) and right-to-left (RTL) language scripts is the direction in which content is displayed: + +* LTR languages display content from left to right +* RTL languages display content from right to left + +RTL content also affects the direction in which some icons and images are displayed, particularly those depicting a sequence of events. + +In general, the passage of time is depicted as left to right for LTR languages, and right to left for RTL languages. + +![](https://user-images.githubusercontent.com/53938155/145036934-691c6bda-a58b-4977-9247-cb6e3830dee7.png) + +When a UI is changed from LTR to RTL (or vice-versa), it’s often called mirroring. An RTL layout is the mirror image of an LTR layout, and it affects layout, text, and graphics. + +# What changes in RTL? + +When a UI is mirrored, these changes occur: + +* Text fields icons are displayed on the opposite side of a field +* Navigation buttons are displayed in reverse order +* Icons that communicate direction, like arrows, are mirrored +* Text (if it is translated to an RTL language) is aligned to the right + +These items are not mirrored: + +* Untranslated text (even if it’s part of a phrase) +* Icons that don’t communicate direction, such as a camera +* Numbers, such as those on a clock and phone numbers +* Charts and graphs + +Text should always be in the correct direction for the language it’s in. For example, any LTR words, such as a URL, will continue to be shown in an LTR format, even if the rest of the UI is in RTL. + +![](https://user-images.githubusercontent.com/53938155/145037261-2f7afb57-cbeb-4a6e-8ac7-c47261790945.png) + # Testing app for RTL Layouts To test any screen for RTL language follow these steps: 1. Enable [`Developer Options`](https://developer.android.com/studio/debug/dev-options) on your device. @@ -7,3 +41,8 @@ Make this language as primary language from your `Language Preferences` in `Sett The screen will look something like this: + +# 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) From 89ab98fef2b66c187276041bd0e3205f897e9ce9 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Mon, 3 Jan 2022 11:27:55 +0530 Subject: [PATCH 262/374] Updated Working on UI (markdown) --- Working-on-UI.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Working-on-UI.md b/Working-on-UI.md index 415c26e6b31..5371cb7c97d 100644 --- a/Working-on-UI.md +++ b/Working-on-UI.md @@ -5,9 +5,11 @@ For understanding the mocks let's take one example. Open [Admin Auth Mock Link](https://xd.adobe.com/view/0687f00c-695b-437a-79a6-688e7f4f7552-70b6/screen/a841330e-efe5-4bdb-acdd-4d6e52a59571/PC-MP-Admin-Authorization-Add-Profile-Empty-) In the below image you can see that there are two icons on left side of the screen. First icon is for comment, using which you can comment on the mock and second icon is for screen details which provide detailed information about the UI. + Screenshot 2020-01-22 at 3 14 13 PM Once you have selected the second icon, you will see a menu on right as below: + Screenshot 2020-01-22 at 3 17 03 PM This menu contains details about the screen width, colors, fonts, etc. Also, please note that the screen width in the mocks is **360 px**. @@ -36,10 +38,10 @@ Do not forget to check the opacity value in mocks. For example you find Opacity 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 not using blur effect in android code, so if the mock item does have a blur value than in that case optimise the android code in such a way that it does look almost like the mock without using the 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 and use it accordingly in the code. +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. @@ -63,3 +65,5 @@ Accessibility Scanner scans your screen and provides suggestions to improve the * 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) From c30f2ee5e67a29e54c9454f1abbc2402f38d7c8b Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Mon, 3 Jan 2022 11:31:24 +0530 Subject: [PATCH 263/374] Destroyed XML code style format (markdown) --- XML-code-style-format.md | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 XML-code-style-format.md diff --git a/XML-code-style-format.md b/XML-code-style-format.md deleted file mode 100644 index 566f12171a9..00000000000 --- a/XML-code-style-format.md +++ /dev/null @@ -1,39 +0,0 @@ - -Android Code Style improves productivity. When working alone on your apps you don’t have problems with your manual code formatting. Whereas while multiple developers, with multiple opinions, multiple operating systems and multiple screen sizes work on the same code base, if you don’t let a tool format your code, discussions about the formatting may arise or worse, different formatting and sorting increases diffs and can cause completely unnecessary merge conflicts. This will slow down development for no reason. - -It’s professional to have common formatting throughout the project. It helps the project to be ready to scale to two or more developers. -## Steps to do -* **Android Studio**>**Preferences(in mac)** -**Open Settings** > **Editor** >**Code Style** > **XML** > **Others** -![8](https://user-images.githubusercontent.com/54615666/80364656-ea4a3500-88a3-11ea-9b7b-ab804e8bbf55.png) -![pasted image 0](https://user-images.githubusercontent.com/54615666/80364659-eae2cb80-88a3-11ea-819a-f1d96beaea8b.png) -* Keep blank lines: 2 change it to 0 - -* **Open Settings** > **Editor** > **Code Style** > **XML** > **Android** Click **Set from...** text. -* Select **Predefined Styles** > **Android** Click **Apply button** - -![2](https://user-images.githubusercontent.com/54615666/80364643-e5858100-88a3-11ea-8a15-7a6e9ecf785c.png) - -## Final Settings - -![3](https://user-images.githubusercontent.com/54615666/80364649-e7e7db00-88a3-11ea-97c4-46b3bc2096eb.png) -![4](https://user-images.githubusercontent.com/54615666/80364650-e8807180-88a3-11ea-818b-effa8e4e2897.png) - -## Other Settings -![5](https://user-images.githubusercontent.com/54615666/80364651-e9190800-88a3-11ea-82ce-874110ff53c3.png) -![6](https://user-images.githubusercontent.com/54615666/80364653-e9b19e80-88a3-11ea-8489-1b6fafeb518a.png) -![7](https://user-images.githubusercontent.com/54615666/80364655-e9b19e80-88a3-11ea-90f4-15662f9f04c0.png) -![8](https://user-images.githubusercontent.com/54615666/80364656-ea4a3500-88a3-11ea-9b7b-ab804e8bbf55.png) - - -## Share rules -Formatting files makes even more sense when multiple people are working on a project so of course, should share formatting rules with the team. It’s a good start if we use Android Studio’s default code formatting. But that’s unsafe! The default settings have changed in the past and will change in the future. Our team should use a code style independent from the IntelliJ version one is working on. So if we want any custom changes that would help all, please do update in this doc and share rules. -Find current rules in CodeStyleRules.xml -## Beyond Setting Changes -After following all these steps in android studio, now it is easy to use standard code guidelines in XML files. - -Reformat all edited files automatically in android studio using the following command. -* **Windows:** Ctrl + Alt + L -* **Linux:** Ctrl + Shift + Alt + L -* **mac:** Option + Command + L -* **Ubuntu** users might face the issue because Ctrl + Alt + L locks the screen by default nature. Refer to this stackoverflow-link on how to solve this. From 1c9d11c08e461d0a8d9adbf549917ca9e381560e Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Mon, 3 Jan 2022 11:32:26 +0530 Subject: [PATCH 264/374] Removed XML Code Style wiki --- _Sidebar.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_Sidebar.md b/_Sidebar.md index 0b309d746cf..83d4a1a7612 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -27,8 +27,7 @@ **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]] - * [[XML code style format|https://github.com/oppia/oppia-android/wiki/XML-code-style-format]] + * [[Ktlint Guide|https://github.com/oppia/oppia-android/wiki/Ktlint-Guide]] * [[Static Analysis Checks|https://github.com/oppia/oppia-android/wiki/Static-Analysis-Checks]] * [[Background Processing|https://github.com/oppia/oppia-android/wiki/Background-Processing]] * [[Kotlin Coroutines|https://github.com/oppia/oppia-android/wiki/Kotlin-Coroutines]] From a8af63d05511bf7c64daf07d08daf5450ff4807c Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 4 Jan 2022 23:10:46 -0800 Subject: [PATCH 265/374] Updated Oppia Android Testing (markdown) --- Oppia-Android-Testing.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Oppia-Android-Testing.md b/Oppia-Android-Testing.md index 4649f558bd1..c110bdb925d 100644 --- a/Oppia-Android-Testing.md +++ b/Oppia-Android-Testing.md @@ -103,6 +103,7 @@ public class MyActivityTest { 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: @@ -138,6 +139,8 @@ class PinPasswordActivityTest { } ``` +**Important note:** When running the Espresso tests, ensure that you are using the **API 28** emulator. If you use e.g. API 30, you may get a message saying "0 tests passed" when trying to run the tests. + ### How to use View Matchers, View Actions and View Assertions in Espresso? Espresso has many ViewMatcher options which are very effective in uniquely locate UI element. You can also combine and create a combination of View Matchers to find element uniquely. From 824db380f896643baf4c363e309b23c78e17eef2 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 9 Jan 2022 16:30:52 +0530 Subject: [PATCH 266/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 7cceb41585b..ceb75aa2c71 100644 --- a/Home.md +++ b/Home.md @@ -1,6 +1,6 @@ Thanks for your interest in contributing to the Oppia project, and making it easier for students to learn online in an effective and enjoyable way! -There are lots of 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/). Don't worry if you're new to "open source", or if you're 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 around the world to learn things better, and that you're responsible and reliable. +There are lots of 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 if you're 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 around the world to learn things better, and that you're responsible and reliable. To make it easier to get started, we've catalogued some of the different ways to help out. Please feel free to take a look through them, and see if any interest you: From aa531653d4438064b5fccff12328f7f8b3049cc2 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sun, 9 Jan 2022 16:41:49 +0530 Subject: [PATCH 267/374] Updated _Sidebar (markdown) --- _Sidebar.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 83d4a1a7612..7469941787f 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -6,13 +6,16 @@ --- **Developing Oppia** - * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki]] + * [[Contributing to Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] + * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] + * [[Finding Something to do|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do]] * 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 * [[Making a code change|https://github.com/oppia/oppia-android/wiki/making-a-code-change]] + * [[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]] * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] @@ -29,10 +32,12 @@ * [[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 Guile|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]] + * [[Developing skills|https://github.com/oppia/oppia-android/wiki/Developing-skills]] * [[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]] From ff356073538e7496a6a9c609b6c02ba0b0587384 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sat, 15 Jan 2022 23:09:01 +0530 Subject: [PATCH 268/374] Added a description on how to write E2E tests --- End-to-End-Testing-Guide.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/End-to-End-Testing-Guide.md b/End-to-End-Testing-Guide.md index 2544a7a6d05..ad8581fbcaa 100644 --- a/End-to-End-Testing-Guide.md +++ b/End-to-End-Testing-Guide.md @@ -88,3 +88,24 @@ The android_binary of a test suite generates a test apk with the same name as th 4. Prefer using existing helpers from ``EndToEndTestHelper`` rather than reimplementing them. 5. Prefer testing whole end-to-end flows rather than specific behaviors. For example: opening the app, downloading a topic, and being able to play it is an excellent end-to-end test since it’s verifying multiple cross-stack behaviors. Conversely, testing that a thumbnail is aligned correctly on the home screen is less useful and ought to be tested in Robolectric or Espresso local to the component showing that image. 6. Use uiautomatorviewer to get details of each view such as resource ID, content description, class, and other properties. + +### Writing E2E tests +Unlike Robolectric and Espresso, tests in UiAutomator don't share the same code as Espresso and Robolectric. UiAutomator tests are dependent on [UiDevice](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice). UiDevice provides access to all the views and gives possibilities to stimulate all UserActions in the device/emulator including an app other than the current app. + +In the instrumentation module all the UiAutomator tests are written using the Extensions of UiDevice in [EndToEndTestHelper.kt](https://github.com/oppia/oppia-android/blob/develop/instrumentation/src/java/org/oppia/android/instrumentation/testing/EndToEndTestHelper.kt) + +**Example:** +To navigate from Profile screen to a Exploration page +``` + // device is a Instance of UiDevice. + device.findObjectByRes("skip_text_view").click() // Click on the "skip" button on the onBoarding page. + device.findObjectByRes("get_started_button").click() // Click on the "Getting Started' button. + device.waitForRes("profile_select_text") // Waiting for the Profile Select screen to appear. + device.findObjectByText("Admin").click() // Click on the admin profile. + scrollRecyclerViewTextIntoView("First Test Topic") // Scroll to the view with text "First Test Topic. + device.findObjectByText("First Test Topic").click() // Click on the "First Test Topic" text. + device.findObjectByText("LESSONS").click() // Click on the "Lessons" tab. + device.findObjectByText("First Story").click() // Click on the "First Story" tab. + scrollRecyclerViewTextIntoView("Chapter 1: Prototype Exploration") // Scroll to first exploration. + device.findObjectByText("Chapter 1: Prototype Exploration").click() // Click on the first exploration. +``` \ No newline at end of file From 8ecebd60e9926c3794ff540ffba2e40e7b024ec6 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 18 Jan 2022 00:52:21 +0530 Subject: [PATCH 269/374] Nit typo fix --- Frequent-Errors-and-Solutions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Frequent-Errors-and-Solutions.md b/Frequent-Errors-and-Solutions.md index 7e101064e07..dac1bd3240c 100644 --- a/Frequent-Errors-and-Solutions.md +++ b/Frequent-Errors-and-Solutions.md @@ -3,7 +3,7 @@ **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 table +## 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 From 9025481f108eb1422815cde577b61718a1a03fb4 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 20 Jan 2022 00:16:54 -0800 Subject: [PATCH 270/374] Created Writing design docs (markdown) --- Writing-design-docs.md | 49 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 Writing-design-docs.md diff --git a/Writing-design-docs.md b/Writing-design-docs.md new file mode 100644 index 00000000000..7207300dc9c --- /dev/null +++ b/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. + From 7b37802fb9cb80b1c8e9e3f45ec25d3a77456148 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 20 Jan 2022 00:17:50 -0800 Subject: [PATCH 271/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index 7469941787f..5e44871ad72 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -26,6 +26,7 @@ * [[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 From 685b0cf501ea318a23165b6791e12bf55330fb59 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:44:08 +0530 Subject: [PATCH 272/374] Created Work Manager (markdown) --- Work-Manager.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 Work-Manager.md diff --git a/Work-Manager.md b/Work-Manager.md new file mode 100644 index 00000000000..5cd813addb1 --- /dev/null +++ b/Work-Manager.md @@ -0,0 +1,164 @@ +# What is WorkManager? +WorkManager is part of Android Jetpack and an Architecture Component for background work that needs a combination of opportunistic and guaranteed execution. Opportunistic execution means that WorkManager will do your background work as soon as it can. Guaranteed execution means that WorkManager will take care of the logic to start your work under a variety of situations, even if you navigate away from your app. + +WorkManager is an incredibly flexible library that has many additional benefits. These include: +- Support for both asynchronous one-off and periodic tasks +- Support for constraints such as network conditions, storage space, and charging status +- Chaining of complex work requests, including running work in parallel +- Output from one work request used as input for the next +- Handling API level compatibility back to API level 14 (see note) +- Working with or without Google Play services +- Following system health best practices +- LiveData support to easily display work request state in UI + +The WorkManager library is a good choice for tasks that are useful to complete, even if the user navigates away from the particular screen or your app. Some examples of tasks that are a good use of WorkManager: +- Uploading logs +- Applying filters to images and saving the image +- Periodically syncing local data with the network + +WorkManager offers guaranteed execution, and not all tasks require that. As such, it is not a catch-all for running every task off of the main thread. + +# Its Usage in Oppia Android +There are a few WorkManager classes you need to know about: + +- `Worker`: This is where you put the code for the actual work you want to perform in the background. You'll extend this class and override the doWork() method. +- `WorkRequest`: This represents a request to do some work. You'll pass in your Worker as part of creating your WorkRequest. When making the WorkRequest you can also specify things like Constraints on when the Worker should run. There are two types of work supported by WorkManager: OneTimeWorkRequest and PeriodicWorkRequest. +- `WorkManager`: This class actually schedules your WorkRequest and makes it run. It schedules WorkRequests in a way that spreads out the load on system resources, while honoring the constraints you specify. + + +In Oppia we are using WorkManager in two scenarios : +- To upload cached Logs (for Analytics) over FirebaseAnalytics whenever data connection and battery requirements are met. This was implemented by @Sarthak2601 during GSoC'20, for more details you can go through the [proposal idea](https://github.com/oppia/oppia/wiki/pdfs/GSoC2020SarthakAgarwal.pdf) +- To sync up the PlatformParameters from OppiaBackend whenever the app starts and the data + battery requirements are met. This was implemented by @ARJUPTA during GSoC'21, for more details you can go through the [proposal idea](https://github.com/oppia/oppia/wiki/pdfs/GSoC2021ArjunGupta.pdf) + +# How to use WorkManager +If you want to introduce a new feature or any change to the existing WorkManager implementation in oppia-android, here is the basic structure of files you need to keep in mind : + +1. Start with creating a Worker class (we have used `ListenableWorker` till now everywhere) for eg - MyFeatureWorker. + + ``` + class LogUploadWorker private constructor( + context: Context, + params: WorkerParameters, + ... + @BackgroundDispatcher private val backgroundDispatcher: CoroutineDispatcher + ) : ListenableWorker(context, params) { + @ExperimentalCoroutinesApi + override fun startWork(): ListenableFuture { + val backgroundScope = CoroutineScope(backgroundDispatcher) + val result = backgroundScope.async {...} + return if(checkWorkDone(result)) Result.success() else Result.failure() + } + } + ``` + +2. Then after implementing all the functionality in MyFeatureWorker, create a custom WorkerFactory class (for eg- MyFeatureWorkerFactory) so that we can provide any extra parameters if needed. + + ``` + class LogUploadWorkerFactory @Inject constructor( + private val workerFactory: LogUploadWorker.Factory + ) : WorkerFactory() { + + /** Returns a new [LogUploadWorker] for the given context and parameters. */ + override fun createWorker( + appContext: Context, + workerClassName: String, + workerParameters: WorkerParameters + ): ListenableWorker? { + return workerFactory.create(appContext, workerParameters) + } + } + ``` + +3. Provide an instance of this WorkerFactory class in the `WorkManagerConfigurationModule` so that a singular work manager configuration can be made for the entire app. + + ``` + @Module + class WorkManagerConfigurationModule { + + @Singleton + @Provides + fun provideWorkManagerConfiguration( + logUploadWorkerFactory: LogUploadWorkerFactory, + platformParameterSyncUpWorkerFactory: PlatformParameterSyncUpWorkerFactory + ): Configuration { + val delegatingWorkerFactory = DelegatingWorkerFactory() + delegatingWorkerFactory.addFactory(logUploadWorkerFactory) + delegatingWorkerFactory.addFactory(platformParameterSyncUpWorkerFactory) + return Configuration.Builder().setWorkerFactory(delegatingWorkerFactory).build() + } + } + ``` + +4. After all these steps create an Initializer class (for eg- MyFeatureWorkerInitializer) that will prepare and enqueue a WorkRequest for you at the time when app starts. + + ``` + @Singleton + class LogUploadWorkManagerInitializer @Inject constructor( + private val context: Context, + private val logUploader: LogUploader + ) : ApplicationStartupListener { + override fun onCreate() { + val workManager = WorkManager.getInstance(context) + logUploader.enqueueWorkRequestForEvents(workManager, workRequestForUploadingEvents) + logUploader.enqueueWorkRequestForExceptions(workManager, workRequestForUploadingExceptions) + } + } + ``` + +**Note** - All the parts of WorkManager implementation entirely lie in the domain layer, but there are few functionalities that you may need to acquire from other layers for eg- if you need to make a network request you would probably need to interact with data layer also. + +# Writing tests with WorkManager +For writing any test with WorkManager you will need to interact with +- *WorkManagerTestInitHelper* so that you can emulate the enquing and running of WorkRequests. + + ``` + @Before + fun setUp() { + setUpTestApplicationComponent() + context = InstrumentationRegistry.getInstrumentation().targetContext + val config = Configuration.Builder() + .setExecutor(SynchronousExecutor()) + .setWorkerFactory(logUploadWorkerFactory) + .build() + WorkManagerTestInitHelper.initializeTestWorkManager(context, config) + } + ``` +- *TestCoroutinesDispatcher* so that you can block the code execution up untill WorkRequest(s) are running. (ie. working with suspend functions) +- You might also need to introduce some fakes so that you can make sure the entities (object, classes, varaibles & constants etc.) over which you MyFeatureWorker depends doesn't have any bugs. + +Here is an exemplar test that is using WorkManager to enqueue a WorkRequest with any inputData (if needed). After we enqueue a request, the next step is to wait until its execution is completed and for that we are using testCoroutineDispatchers - +``` + @Test + fun testWorker_logEvent_withoutNetwork_enqueueRequest_verifySuccess() { + networkConnectionUtil.setCurrentConnectionStatus(NONE) + analyticsController.logTransitionEvent( + eventLogTopicContext.timestamp, + eventLogTopicContext.actionName, + oppiaLogger.createTopicContext(TEST_TOPIC_ID) + ) + + val workManager = WorkManager.getInstance(ApplicationProvider.getApplicationContext()) + + val inputData = Data.Builder().putString( + LogUploadWorker.WORKER_CASE_KEY, + LogUploadWorker.EVENT_WORKER + ).build() + + val request: OneTimeWorkRequest = OneTimeWorkRequestBuilder() + .setInputData(inputData) + .build() + + workManager.enqueue(request) + testCoroutineDispatchers.runCurrent() + val workInfo = workManager.getWorkInfoById(request.id) + + assertThat(workInfo.get().state).isEqualTo(WorkInfo.State.SUCCEEDED) + assertThat(fakeEventLogger.getMostRecentEvent()).isEqualTo(eventLogTopicContext) + } +``` + +In Oppia we write tests for both the Worker and its Initializer class. You can take a reference for the same from these files: + +Worker Tests - *[PlatformParameterSyncUpWorkerTest](https://github.com/oppia/oppia-android/blob/develop/domain/src/test/java/org/oppia/android/domain/platformparameter/syncup/PlatformParameterSyncUpWorkerTest.kt) OR [LogUploadWorkerTest](https://github.com/oppia/oppia-android/blob/develop/domain/src/test/java/org/oppia/android/domain/oppialogger/loguploader/LogUploadWorkerTest.kt)* + +Initializer Tests - *[PlatformParameterSyncUpWorkManagerInitializerTest](https://github.com/oppia/oppia-android/blob/develop/domain/src/test/java/org/oppia/android/domain/platformparameter/syncup/PlatformParameterSyncUpWorkManagerInitializerTest.kt) OR [LogUploadWorkManagerInitializerTest](https://github.com/oppia/oppia-android/blob/develop/domain/src/test/java/org/oppia/android/domain/oppialogger/loguploader/LogUploadWorkManagerInitializerTest.kt)* \ No newline at end of file From 32c4a2daa42a8c791bce77f401f104b4ef72be5d Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:45:53 +0530 Subject: [PATCH 273/374] Added Work Manager wiki under Developer Reference section --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index 5e44871ad72..525618d6aa8 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -42,6 +42,7 @@ * [[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]] * [[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]] From 03c144fb7a47455adc04531053ffd5ac0b19a2ec Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:47:03 +0530 Subject: [PATCH 274/374] Created Dependency Injection (markdown) --- Dependency-Injection.md | 52 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 Dependency-Injection.md diff --git a/Dependency-Injection.md b/Dependency-Injection.md new file mode 100644 index 00000000000..43b4d7b4012 --- /dev/null +++ b/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]("Dagger.md") \ No newline at end of file From 5b457d716239219bc9587021afe479e7c3c9c81f Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:49:10 +0530 Subject: [PATCH 275/374] Created Dagger (markdown) --- Dagger.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 Dagger.md diff --git a/Dagger.md b/Dagger.md new file mode 100644 index 00000000000..c92830d9366 --- /dev/null +++ b/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: +
    +
  • Root application component for @Singleton that's initialized in a custom Application class
    • +
  • Per-activity and per-fragment subcomponents that are initialized in base activity and fragment classes, respectively
    • +
  • Inheritance such that all application-level classes can be injected in activities, and all activity-level classes can be injected into fragments (but not vice versa for either)
    • +
  • Activity & fragment controllers for each activity and fragment that are @Inject-constructed, and can inject all needed dependencies and perform necessary UI logic
    • +
  • Activity and fragment classes become boilerplate classes that extend base classes that enable DI for them, and delegate UI callbacks to their controller classes for processing
    • +
  • View models are also injectable for use in controllers per a ProAndroidDev article
    • +
  • Similar to Dagger Android, but with better encapsulation
    • +
+ 		+ +
+ +You can understand it with this example : + +This is a Singleton-scoped object with dependency. Note that because Factory is `@Singleton` scoped, it can inject everything in the Singleton component including blocking dispatcher. +``` +@Singleton +class Factory @Inject constructor(@BlockingDispatcher private val blockingDispatcher: CoroutineDispatcher) { + fun create(): InMemoryBlockingCache { + return InMemoryBlockingCache(blockingDispatcher) + } +} +``` + +These are Singleton-scoped providers with custom qualifiers. Note also that to distinguish between two of the same types, we can use custom qualifier annotations like @BackgroundDispatcher and @BlockingDispatcher. + +``` +@Module +class DispatcherModule { + @Provides + @BackgroundDispatcher + @Singleton + fun provideBackgroundDispatcher(): CoroutineDispatcher { + return Executors.newFixedThreadPool(4).asCoroutineDispatcher() + } + + @Provides + @BlockingDispatcher + @Singleton + fun provideBlockingDispatcher(): CoroutineDispatcher { + return Executors.newSingleThreadExecutor().asCoroutineDispatcher() + } +} +``` + + + +# How to write Tests with Dagger +- Dependencies can be replaced at test time +- This is especially useful for API endpoints! We can replace Retrofit instances with mocks that let us carefully control request/response pairs +- This is also useful for threading! We can synchronize coroutines and ensure they complete before continuing test operations +- Tests can declare their own scoped modules in-file +- Tests themselves create a test application component and inject dependencies directly into @Inject-able fields +- Bazel (#59) will make this even easier since test modules could then be shareable across tests + +Here is an example of testing with Oppia Dagger. This shows setting up a test component and using it to inject dependencies for testing purposes. It also shows how to create a test-specific dependency that can be injected into a test for manipulation. +``` +class InMemoryBlockingCacheTest { + @ExperimentalCoroutinesApi @Inject @field:TestDispatcher lateinit var testDispatcher: TestCoroutineDispatcher + @ExperimentalCoroutinesApi private val backgroundTestCoroutineScope by lazy { CoroutineScope(backgroundTestCoroutineDispatcher) } + @ExperimentalCoroutinesApi private val backgroundTestCoroutineDispatcher by lazy { TestCoroutineDispatcher() } + + @Before @ExperimentalCoroutinesApi fun setUp() { setUpTestApplicationComponent() } + + @Test @ExperimentalCoroutinesApi fun `test with testDispatcher since it's connected to the blocking dispatcher`() = runBlockingTest(testDispatcher) { /* ... */ } + + private fun setUpTestApplicationComponent() { + DaggerInMemoryBlockingCacheTest_TestApplicationComponent.builder().setApplication(ApplicationProvider.getApplicationContext()).build().inject(this) + } + + @Qualifier annotation class TestDispatcher + @Module + class TestModule { + @ExperimentalCoroutinesApi @Singleton @Provides @TestDispatcher fun provideTestDispatcher(): TestCoroutineDispatcher { return TestCoroutineDispatcher() } + @ExperimentalCoroutinesApi @Singleton @Provides @BlockingDispatcher + fun provideBlockingDispatcher(@TestDispatcher testDispatcher: TestCoroutineDispatcher): CoroutineDispatcher { return testDispatcher } + } + + @Singleton + @Component(modules = [TestModule::class]) + interface TestApplicationComponent { + @Component.Builder interface Builder { @BindsInstance fun setApplication(application: Application): Builder fun build(): TestApplicationComponent } + fun inject(inMemoryBlockingCacheTest: InMemoryBlockingCacheTest) + } +} +``` + +# Points to Note +Dagger compile-time errors can be hard to understand +- When you encounter one: scan the error for the dependency name (it's likely a dependency you just imported into the file failing to compile) +- Search for the Dagger module you want to use to provide that dependency +- Make sure your Gradle module or Bazel build file depends on the library that contains the module you need +- Note that Gradle modules cannot depend on the app module, which means any Dagger modules in the app Gradle module are inaccessible outside of the app module \ No newline at end of file From 748b28e31dbaf79bc1b29cc45685f0c6ccbceebd Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:49:44 +0530 Subject: [PATCH 276/374] Corrected the Dagger Wiki link --- Dependency-Injection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dependency-Injection.md b/Dependency-Injection.md index 43b4d7b4012..313d7a885f6 100644 --- a/Dependency-Injection.md +++ b/Dependency-Injection.md @@ -49,4 +49,4 @@ class PersistentCacheStore private constructor() { } ``` -Hence this calls for a framework that can help us with Dependency Injection in Android and Dagger seems the most favourable choice. [ReadMore]("Dagger.md") \ No newline at end of file +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 From 6859a3e20a657f2cf9eee7b730e478b38a383754 Mon Sep 17 00:00:00 2001 From: Arjun Gupta Date: Tue, 1 Feb 2022 19:53:33 +0530 Subject: [PATCH 277/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index 525618d6aa8..e8384b4719d 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -43,6 +43,7 @@ * [[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]] From f958595579d1a07d42d27c00ebe91cd8762c294d Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Wed, 2 Feb 2022 23:00:55 +0530 Subject: [PATCH 278/374] Created Get Help (markdown) --- Get-Help.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 Get-Help.md diff --git a/Get-Help.md b/Get-Help.md new file mode 100644 index 00000000000..ce2b796f885 --- /dev/null +++ b/Get-Help.md @@ -0,0 +1,166 @@ +## Table of Contents + +* [Communication channels](#communication-channels) + * [Email](#email) + * [Gitter](#gitter) + * [Google Chat or Hangouts](#google-chat-or-hangouts) + * [GitHub](#github) + * [GitHub Discussions](#github-discussions) +* [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. + +### Gitter + +We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! 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. For questions about setting up Oppia or regarding the codebase or tests you can create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) where Oppia's Welfare team and other developers will assist you in resolving the issue. + +You can also directly message developers over Gitter. However, some developers don't monitor their Gitter messages regularly, so you might not get a response very quickly (or at all). + +### 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). + +### GitHub Discussions +If you have questions regarding Oppia you can create a discussion here where Oppia's Welfare team and other developers will assist you in resolving the issue. 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. +* Setup Issues: Any issues that developers are facing with setting up or starting the server. +* Q&A: Any questions that developers have. +* Ideas: Any developer can place an idea here and it can be discussed here. +* Release: Discussion for bugs & PRs targeting the release. + +You can refer to [this guide](https://docs.github.com/en/discussions/quickstart#creating-a-new-discussion) on how to create a new discussion. + +## 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). +* 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**, you can drop a message on the [gitter](https://gitter.im/oppia/oppia-chat#) chat too. + +* 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://gitter.im/oppia/oppia-android) 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 the [gitter chat](https://gitter.im/oppia/oppia-android) 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 From 309a5d6a8543a29087f0e0839452d9f8c029aedb Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Wed, 2 Feb 2022 23:03:23 +0530 Subject: [PATCH 279/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index e8384b4719d..5a5ddae5de9 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -18,6 +18,7 @@ * [[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]] + * [[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]] * Testing * [[Oppia Android Testing|https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing]] From 0e21334cff348b6859215471aa2b70fba35af357 Mon Sep 17 00:00:00 2001 From: Farees Hussain Date: Sat, 5 Feb 2022 19:44:30 +0530 Subject: [PATCH 280/374] Updated End to End Testing Guide (markdown) --- End-to-End-Testing-Guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/End-to-End-Testing-Guide.md b/End-to-End-Testing-Guide.md index ad8581fbcaa..d88897d2168 100644 --- a/End-to-End-Testing-Guide.md +++ b/End-to-End-Testing-Guide.md @@ -66,7 +66,7 @@ The android_binary of a test suite generates a test apk with the same name as th ``` 2. install the oppia_test.apk and the test suite’s APK ``` - adb install -r bazel-bin/oppia_test.apk && adb install -r bazel-bin/instrumentation/.apk + adb install -r bazel-bin/instrumentation/oppia_test.apk && adb install -r bazel-bin/instrumentation/.apk ``` e.g.: ``` From e36af0e5a214d66d3e780ddbfa184333c1efd861 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Thu, 10 Feb 2022 12:27:51 +0530 Subject: [PATCH 281/374] Updated "Finding something to do" --- Contributing-to-Oppia-android.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md index c9a2523f887..07fbc39e9d8 100644 --- a/Contributing-to-Oppia-android.md +++ b/Contributing-to-Oppia-android.md @@ -116,13 +116,10 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav **UI** - - [RTL Exempted files](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+RTL+Exempted+file) - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) **Bazel** - - [Create bazel subpackage](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22Bazel+Stage+2%22+label%3A%22good+first+issue%22) - **Accessibility** - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) From 6d89f94da284e050b4440b489cc363d60d92dad1 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Wed, 16 Feb 2022 07:37:28 -0800 Subject: [PATCH 282/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 5a5ddae5de9..ca8d6324408 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -10,6 +10,7 @@ * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] * [[Finding Something to do|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do]] + * [[How to Get Help | https://github.com/oppia/oppia-android/wiki/Get-Help]] * 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]] @@ -18,7 +19,6 @@ * [[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]] - * [[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]] * Testing * [[Oppia Android Testing|https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing]] From 85a196e8238a8f956b0ae3c312b6b02e3f7952c2 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Thu, 17 Feb 2022 00:11:01 +0530 Subject: [PATCH 283/374] Created Teams at oppia android (markdown) --- Teams-at-oppia-android.md | 73 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 Teams-at-oppia-android.md diff --git a/Teams-at-oppia-android.md b/Teams-at-oppia-android.md new file mode 100644 index 00000000000..71af0a3a98f --- /dev/null +++ b/Teams-at-oppia-android.md @@ -0,0 +1,73 @@ +## Teams at Oppia android + +The Oppia team is a distributed team of contributors from all over the world. To ensure that the project is as stable as possible, we have several infrastructure teams devoted to maintaining the health of various aspects of the development workflow. We also have an onboarding team that helps new contributors get started with the project and a welfare team responsible for assisting new contributors. + +This wiki page explains the different teams in Oppia and their composition. + +### Clam Team + +CLAM team is responsible for most of the UI based code (app-layer), which includes exploration player, question player, concept-card, subtopics, topics, etc. All these user-facing features must be RTL supportive, accessible by all and should work on all devices (mobile + tablet). + +**Team contact:** Rajat Talesra (@rt4914) (lead), Yash Verma (@yash10019coder) + +### Dev-workflow Team +The dev-workflow team ensures that the Oppia development process is smooth, stable and enjoyable, by ensuring that the following always hold: + +1. There are no issues with the codebase setup (especially for new contributors). +2. Automated checks work as intended and are not unduly burdensome on both contributor’s machines and CI servers. +3. The technical documentation on the wiki is well-arranged, useful, and correct. +4. There are no security issues relating to npm dependencies. +5. The review process is speedy and streamlined. + +Long-term projects include: + +1. Working with the Onboarding team to identify areas where new contributors get stuck during the onboarding process and taking steps to fix those issues. +2. Streamlining the code review flow by: + * adding pre-submit checks for common errors + * enabling Oppiabot to automatically handle review/code-owner assignments + * speeding up the CI processes. + +**Team contact:** Vinita Murthi (@vinitamurthi) (lead), Arjun Gupta (@ARJUPTA) + +### Infrastructure Teams + +##### Core Maintainers Team +The core maintainers team is accountable to the Oppia developer community with regards to preserving the stability of the entire Oppia codebase, by ensuring that the following things are true at all times for the "develop" branch on GitHub: +1. It is free of serious bugs that adversely impact the end-user experience. +2. It passes the CI checks. +3. It has no security issues. + +Because this group understands the "big picture" of Oppia, other contributors are expected to take their advice seriously, especially when members of this group are acting in an incident-response capacity. + +Membership of this group is decided by appointment, by a committee made up of the currently-serving core maintainers. + +Contributors should notify the members of this team when they see major bugs or security vulnerabilities. The Core Maintainers group can be contacted via the @oppia/core-maintainers alias or at oppia-core-maintainers@googlegroups.com. + + +##### Release Process Team +This team is responsible for ensuring that Oppia releases happen smoothly, correctly, and on time. Long-term projects include: +1. Streamlining the release process, and automating as many parts as possible, in order to reduce the chance of human error. +2. Adding automatic safeguards to ensure the correctness of releases. +3. Organizing the release coordinator rotation. + +**Team Contact:** Ben Henning (@BenHenning) + +##### Quality Assurance Team +This team is responsible for ensuring that the Oppia codebase and releases are bug-free. Long-term projects include: +1. Deciding on a strategy for maintaining test coverage. +2. Improving test coverage to 100%. +3. Reducing the StackDriver error count to 0. +4. Organize the QA and bug fixing teams for each release. +5. Fix any known bugs in Oppia (especially user-facing ones). + +**Team Contact:** Ben Henning (@BenHenning) + +### Onboarding Team +The onboarding team aims to welcome new contributors and answer their questions. + +**Team contact:** Rajat Talesra (@rt4914) (lead), Sarthak Aggarwal (@Sarthak2601) + +### Welfare Team +The welfare team is a group of Oppia developers who are committed to helping developers to be able to unblock themselves when they face any problems. + +**Team contact:** Farees Hussain (@FareesHussain) (lead), Apoorv Srivastava (@MaskedCarrot) \ No newline at end of file From 6da5a79519b47c416b891019edeb2cd91ac18db8 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Thu, 17 Feb 2022 00:11:15 +0530 Subject: [PATCH 284/374] Updated Teams at oppia android (markdown) --- Teams-at-oppia-android.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/Teams-at-oppia-android.md b/Teams-at-oppia-android.md index 71af0a3a98f..3dfbaff0afb 100644 --- a/Teams-at-oppia-android.md +++ b/Teams-at-oppia-android.md @@ -1,5 +1,3 @@ -## Teams at Oppia android - The Oppia team is a distributed team of contributors from all over the world. To ensure that the project is as stable as possible, we have several infrastructure teams devoted to maintaining the health of various aspects of the development workflow. We also have an onboarding team that helps new contributors get started with the project and a welfare team responsible for assisting new contributors. This wiki page explains the different teams in Oppia and their composition. From 16303d784627d84cd701b2d57a3840057afde1d9 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Thu, 17 Feb 2022 18:56:45 +0530 Subject: [PATCH 285/374] Added link to "teams at oppia androdi" page --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index ca8d6324408..6cd6decc0ac 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -3,6 +3,7 @@ * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|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** From bc292fa653f4eb1afa1a90788b53675b88b238b3 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:16:03 -0800 Subject: [PATCH 286/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index 6cd6decc0ac..a66b5da960d 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -40,6 +40,7 @@ * [[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]] * [[Developing skills|https://github.com/oppia/oppia-android/wiki/Developing-skills]] * [[Buf Guide|https://github.com/oppia/oppia-android/wiki/Buf-Guide]] * [[Firebase Console Guide|https://github.com/oppia/oppia-android/wiki/Firebase-Console-Guide]] From 88a543d1c79e7e64de4e9fd586f1697ba70b5545 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:16:26 -0800 Subject: [PATCH 287/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index a66b5da960d..0c8f513ce81 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -41,7 +41,6 @@ * [[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]] - * [[Developing skills|https://github.com/oppia/oppia-android/wiki/Developing-skills]] * [[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]] From c68a27ba4b51d1a1984868dd5062451fa360c66f Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:17:23 -0800 Subject: [PATCH 288/374] Created Dark Mode (markdown) --- Dark-Mode.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 Dark-Mode.md diff --git a/Dark-Mode.md b/Dark-Mode.md new file mode 100644 index 00000000000..a2c812827ba --- /dev/null +++ b/Dark-Mode.md @@ -0,0 +1,94 @@ +## Overview +This guide explains the newly adopted convention for using colors in oppia-android and adding support for dark mode +to any particular layout while keeping the code organised and strictly following the decided convention. + +The approach is to split color declarations in 4 different files instead of keeping the colors at one place, promoting separation of +concerns and hence improving code maintainability and understandability. + + + +#### Knowing the convention + +The following files have been added for maintaining the colors : +1. **`color_defs.xml`**
+ This file should strictly contain actual color names (irrespective of their intended use) with their hex color code declaration.
+ example:
+ > Don't + ```xml + #90EE90 + #90EE90 + #FF0000 + ``` + > Do + ```xml + #90EE90 + #0000FF + ``` + Declarations from this file should be only used in `color_palette.xml`. + +2. **`color_palette.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 + @color/light_black + @color/oppia_pink + ``` + >Do: + ```xml + @color/light_black + @color/oppia_pink + ``` + You can refer to both variations of these files to see how it separates the colors. +3. **`component_colors.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 + @color/primary_text_color + @color/toolbar_color + + @color/primary_text_color + @color/primary_text_color + @color/text_input_background_color + + @color/description_text_color + @color/background_color + + @color/primary_text_color + @color/dark_text_color + ``` +4. **`colors_migrating.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`* + + +

+visual representation of color hierarchy

+ +## Working with the layouts +Currently most of the layouts are directly referencing colors from `color_defs.xml`, they don't have separate colors for day and night mode. Our goal here is to make sure that views and layouts are using specified colors for day and night wherever applicable. + +You can refer to the design mocks for expected final result : [Dark Mode Mocks](https://xd.adobe.com/view/c05e9343-60f6-4c11-84ac-c756b75b940f-950d/grid/) + +#### How to acheive this goal? +Here is how I would go around working with any particular layout...
+ +- 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 *`__color`*. + +- Go through the mock for the concerned activity and note down which component of the app needs separate colors for day and night modes. The mock has provided hex color codes for all the elements in the UI, if any of the colors is not already present in the `color_defs.xml` then add it to the file with the actual color name. + +- Now, the newly defined colors in `component_colors.xml` should reference to something in `color_palette.xml`, define new colors in `color_palette.xml` based on general use case if not already defined. You will need to define same colors twice, in `values\color_palette.xml` as well as `values-night\color_palette.xml`. Both these declarations can be same as well, if there is no difference in the mocks for day and night mode. Make sure `color_palette.xml` is using colors from `color_defs.xml` only. + +Naming these colors can be bit tricky so it is suggested to take help from already exisitng colors in these files. + +In short, the general idea is to make sure layouts reference colors only from `component_colors.xml`, which is then referencing a version of `color_palette.xml` based on the active theme, making sure all the color declarations are as per the conventions decided for them. + +*Tip: Use layout Inspector to know more about targeted views.* + +### Running the app with dark mode +We suggest running the app on an API 30 Google Pixel emulator using the system-wide dark mode option from settings.
+ +Some other skins of android might force their own version of dark mode to screens not having dark mode support yet. From 4c6be7d9292d0324361f89bf47bea4df3b046031 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:18:10 -0800 Subject: [PATCH 289/374] Updated Dark Mode (markdown) --- Dark-Mode.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Dark-Mode.md b/Dark-Mode.md index a2c812827ba..493e8ca60bf 100644 --- a/Dark-Mode.md +++ b/Dark-Mode.md @@ -1,3 +1,5 @@ +_Credit: Thanks to **@ayush0402** for writing up this guide._ + ## Overview This guide explains the newly adopted convention for using colors in oppia-android and adding support for dark mode to any particular layout while keeping the code organised and strictly following the decided convention. From ffbdc84a71604e133b6bc06ccb63eb77f180fdfc Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:18:31 -0800 Subject: [PATCH 290/374] Updated Dark Mode (markdown) --- Dark-Mode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dark-Mode.md b/Dark-Mode.md index 493e8ca60bf..fddaa90bd32 100644 --- a/Dark-Mode.md +++ b/Dark-Mode.md @@ -1,4 +1,4 @@ -_Credit: Thanks to **@ayush0402** for writing up this guide._ +_Author credit: Thanks to **@ayush0402** for writing up this guide._ ## Overview This guide explains the newly adopted convention for using colors in oppia-android and adding support for dark mode From 343e2db2756a2a8008902c0880fea435a7731a9a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:18:54 -0800 Subject: [PATCH 291/374] Updated Dark Mode (markdown) --- Dark-Mode.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dark-Mode.md b/Dark-Mode.md index fddaa90bd32..352b6eaf6f3 100644 --- a/Dark-Mode.md +++ b/Dark-Mode.md @@ -1,4 +1,4 @@ -_Author credit: Thanks to **@ayush0402** for writing up this guide._ +_Author credit: Thanks to **@ayush0402** for writing up the initial version of this guide._ ## Overview This guide explains the newly adopted convention for using colors in oppia-android and adding support for dark mode From f196cad5e467a2b850a031c889a6293ad1dbfcca Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:19:26 -0800 Subject: [PATCH 292/374] Updated Contributing to Oppia android (markdown) --- Contributing-to-Oppia-android.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md index 07fbc39e9d8..04602c3dbfd 100644 --- a/Contributing-to-Oppia-android.md +++ b/Contributing-to-Oppia-android.md @@ -117,6 +117,7 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav **UI** - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) + - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode) -- see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode). **Bazel** From 1a4881171e22c05cda80bca5a646467262a33974 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:19:48 -0800 Subject: [PATCH 293/374] Updated Contributing to Oppia android (markdown) --- Contributing-to-Oppia-android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md index 04602c3dbfd..8c8f4e3495d 100644 --- a/Contributing-to-Oppia-android.md +++ b/Contributing-to-Oppia-android.md @@ -117,7 +117,7 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav **UI** - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode) -- see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode). + - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). **Bazel** From d3dab504634d2efddcfec7ae9311e1646d537caf Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:23:51 -0800 Subject: [PATCH 294/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 191 ++++++++++++++++++++++++++++++--- 1 file changed, 177 insertions(+), 14 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 1114cd86b18..bde10cac51f 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -1,6 +1,143 @@ -The following instructions will help you submit a PR effectively and in a clean way. Before going through this document, make sure you look at the instructions on the [wiki home page](https://github.com/oppia/oppia-android/wiki). +**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial to pull requests.](https://www.atlassian.com/git/tutorials/making-a-pull-request) -## Important Points +Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc.](https://github.com/oppia/oppia/wiki/Writing-design-docs) This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. + +To make code changes, please follow the following instructions carefully! Otherwise, your code review may be delayed. + - [Creating a pull request using the terminal](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-request-using-the-terminal) + - [Creating a pull request using android studio's UI based Github workflow](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-requeset-using-android-studios-ui-based-github-workflow) + +### Making a code change using the terminal + +**Step 1: Update your repository** +The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: +``` +git fetch upstream +git checkout develop +git merge upstream/develop +``` + +**Step 2: Create a new branch with a descriptive name** +Then create a new branch. In this example the branch is named `your-branch-name`. 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.` + +``` +git checkout -b your-branch-name +``` + +**Step 2: Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. + +You can change your most recent commit message using `git commit --amend`. + +*Note: It is difficult to change any commit messages other than your most recent one or messages on commits that have been pushed, so write your commit messages carefully!* + +Before making the commit, do some sanity-checks: +- Ensure that your code follows the style rules. +- Run robolectric and espresso tests to make sure you haven't broken anything! If you would to know more about testing on oppia-android check out [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) + + +Run git status to check that your changes are what you expect. To inspect the changes made to any particular file, use git diff your-file-name. + +Stage all your changes: +``` +git add . +``` +(`.` refers to your current directory) +To actually make the commit, run: + +``` +git commit -m "{{YOUR COMMIT MESSAGE HERE}}" +``` +*Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* + +**Step 3: Push changes to your GitHub fork** + +Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: + +Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. + +Use a tool like `git diff upstream/develop` 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 like debugging code. + +We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. + +When you're ready to push, run: +``` +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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. + +### Making a code change using android studio's UI based Github workflow + +**Step 1: Update your repository** +The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: + +On the bottom right side of your android studio screen you will find you branch name. + +Click on **branch_name** > **develop** > **Update** + +10 + +**Step 2: Create a new branch with a descriptive name** + +On the bottom right side of your android studio screen your branch. +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.` + +12 + + +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 + +11 + +**Step 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. + +5 + +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) + +8 + +Click on the green tick symbol to commit your files. + +9 + +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. + +13 + +**Step 4: Push changes to your GitHub fork** + +Now we need to Push the code changes to local branch(origin) and upstream(remote) +Right click **app > Git > Repository > Push** + +15 + +Your new branch needs to be added to both origin and upstream remote. +Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. + +16 + + +### Create a pull request + +Once your feature is ready, you can open a pull request (PR)! + +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. + + +### Important Points 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). @@ -8,24 +145,15 @@ The following instructions will help you submit a PR effectively and in a clean 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. -## Clarification regarding **Assignees** and **Reviewers** section. +### Clarification regarding **Assignees** and **Reviewers** section. 1. **Reviewers**: This section will be filled automatically by Oppia-Bot. Once this section is filled out, it generally should not change throughout the timeline of the PR. 2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More 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. -## Checklist before submitting a PR -Note: This checklist should be embedded in your every PR explanation with appropriate ticks. Please tick the relevant boxes by putting an "x" in them -- [ ] The PR title and explanation each start with "Fix #bugnum: " (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".) -- [ ] Any changes to [scripts/assets](https://github.com/oppia/oppia-android/tree/develop/scripts/assets) files have their rationale included in the PR explanation. -- [ ] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). -- [ ] The PR does not contain any unnecessary code changes from Android Studio ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#undo-unnecessary-changes)). -- [ ] The PR is made from a branch that's **not** called "develop" and is up-to-date with "develop". -- [ ] The PR is **assigned** to the appropriate reviewers ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#clarification-regarding-assignees-and-reviewers-section)). - -## Undo unnecessary changes +### 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: 1. Once you PR is created, go to `Files changed` section available on top of your pull request. For example: @@ -34,7 +162,42 @@ Sometimes android studio automatically makes changes to files based on your loca The `Files changed` section should contain only those changes which were done by you. -## Tips for getting your PR merged after submission + +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. + +### 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 in two ways: +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 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. + +2. 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 +git commit -a +git push origin new-branch-name + ``` + +Once you've finished addressing everything, and would like the reviewer to take another look, 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. + +### Tidy up! +After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository + +### Celebrate. :confetti_ball: +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. + + +### Tips for getting your PR merged after submission 1. Keep track of **Assignees** section and reply to comments in the PR itself. 2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. 3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. From dc1fd2c0a762be009705f7c561785b6dd9b11cdd Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:23:55 -0800 Subject: [PATCH 295/374] Destroyed Making a code change (markdown) --- Making-a-code-change.md | 206 ---------------------------------------- 1 file changed, 206 deletions(-) delete mode 100644 Making-a-code-change.md diff --git a/Making-a-code-change.md b/Making-a-code-change.md deleted file mode 100644 index bde10cac51f..00000000000 --- a/Making-a-code-change.md +++ /dev/null @@ -1,206 +0,0 @@ -**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial to pull requests.](https://www.atlassian.com/git/tutorials/making-a-pull-request) - -Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc.](https://github.com/oppia/oppia/wiki/Writing-design-docs) This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. - -To make code changes, please follow the following instructions carefully! Otherwise, your code review may be delayed. - - [Creating a pull request using the terminal](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-request-using-the-terminal) - - [Creating a pull request using android studio's UI based Github workflow](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-requeset-using-android-studios-ui-based-github-workflow) - -### Making a code change using the terminal - -**Step 1: Update your repository** -The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: -``` -git fetch upstream -git checkout develop -git merge upstream/develop -``` - -**Step 2: Create a new branch with a descriptive name** -Then create a new branch. In this example the branch is named `your-branch-name`. 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.` - -``` -git checkout -b your-branch-name -``` - -**Step 2: Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. - -You can change your most recent commit message using `git commit --amend`. - -*Note: It is difficult to change any commit messages other than your most recent one or messages on commits that have been pushed, so write your commit messages carefully!* - -Before making the commit, do some sanity-checks: -- Ensure that your code follows the style rules. -- Run robolectric and espresso tests to make sure you haven't broken anything! If you would to know more about testing on oppia-android check out [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) - - -Run git status to check that your changes are what you expect. To inspect the changes made to any particular file, use git diff your-file-name. - -Stage all your changes: -``` -git add . -``` -(`.` refers to your current directory) -To actually make the commit, run: - -``` -git commit -m "{{YOUR COMMIT MESSAGE HERE}}" -``` -*Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* - -**Step 3: Push changes to your GitHub fork** - -Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: - -Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. - -Use a tool like `git diff upstream/develop` 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 like debugging code. - -We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. - -When you're ready to push, run: -``` -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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. - -### Making a code change using android studio's UI based Github workflow - -**Step 1: Update your repository** -The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: - -On the bottom right side of your android studio screen you will find you branch name. - -Click on **branch_name** > **develop** > **Update** - -10 - -**Step 2: Create a new branch with a descriptive name** - -On the bottom right side of your android studio screen your branch. -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.` - -12 - - -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 - -11 - -**Step 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. - -5 - -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) - -8 - -Click on the green tick symbol to commit your files. - -9 - -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. - -13 - -**Step 4: Push changes to your GitHub fork** - -Now we need to Push the code changes to local branch(origin) and upstream(remote) -Right click **app > Git > Repository > Push** - -15 - -Your new branch needs to be added to both origin and upstream remote. -Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. - -16 - - -### Create a pull request - -Once your feature is ready, you can open a pull request (PR)! - -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. - - -### Important Points - -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. - -### Clarification regarding **Assignees** and **Reviewers** section. -1. **Reviewers**: This section will be filled automatically by Oppia-Bot. Once this section is filled out, it generally should not change throughout the timeline of the PR. -2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More 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. - - -### 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: -1. Once you PR is created, go to `Files changed` section available on top of your pull request. For example: - - -2. Now 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. - - - -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. - -### 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 in two ways: -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 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. - -2. 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 -git commit -a -git push origin new-branch-name - ``` - -Once you've finished addressing everything, and would like the reviewer to take another look, 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. - -### Tidy up! -After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository - -### Celebrate. :confetti_ball: -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. - - -### Tips for getting your PR merged after submission -1. Keep track of **Assignees** section and reply to comments in the PR itself. -2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. -3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. -4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). -5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. -6. 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. \ No newline at end of file From 6f409d0b196716e472696ed362a16e9f2a1f0fe2 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:24:06 -0800 Subject: [PATCH 296/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 0c8f513ce81..e3f04c66d5b 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -16,7 +16,6 @@ * [[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 - * [[Making a code change|https://github.com/oppia/oppia-android/wiki/making-a-code-change]] * [[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]] From a9091d31862542e06908721b3af8ed41e5725ca5 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:24:39 -0800 Subject: [PATCH 297/374] Updated Contributing to Oppia android (markdown) --- Contributing-to-Oppia-android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md index 8c8f4e3495d..f708002ca6d 100644 --- a/Contributing-to-Oppia-android.md +++ b/Contributing-to-Oppia-android.md @@ -112,7 +112,7 @@ For now, you generally won't need to do this, until the Android app supports on- ## Finding something to do **Starter projects for new contributors** -Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. After that, we’d strongly recommend tackling some part of one of the following starter issues. +Welcome! Please make sure to follow the onboarding instructions above if you haven’t already, and also read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). After that, we’d strongly recommend tackling some part of one of the following starter issues. **UI** From 97bbf6dab16d91623f8ce061ddc80c975dd99f75 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:39:38 -0800 Subject: [PATCH 298/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 77 +++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 30 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index bde10cac51f..cc1a2775f2b 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -1,12 +1,12 @@ -**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial to pull requests.](https://www.atlassian.com/git/tutorials/making-a-pull-request) +**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial on pull requests](https://www.atlassian.com/git/tutorials/making-a-pull-request). -Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc.](https://github.com/oppia/oppia/wiki/Writing-design-docs) This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. +Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. -To make code changes, please follow the following instructions carefully! Otherwise, your code review may be delayed. - - [Creating a pull request using the terminal](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-request-using-the-terminal) - - [Creating a pull request using android studio's UI based Github workflow](https://gist.github.com/MaskedCarrot/6ebb2d3b6c3e4870d8d2cb92eef4d52b#creating-a-pull-requeset-using-android-studios-ui-based-github-workflow) +Before you make a PR, you'll need to make and test the changes locally. To do this, please follow the following instructions carefully! Otherwise, your code review may be delayed. + - [Making a local code change using the terminal](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#making-a-local-code-change-using-the-terminal) + - [Making a local code change using Android Studio's UI-based Github workflow](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#making-a-local-code-change-using-android-studios-ui-based-github-workflow) -### Making a code change using the terminal +### Making a local code change using the terminal **Step 1: Update your repository** The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: @@ -23,7 +23,7 @@ Then create a new branch. In this example the branch is named `your-branch-name` git checkout -b your-branch-name ``` -**Step 2: Make commits locally to your feature branch** +**Step 3: Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. @@ -51,13 +51,13 @@ git commit -m "{{YOUR COMMIT MESSAGE HERE}}" ``` *Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* -**Step 3: Push changes to your GitHub fork** +**Step 4: Push changes to your GitHub fork** Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: -Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. +- Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. -Use a tool like `git diff upstream/develop` 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 like debugging code. +- Use a tool like `git diff upstream/develop` 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 like debugging code. We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. @@ -67,7 +67,7 @@ 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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. -### Making a code change using android studio's UI based Github workflow +### Making a local code change using Android Studio's UI-based Github workflow **Step 1: Update your repository** The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: @@ -130,49 +130,44 @@ Once your feature is ready, you can open a pull request (PR)! 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. +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 +### 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. +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 will be filled automatically by Oppia-Bot. Once this section is filled out, it generally should not change throughout the timeline of the PR. -2. **Assignees**: The Assignees field indicates the person(s) who the PR is currently blocked on. More specifically: +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. -### 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: -1. Once you PR is created, go to `Files changed` section available on top of your pull request. For example: - - -2. Now 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. - - - -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. ### 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 in two ways: 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 will delay your review, because it overwrites history on GitHub and makes the incremental changes harder to review. + - **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. - 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. + 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. 2. Resolve any merge conflicts that arise. To resolve conflicts between ‘new-branch-name’ (in your fork) and ‘develop’ (in the oppia repository), run: @@ -188,6 +183,28 @@ Once you've finished addressing everything, and would like the reviewer to take At the end, the reviewer will merge the pull request. +### 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. + +!["Pull Changes" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797367-bf8cbefd-c6da-4a82-8210-806d70411b05.png) + +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. + +!["Conflicts" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797370-2d4d7d6c-42c4-4581-a83e-fcce727d5d70.png) + +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. + +!["Conflicts diff" window in Android Studio](https://user-images.githubusercontent.com/10575562/154797371-9e2596ab-ad0c-4fa3-93ca-6e874528bb99.png) + + +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. + + ### Tidy up! After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository From edd146dc8acf71a52201b271c450f03c10db7f4a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:47:47 -0800 Subject: [PATCH 299/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 57 +++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 22 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index cc1a2775f2b..1dbd85c1652 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -1,6 +1,16 @@ -**Working on your first pull request?** Pull requests can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out the free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) or [Atlassian's tutorial on pull requests](https://www.atlassian.com/git/tutorials/making-a-pull-request). +**Working on your first pull request?** Pull requests (PRs) can be tricky to understand at first, so if the instructions on this page don't make sense to you, check out these resources: +- The free series [How to Contribute to an Open Source Project on GitHub](https://app.egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) +- [Atlassian's tutorial on pull requests](https://www.atlassian.com/git/tutorials/making-a-pull-request). -Note: If your change involves more than around 500 lines of code, we recommend first creating a short [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. +Here are the steps for making a PR to the Oppia Android codebase: +1. [Make a local code change](#making-a-local-code-change) +2. [Create a PR on GitHub](#create-a-pull-request) +3. [Address review comments until all reviewers give LGTM]((#address-review-comments-until-all-reviewers-give-lgtm)) +4. [Tidy up and celebrate!](#tidy-up) + +Note: If your change involves more than around 500 lines of code, we recommend first creating a [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. + +## Making a local code change Before you make a PR, you'll need to make and test the changes locally. To do this, please follow the following instructions carefully! Otherwise, your code review may be delayed. - [Making a local code change using the terminal](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#making-a-local-code-change-using-the-terminal) @@ -124,7 +134,7 @@ Once you push a branch to Git you wont be able to rename it so, be sure about th 16 -### Create a pull request +## Create a pull request Once your feature is ready, you can open a pull request (PR)! @@ -160,7 +170,7 @@ You have successfully created a pull request! Now, wait for your code to get rev -### Address review comments until all reviewers give LGTM +## 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 in two ways: 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)".) @@ -169,7 +179,25 @@ When your reviewer has reviewed the code, you'll get an email. You'll need to re 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. -2. Resolve any merge conflicts that arise. To resolve conflicts between ‘new-branch-name’ (in your fork) and ‘develop’ (in the oppia repository), run: +2. Resolve any merge conflicts that arise 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.) + +Once you've finished addressing everything, and would like the reviewer to take another look, 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. + + +### Tips for getting your PR merged after submission +1. Keep track of **Assignees** section and reply to comments in the PR itself. +2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. +3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. +4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). +5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. +6. 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. + + +### 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 @@ -179,10 +207,6 @@ git commit -a git push origin new-branch-name ``` -Once you've finished addressing everything, and would like the reviewer to take another look, 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. - ### 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. @@ -205,19 +229,8 @@ You can either directly accept the changes from develop (discarding your local c 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. -### Tidy up! -After the PR status has changed to "Merged", delete the feature branch from both your local clone and the GitHub repository - -### Celebrate. :confetti_ball: -Congratulations, you have contributed to the Oppia Android project! +## 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. - -### Tips for getting your PR merged after submission -1. Keep track of **Assignees** section and reply to comments in the PR itself. -2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. -3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. -4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). -5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. -6. 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. \ No newline at end of file From ff32566113c127229acde1944602fdd12483db91 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:51:21 -0800 Subject: [PATCH 300/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 1dbd85c1652..7fb318f34d0 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -4,8 +4,8 @@ Here are the steps for making a PR to the Oppia Android codebase: 1. [Make a local code change](#making-a-local-code-change) -2. [Create a PR on GitHub](#create-a-pull-request) -3. [Address review comments until all reviewers give LGTM]((#address-review-comments-until-all-reviewers-give-lgtm)) +2. [Create a PR on GitHub](#create-a-pr-on-github) +3. [Address review comments until all reviewers give LGTM](#address-review-comments-until-all-reviewers-give-lgtm) 4. [Tidy up and celebrate!](#tidy-up) Note: If your change involves more than around 500 lines of code, we recommend first creating a [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. @@ -134,7 +134,7 @@ Once you push a branch to Git you wont be able to rename it so, be sure about th 16 -## Create a pull request +## Create a PR on GitHub Once your feature is ready, you can open a pull request (PR)! @@ -186,7 +186,7 @@ Once you've finished addressing everything, and would like the reviewer to take At the end, the reviewer will merge the pull request. -### Tips for getting your PR merged after submission +### Tips for getting your PR merged 1. Keep track of **Assignees** section and reply to comments in the PR itself. 2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. 3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. From 7c38951c1ed029b4b711afcff8861495d6b2a0dc Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 02:57:25 -0800 Subject: [PATCH 301/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 127 ++++++++++++++------------------- 1 file changed, 52 insertions(+), 75 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 7fb318f34d0..44460eb216e 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -10,7 +10,7 @@ Here are the steps for making a PR to the Oppia Android codebase: Note: If your change involves more than around 500 lines of code, we recommend first creating a [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. -## Making a local code change +## Step 1: Making a local code change Before you make a PR, you'll need to make and test the changes locally. To do this, please follow the following instructions carefully! Otherwise, your code review may be delayed. - [Making a local code change using the terminal](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#making-a-local-code-change-using-the-terminal) @@ -18,123 +18,100 @@ Before you make a PR, you'll need to make and test the changes locally. To do th ### Making a local code change using the terminal -**Step 1: Update your repository** -The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: +1. **Update your repository.** The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: + ``` -git fetch upstream -git checkout develop -git merge upstream/develop + git fetch upstream + git checkout develop + git merge upstream/develop ``` -**Step 2: Create a new branch with a descriptive name** -Then create a new branch. In this example the branch is named `your-branch-name`. 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.` +2. **Create a new branch with a descriptive name.** In the example below, the branch is named `your-branch-name`. 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.` ``` -git checkout -b your-branch-name + git checkout -b your-branch-name ``` -**Step 3: Make commits locally 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. +3. **Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. -However, do not write "Fix #ISSUE_NUMBER" (e.g. "Fix #99999") in your commit messages (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. + You can change your most recent commit message using `git commit --amend`. *Note: It is difficult to change any commit messages other than your most recent one or messages on commits that have been pushed, so write your commit messages carefully!* -You can change your most recent commit message using `git commit --amend`. + Before making the commit, do some sanity-checks: + - Ensure that your code follows the style rules. + - Run robolectric and espresso tests to make sure you haven't broken anything! If you would to know more about testing on oppia-android, check out [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) + - Run git status to check that your changes are what you expect. To inspect the changes made to any particular file, use git diff your-file-name. -*Note: It is difficult to change any commit messages other than your most recent one or messages on commits that have been pushed, so write your commit messages carefully!* + Stage all your changes (the `.` at the end refers to your current directory): -Before making the commit, do some sanity-checks: -- Ensure that your code follows the style rules. -- Run robolectric and espresso tests to make sure you haven't broken anything! If you would to know more about testing on oppia-android check out [Oppia Android Testing](https://github.com/oppia/oppia-android/wiki/Oppia-Android-Testing) + ``` + git add . + ``` + To actually make the commit, run: -Run git status to check that your changes are what you expect. To inspect the changes made to any particular file, use git diff your-file-name. - -Stage all your changes: -``` -git add . -``` -(`.` refers to your current directory) -To actually make the commit, run: - -``` -git commit -m "{{YOUR COMMIT MESSAGE HERE}}" -``` -*Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* + ``` + git commit -m "{{YOUR COMMIT MESSAGE HERE}}" + ``` -**Step 4: Push changes to your GitHub fork** + *Note: There is no maximum or minimum number of commits required in a PR. Instead of aiming for a certain number, you should try to make each commit a logical "chunk" of work. There are many opinions about how big commits should be, but a useful rule of thumb is that you should be able to read the first lines of all your commit messages to get a good idea of what you changed. If you find yourself needing lots of clauses to capture what you changed, your commit is probably too big.* -Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: +4. **Push changes to your GitHub fork.** Before pushing, make sure to check the following things, otherwise you will incur delays with the review process or the automated checks: + - Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. + - Use a tool like `git diff upstream/develop` 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 like debugging code. -- Do some manual testing on your local instance of Oppia to check that you haven't broken anything. This is important to avoid breakages. + We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. -- Use a tool like `git diff upstream/develop` 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 like debugging code. + When you're ready to push, run: + ``` + git push origin {{YOUR BRANCH NAME}} + ``` -We don't allow force-pushing at Oppia, so once you push your commits, you can't change them. You can still add new commits though. - -When you're ready to push, run: -``` -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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. + 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, read the failure messages and fix the issues by making a new commit (see step 3), then repeat the previous instructions to retry the push. Do not bypass these presubmit checks! The checks get run on your PR too, so if you bypass failures on your local machine, you'll just have to fix them later when they fail on the PR. ### Making a local code change using Android Studio's UI-based Github workflow -**Step 1: Update your repository** -The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: - -On the bottom right side of your android studio screen you will find you branch name. +1. **Update your repository.** The new branch should be based on the latest code in develop, so checkout the latest version of develop, like this: -Click on **branch_name** > **develop** > **Update** + On the bottom right side of your android studio screen you will find your branch name. Click on **branch_name** > **develop** > **Update**: 10 -**Step 2: Create a new branch with a descriptive name** +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**. -On the bottom right side of your android studio screen your branch. -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.` + 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.` 12 - -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 + 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: 11 -**Step 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. - -5 +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) + 5 -8 + 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. + 8 -9 + 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. + 9 -13 + 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. -**Step 4: Push changes to your GitHub fork** + 13 -Now we need to Push the code changes to local branch(origin) and upstream(remote) -Right click **app > Git > Repository > Push** +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**: -15 + 15 -Your new branch needs to be added to both origin and upstream remote. -Once you push a branch to Git you wont be able to rename it so, be sure about the naming before pushing. + 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: -16 + 16 -## Create a PR on GitHub +## Step 2: Create a PR on GitHub Once your feature is ready, you can open a pull request (PR)! @@ -170,7 +147,7 @@ You have successfully created a pull request! Now, wait for your code to get rev -## Address review comments until all reviewers give LGTM +## 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 in two ways: 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)".) @@ -229,7 +206,7 @@ You can either directly accept the changes from develop (discarding your local c 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. -## Tidy up and celebrate! :confetti_ball: +## 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. From 46ee9706070845810a85919e3df4d2e3c88b382c Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 03:00:04 -0800 Subject: [PATCH 302/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 43 +++++++++++++++++----------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 44460eb216e..f9bff2bba59 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -3,10 +3,10 @@ - [Atlassian's tutorial on pull requests](https://www.atlassian.com/git/tutorials/making-a-pull-request). Here are the steps for making a PR to the Oppia Android codebase: -1. [Make a local code change](#making-a-local-code-change) -2. [Create a PR on GitHub](#create-a-pr-on-github) -3. [Address review comments until all reviewers give LGTM](#address-review-comments-until-all-reviewers-give-lgtm) -4. [Tidy up and celebrate!](#tidy-up) +1. [Make a local code change](#step-1-making-a-local-code-change) +2. [Create a PR on GitHub](#step-2-create-a-pr-on-github) +3. [Address review comments until all reviewers give LGTM](#step-3-address-review-comments-until-all-reviewers-give-lgtm) +4. [Tidy up and celebrate!](#step-4-tidy-up-and-celebrate-confetti_ball) Note: If your change involves more than around 500 lines of code, we recommend first creating a [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. @@ -20,17 +20,17 @@ Before you make a PR, you'll need to make and test the changes locally. To do th 1. **Update your repository.** The new branch should be based on the latest code in develop, so checkout the latest version of develop like this: -``` - git fetch upstream - git checkout develop - git merge upstream/develop -``` + ``` + git fetch upstream + git checkout develop + git merge upstream/develop + ``` 2. **Create a new branch with a descriptive name.** In the example below, the branch is named `your-branch-name`. 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.` -``` - git checkout -b your-branch-name -``` + ``` + git checkout -b your-branch-name + ``` 3. **Make commits locally 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 (or any of the other closing phrases from GitHub's documentation), as this will cause Github to close the original issue automatically. @@ -74,17 +74,17 @@ Before you make a PR, you'll need to make and test the changes locally. To do th On the bottom right side of your android studio screen you will find your branch name. Click on **branch_name** > **develop** > **Update**: -10 + 10 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.` -12 + 12 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: -11 + 11 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. @@ -192,18 +192,17 @@ You can use Android Studio to resolve merge conflicts through its UI-based Git f - 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. -!["Pull Changes" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797367-bf8cbefd-c6da-4a82-8210-806d70411b05.png) - -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. + !["Pull Changes" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797367-bf8cbefd-c6da-4a82-8210-806d70411b05.png) -!["Conflicts" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797370-2d4d7d6c-42c4-4581-a83e-fcce727d5d70.png) +- 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. + !["Conflicts" dialog box in Android Studio](https://user-images.githubusercontent.com/10575562/154797370-2d4d7d6c-42c4-4581-a83e-fcce727d5d70.png) -!["Conflicts diff" window in Android Studio](https://user-images.githubusercontent.com/10575562/154797371-9e2596ab-ad0c-4fa3-93ca-6e874528bb99.png) +- 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. + !["Conflicts diff" window in Android Studio](https://user-images.githubusercontent.com/10575562/154797371-9e2596ab-ad0c-4fa3-93ca-6e874528bb99.png) -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. + 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: From 24ec00d2a5f7934bccf2f3f7b03212f7a45a9c25 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Sat, 19 Feb 2022 03:01:49 -0800 Subject: [PATCH 303/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index f9bff2bba59..d959b924447 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -113,13 +113,11 @@ Before you make a PR, you'll need to make and test the changes locally. To do th ## Step 2: Create a PR on GitHub -Once your feature is ready, you can open a pull request (PR)! +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". +- 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. @@ -132,9 +130,9 @@ You have successfully created a pull request! Now, wait for your code to get rev - 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: +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. @@ -164,8 +162,8 @@ At the end, the reviewer will merge the pull request. ### Tips for getting your PR merged -1. Keep track of **Assignees** section and reply to comments in the PR itself. -2. PRs should not be merged if there are any requested changes, or if there are any unresolved conversation threads. +1. Keep track of the **Assignees** section, and reply to comments in the PR itself. +2. PRs will not be merged if there are any requested changes, or if there are any unresolved conversation threads. 3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. 4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). 5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. From 5efdb98e3a5db20349c1766bcbfdd0c6af4d07bf Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Mon, 21 Feb 2022 22:03:24 +0530 Subject: [PATCH 304/374] Typo: `Guile` to `Guide` --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index e3f04c66d5b..71074b2c4c9 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -34,7 +34,7 @@ * [[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 Guile|https://github.com/oppia/oppia-android/wiki/Accessibility-(A11y)-Guide]] + * [[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]] From 55e72414f7386a0fdb14ef068e6a09cd2ef995df Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Wed, 23 Feb 2022 07:37:43 -0800 Subject: [PATCH 305/374] Updated Teams at oppia android (markdown) --- Teams-at-oppia-android.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Teams-at-oppia-android.md b/Teams-at-oppia-android.md index 3dfbaff0afb..a1d9a0f64ff 100644 --- a/Teams-at-oppia-android.md +++ b/Teams-at-oppia-android.md @@ -2,11 +2,11 @@ The Oppia team is a distributed team of contributors from all over the world. To This wiki page explains the different teams in Oppia and their composition. -### Clam Team +### CLaM Team -CLAM team is responsible for most of the UI based code (app-layer), which includes exploration player, question player, concept-card, subtopics, topics, etc. All these user-facing features must be RTL supportive, accessible by all and should work on all devices (mobile + tablet). +CLaM team is responsible for most of the UI based code (app-layer), which includes exploration player, question player, concept-card, subtopics, topics, etc. All these user-facing features must be RTL supportive, accessible by all and should work on all devices (mobile + tablet). -**Team contact:** Rajat Talesra (@rt4914) (lead), Yash Verma (@yash10019coder) +**Team contact:** Rajat Talesra (@rt4914) (lead), Ayush Kumar (@ayush0402), Yash Verma (@yash10019coder) ### Dev-workflow Team The dev-workflow team ensures that the Oppia development process is smooth, stable and enjoyable, by ensuring that the following always hold: From c0bdd66f56e67bcdf93a47512423cb23f92f752d Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 24 Feb 2022 07:43:07 -0800 Subject: [PATCH 306/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 71074b2c4c9..5846aaaf373 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -3,7 +3,7 @@ * [Code of Conduct](https://github.com/oppia/oppia-android/blob/develop/.github/CODE_OF_CONDUCT.md) * **[[Get involved!|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) + * [Teams at Oppia Android](https://github.com/oppia/oppia-android/wiki/Teams-at-oppia-android) --- **Developing Oppia** From e728f8db9e384a4625191f72c9fd1f2482808c5f Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 24 Feb 2022 07:43:45 -0800 Subject: [PATCH 307/374] Updated Teams at oppia android (markdown) --- Teams-at-oppia-android.md => Teams-at-Oppia-Android.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Teams-at-oppia-android.md => Teams-at-Oppia-Android.md (100%) diff --git a/Teams-at-oppia-android.md b/Teams-at-Oppia-Android.md similarity index 100% rename from Teams-at-oppia-android.md rename to Teams-at-Oppia-Android.md From 6d9f7d5336e8dfebe9bdeac58b242b1fcf321717 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Tue, 1 Mar 2022 22:47:20 +0530 Subject: [PATCH 308/374] Added mock links --- Working-on-UI.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Working-on-UI.md b/Working-on-UI.md index 5371cb7c97d..ca5afa02e72 100644 --- a/Working-on-UI.md +++ b/Working-on-UI.md @@ -1,5 +1,9 @@ Oppia-Android app mocks have been prepared on AdobeXD and the mocks have a version associated with them which is displayed on the bottom right corner of the "SplashScreen" page in mocks. Before working on any UI issue make sure that you have latest link of the mock associated with that UI. +- [Mobile Portrait](https://xd.adobe.com/view/3dca36c2-5115-419c-b25e-0f10526b077c-6899/grid/) +- [Mobile Landscape](https://xd.adobe.com/view/ee9e607b-dbd6-4372-48dc-b687d32af3da-98af/grid/) +- [Tablet](https://xd.adobe.com/view/d405de00-a871-4f0f-73a0-f8acef30349b-a234/grid/) + # Understanding the Mock Link: For understanding the mocks let's take one example. Open [Admin Auth Mock Link](https://xd.adobe.com/view/0687f00c-695b-437a-79a6-688e7f4f7552-70b6/screen/a841330e-efe5-4bdb-acdd-4d6e52a59571/PC-MP-Admin-Authorization-Add-Profile-Empty-) From 5e3fde7ecc390d37240346db199743561cea7bd4 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Wed, 16 Mar 2022 23:16:27 -0700 Subject: [PATCH 309/374] Updated Contributing to Oppia android (markdown) --- Contributing-to-Oppia-android.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-android.md index f708002ca6d..81eea468eaf 100644 --- a/Contributing-to-Oppia-android.md +++ b/Contributing-to-Oppia-android.md @@ -114,6 +114,10 @@ For now, you generally won't need to do this, until the Android app supports on- Welcome! Please make sure to follow the onboarding instructions above if you haven’t already, and also read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). After that, we’d strongly recommend tackling some part of one of the following starter issues. +**Testing** + + - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) + **UI** - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) @@ -125,9 +129,6 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) -**Testing** - - - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) ## Communication channels From d3cf8ca68e74fa2951d406ecd13672cfc7ae7c64 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 21 Mar 2022 13:58:11 -0700 Subject: [PATCH 310/374] Updated Contributing to Oppia android (markdown) --- ...buting-to-Oppia-android.md => Contributing-to-Oppia-Android.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Contributing-to-Oppia-android.md => Contributing-to-Oppia-Android.md (100%) diff --git a/Contributing-to-Oppia-android.md b/Contributing-to-Oppia-Android.md similarity index 100% rename from Contributing-to-Oppia-android.md rename to Contributing-to-Oppia-Android.md From e0e2b63e7802db5a2ee5ecdac285281a91367405 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Fri, 15 Apr 2022 21:58:42 +0530 Subject: [PATCH 311/374] Updated Home (markdown) --- Home.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Home.md b/Home.md index ceb75aa2c71..12a255ac1ef 100644 --- a/Home.md +++ b/Home.md @@ -1,11 +1,13 @@ -Thanks for your interest in contributing to the Oppia project, and making it easier for students to learn online in an effective and enjoyable way! +Thanks for your interest in contributing to the Oppia project and making it easier for students to learn online effectively and enjoyably! -There are lots of 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 if you're 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 around the world to learn things better, and that you're responsible and reliable. +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 of the different ways to help out. Please feel free to take a look through them, and see if any interest you: +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 take a look at the [oppia/oppia repository](https://github.com/oppia/oppia). +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). -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! +If you run into any problems, you can check out the [user documentation](https://oppia.github.io/#/) or post it to our [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-dev). Feel free to drop into our [Gitter](https://gitter.im/oppia/oppia-android) chat channel to say hello, too :) + +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! From 4ea21638f74cfd365ebac729af304476229a103d Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 19 Apr 2022 10:10:04 -0700 Subject: [PATCH 312/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index 12a255ac1ef..b2dc979e465 100644 --- a/Home.md +++ b/Home.md @@ -8,6 +8,6 @@ To make it easier to get started, we've catalogued some different ways to help o 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 check out the [user documentation](https://oppia.github.io/#/) or post it to our [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-dev). Feel free to drop into our [Gitter](https://gitter.im/oppia/oppia-android) chat channel to say hello, too :) +If you run into any problems, you can check out the [user documentation](https://oppia.github.io/#/) or post to our [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-dev). Feel free to drop into our [Gitter](https://gitter.im/oppia/oppia-android) chat channel to say hello, too :) 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! From f0b759882c437fb67a3fd3fd8d7f05917970cf54 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 19 Apr 2022 10:12:34 -0700 Subject: [PATCH 313/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 81eea468eaf..639f8d2d50a 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -11,7 +11,6 @@ Thanks for your interest in contributing to the Oppia Android project, and makin * [Finding something to do](#finding-something-to-do) * [Communication channels](#communication-channels) - ## Onboarding instructions If you'd like to help out with the Android project, please follow the following steps to get started: @@ -135,3 +134,5 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav ### Mailing lists We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! + +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). \ No newline at end of file From f35321ab7ec5414bd18dcad2c90ad679bafbea9d Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 19 Apr 2022 10:12:52 -0700 Subject: [PATCH 314/374] Updated Home (markdown) --- Home.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Home.md b/Home.md index b2dc979e465..3b915b6cc45 100644 --- a/Home.md +++ b/Home.md @@ -8,6 +8,6 @@ To make it easier to get started, we've catalogued some different ways to help o 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 check out the [user documentation](https://oppia.github.io/#/) or post to our [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-dev). Feel free to drop into our [Gitter](https://gitter.im/oppia/oppia-android) chat channel to say hello, too :) +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! From 7c1aa0574c06fdada8a2afd615530cf8a357d536 Mon Sep 17 00:00:00 2001 From: Apoorv Srivastava <53645584+MaskedCarrot@users.noreply.github.com> Date: Tue, 10 May 2022 23:45:50 +0530 Subject: [PATCH 315/374] Updated Overview of the Oppia Android codebase and architecture (markdown) --- ...Oppia-Android-codebase-and-architecture.md | 250 ++++++++++++------ 1 file changed, 170 insertions(+), 80 deletions(-) diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/Overview-of-the-Oppia-Android-codebase-and-architecture.md index f16dcb1ba09..86c3c9f0445 100644 --- a/Overview-of-the-Oppia-Android-codebase-and-architecture.md +++ b/Overview-of-the-Oppia-Android-codebase-and-architecture.md @@ -1,96 +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) and [MVVM](https://medium.com/upday-devs/android-architecture-patterns-part-3-model-view-viewmodel-e7eeee76b73b) (Model-View-ViewModel). +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 -# Directory Structure Screenshot 2020-01-13 at 1 21 25 PM + 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/hermetic end-to-end tests using Espresso. Here are the contents of its 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/home** - Fragments, activities, view models, adapters, presenters and interfaces associated with the home screen. -* **app/mydownloads** - Fragments, activities, view models, adapters, presenters and interfaces associated with the "My Downloads" screen. -* **app/parser** - Various classes which parse strings to other data types (e.g. String to Fraction). -* **app/player** - Everything related to the exploration player (e.g. audio, state, etc.). -* **app/profile** - Fragments, activities, view models, adapters, presenters and interfaces for the profile screen and related subscreens. -* **app/recyclerview** - Helper classes for RecyclerView, which is used in various activities and fragments. -* **app/settings** - Fragments, activities, view models, adapters, presenters and interfaces related to the Settings screen and related subscreens. -* **app/splash** - Code related to the app's Splash screen. -* **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/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. - -### 2. data: -This module provides data to the application by fetching data from the Oppia backend, or by fetching data from an offline PersistenceCacheStore. This module is unit-tested with a combination of JUnit and Robolectric. Here are the contents of its subdirectories: - -* **data/backends** - APIs and models which are needed to make a data request to the Oppia backend, and convert that response to appropriate models. -* **data/persistence** - Information pertaining to the offline store is saved here using [PersistenceCacheStore](https://medium.com/@appmattus/caching-made-simple-on-android-d6e024e3726b) - -### 3. domain: -This module contains the business logic of the application, including both frontend controller and business service logic. It is a Java/Kotlin library without Android components, and it is unit-tested using raw JUnit tests. Its subdirectories are as follows: - -* **domain/audio** - Business logic for playing audio in the app. -* **domain/classify** - Classes responsible for classifying user answers to a specific outcome based on Oppia's interaction rule engine. -* **domain/exploration** - Controller for loading explorations, managing states and playing with exploration. -* **domain/profile** - Controller for retrieving, adding, updating, and deleting profiles. -* **domain/question** - Controller for retrieving a set of questions in the app's Practice Mode. -* **domain/topic** - Controller for retrieving all aspects of a topic and topic list, together with the user's progress. -* **domain/util** - Utility with different extension functions and classes to create models from JSON-encoded strings (e.g. `createStateFromJson`). - -### 4. model: -This library contains all `protos` used in the app. It only contains data definitions, so no tests are included. - -### 5. utility: -This is a Java/Kotlin module without Android dependencies. It contains utilities that all other modules may depend on. It also includes JUnit test cases. Its subdirectories are as follows: - -* **utility/caching** - A generic repository for access local APK asset files, and downloading remote binary files. This repository aims to centralize caching management of external asset files to simplify downstream code, and allow assets to be retrieved quickly and synchronously. -* **utility/data** - Various classes which help with effectively fetching locally-stored data in the domain layer. -* **utility/extensions** - Extensions for Android classes (e.g. LiveData). -* **utility/gcsresource** - Provides the default name of the GCS Resource bucket. -* **utility/logging** - Oppia-Android does not use [Log](https://developer.android.com/reference/android/util/Log). Instead, it has a custom Logger, which is a wrapper class for Android Logcat and file logging. **All** logs in this project should use `Logger` instead of `Log`. -* **utility/networking** - A utility to get the current connection status of the device. -* **utility/parser** - Rich-text parsers (e.g. HtmlParser, UrlParser) which ensure that the rich-text from the Oppia backend is parsed correctly in order to display it properly in the Android app. -* **utility/profile** - A utility to manage creation and deletion of directories. -* **utility/threading** - A utility which contains thread-safe enqueue and dequeue methods. - -# App Architecture +#### 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/**. For example, the subdirectory **app/resumeLesson** contains all the activities, fragments, interfaces and ViewModels used by the resume lesson screen. + +#### 2. data + +This module provides data to the application by fetching data from the Oppia backend. This module is unit-tested with a combination of JUnit and Robolectric. Here are the contents of its subdirectories: + +- **data/backends** - APIs and models needed to make a data request to the Oppia backend, and convert that response to appropriate models. +- **data/persistence** - Provides offline storage persistence support via [PersistenceCacheStore](https://github.com/oppia/oppia-android/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache#persistentcachestore%20i) + +#### 3. domain + +This module contains the application's business logic, including both front-end controller and business service logic. It is a Java/Kotlin library without Android components, and it is unit-tested using robolectric tests. This module generally follows the naming convention ****. Some important subdirectories for this module are listed below: + +- **domain/audio** - Business logic for playing audio in the app. +- **domain/classify** - Classes responsible for classifying user answers to a specific outcome based on Oppia’s interaction rule engine. +- **domain/exploration** - Controller for loading explorations, managing states and playing explorations. +- **domain/locale** - Business logic for managing languages & locales. +- **domain/oppialogger** - Business logic for logging warnings and errors and analytics. +- **domain/platformparameter** - Business logic for [platform parameters](https://github.com/oppia/oppia-android/wiki/Platform-Parameters-&-Feature-Flags.). +- **domain/profile** - Controller for retrieving, adding, updating, and deleting profiles. +- **domain/state** - Business logic for managing ephemeral states in play sessions. +- **domain/testing** - Business logic for testing utilities for log uploading functionality. +- **domain/topic** - Controller for retrieving all aspects of a topic and topic list and the user’s progress. +- **domain/workmanager** - Business logic for providing implementation of work manager. + +Besides the subdirectories mentioned above, this module contains all of the test lesson assets loaded by the developer build of the app. The files for these test lessons can be found in the [domain/src/main/assets](https://github.com/oppia/oppia-android/tree/develop/domain/src/main/assets) subdirectory. + +#### 4. model + +This library contains all protos used in the app. It only contains data definitions, so no tests are included. + +#### 5. utility + +This is a Java/Kotlin module without Android dependencies. It contains utilities that all other modules may depend on. It also includes JUnit and robolectric test cases. Its subdirectories are as follows: + +- **utility/accessibility** - Utilities corresponding to Android accessibility. +- **utility/data** - Various classes which help with effectively fetching locally-stored data in the domain layer. +- **utility/extensions** - Extensions for Android classes (e.g. LiveData). +- **utility/gcsresource** - Provides the default name of the GCS Resource bucket. +- **utility/logging** - Oppia Android does not use [Log](https://developer.android.com/reference/android/util/Log). Instead, it has a custom Logger, a wrapper class for Android Logcat and file logging. All logs in this project should use OppiaLogger instead of Log. +- **utility/networking** - A utility to get the current connection status of the device. +- **utility/parser** - Rich-text parsers (e.g. HtmlParser, UrlParser) ensure that the rich-text from the Oppia backend is parsed correctly to display it properly in the Android app. +- **utility/profile** - A utility to manage the creation and deletion of directories. +- **utility/statusbar** - A utility to change the colour of the status bar. +- **utility/system** - A utility that contains system-related utilities. + +#### 6. testing + +This module contains helper classes that make testing other modules easier. + +## App Architecture + Screenshot 2020-01-13 at 12 54 00 PM -The Oppia app follows a combination of MVP (Model-View-Presenter) and MVVM (Model-View-ViewModel) where different Android components fulfill requirements for each piece: -* 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. -* Android Views are classic views: they perform no logic and are simply responsible for displaying data from view models (via Android data-binding). -* View models are Android ViewModels that listen for and expose changes from the model layer. -* The model layer is defined by a combination of protobuf and Kotlin data objects that are provided from the controller layer using LiveData. Managers are responsible for maintaining state in this layer. -* The controller layer interacts with the database and network. It provides data via a custom data source mechanism. -* Android Activities should only perform high-level fragment transaction logic, and are responsible for initializing Dagger components and performing routing. -# Codebase Walkthrough +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. + +example 2 task image + +**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. + +example 2 layout inspector screenshot + +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** -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.) +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. -## Example +**Finding the tests** -**Task**: Add a button in Info Tab which will open an already existing activity (e.g. SplashActivity). +There are two sets of tests: +- Tests to test the UI component +- Tests to test the business logic of the UI component -**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 a `InjectableFragment`, and we can see that it just calls the `TopicInfoFragmentPresenter`. -4. Inside `TopicInfoFragmentPresenter`, we can see that an XML layout is getting inflated 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)`. From this, we know that the corresponding xml file name is `topic_info_fragment.xml`. -5. Now, open `topic_info_fragment.xml` file and create a button inside it. -6. The button click can be handled by data-binding a function (`clickDummyButton`) to the XML. That function will be created in the `TopicInfoViewModel`. From the **App Architecture** section, we know that the ViewModel does not handle the logic, and the presenter is responsible for the logic part. -7. So, we will create another function (`goToSplashActivity`) inside the `TopicInfoFragmentPresenter`. We can then call this function inside `clickDummyButton` which was present in `TopicInfoViewModel`. +Since the UI component is present in the TopicInfoFramgnet, the UI component tests are present in the file TopicInfoFragmentTest. -Following these steps would lead to the completion of the entire task, with all the code blocks in the correct files. +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 on 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 +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 From a2372b4a7c161fe0a013019d2837d5505e8ced6b Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Fri, 13 May 2022 01:28:06 -0700 Subject: [PATCH 316/374] Updated Dark Mode (markdown) --- Dark-Mode.md | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/Dark-Mode.md b/Dark-Mode.md index 352b6eaf6f3..87a6e95bf87 100644 --- a/Dark-Mode.md +++ b/Dark-Mode.md @@ -17,14 +17,14 @@ The following files have been added for maintaining the colors : example:
> Don't ```xml - #90EE90 - #90EE90 - #FF0000 + #90EE90 + #90EE90 + #FF0000 ``` > Do ```xml - #90EE90 - #0000FF + #90EE90 + #0000FF ``` Declarations from this file should be only used in `color_palette.xml`. @@ -33,38 +33,40 @@ The following files have been added for maintaining the colors : The declarations in this file should only reference `color_defs.xml`. >Don't: ```xml - @color/light_black - @color/oppia_pink + @color/light_black + @color/oppia_pink ``` >Do: ```xml - @color/light_black - @color/oppia_pink + @color/light_black + @color/oppia_pink ``` You can refer to both variations of these files to see how it separates the colors. 3. **`component_colors.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 - @color/primary_text_color - @color/toolbar_color + @color/primary_text_color + @color/toolbar_color - @color/primary_text_color - @color/primary_text_color - @color/text_input_background_color + @color/primary_text_color + @color/primary_text_color + @color/text_input_background_color - @color/description_text_color - @color/background_color + @color/description_text_color + @color/background_color - @color/primary_text_color - @color/dark_text_color + @color/primary_text_color + @color/dark_text_color ``` 4. **`colors_migrating.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`* +_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. "`_`" (Look at the color name examples for better understanding.)*

@@ -75,10 +77,10 @@ Currently most of the layouts are directly referencing colors from `color_defs.x You can refer to the design mocks for expected final result : [Dark Mode Mocks](https://xd.adobe.com/view/c05e9343-60f6-4c11-84ac-c756b75b940f-950d/grid/) -#### How to acheive this goal? +#### How to achieve this goal? Here is how I would go around working with any particular layout...
-- 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 *`__color`*. +- 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___color`*. - Go through the mock for the concerned activity and note down which component of the app needs separate colors for day and night modes. The mock has provided hex color codes for all the elements in the UI, if any of the colors is not already present in the `color_defs.xml` then add it to the file with the actual color name. From a19ec926bced222b1e1077b04e7533a8c704ecbc Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:18:55 +0100 Subject: [PATCH 317/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index e9c6e249190..7be83c693c5 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -11,10 +11,15 @@ Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). -1. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include sections on installing OpenJDK on different platforms. For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: +1. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. + +For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: ```sh sudo apt install openjdk-8-jdk ``` + +For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
From f2c36b1e82b7ed822d769325ae873f9d3225c960 Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:19:33 +0100 Subject: [PATCH 318/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 7be83c693c5..e3b974762a1 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -11,22 +11,20 @@ Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). -1. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. +2. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. -For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: + - For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: ```sh sudo apt install openjdk-8-jdk - ``` - -For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". + `` + - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). + - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
- macOS: `export ANDROID_HOME=$HOME/Library/Android/sdk` -1. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). +4. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). #### Possible Error: ``` From 57e3e9bc3498d0293285941ce5a5cceb4dbb3664 Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:19:44 +0100 Subject: [PATCH 319/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index e3b974762a1..79b6bb16fb2 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -17,6 +17,7 @@ Instructions for setting up Bazel on Unix-based machines: ```sh sudo apt install openjdk-8-jdk `` + - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". From 2a0e8f915aac8a039f68ecde31aa4881eedb46e4 Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:19:56 +0100 Subject: [PATCH 320/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 79b6bb16fb2..51ef4db07dd 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -15,8 +15,7 @@ Instructions for setting up Bazel on Unix-based machines: - For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: ```sh - sudo apt install openjdk-8-jdk - `` + sudo apt install openjdk-8-jdk`` - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". From d62b01b42376e5fe4fbfe2445731c198ccbdec2f Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:20:05 +0100 Subject: [PATCH 321/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 51ef4db07dd..b98fb976ebc 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -15,7 +15,7 @@ Instructions for setting up Bazel on Unix-based machines: - For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: ```sh - sudo apt install openjdk-8-jdk`` + sudo apt install openjdk-8-jdk - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". From 73015fd0c4a954cd5a38638c04224a800e84a3cb Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:20:18 +0100 Subject: [PATCH 322/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index b98fb976ebc..c5daeff79e0 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -14,8 +14,10 @@ Instructions for setting up Bazel on Unix-based machines: 2. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. - For example, if you're using Ubuntu or another Debian-based system, you can run the following to install OpenJDK 8: + ```sh sudo apt install openjdk-8-jdk + ``` - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". From bf82ff95f24d165faaaf2eda829bc7e0c0ebda0a Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:20:41 +0100 Subject: [PATCH 323/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index c5daeff79e0..23d1fbe758a 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -20,7 +20,7 @@ Instructions for setting up Bazel on Unix-based machines: ``` - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From 9dcc43536cb38204055cc3ea3af36cb1a241115f Mon Sep 17 00:00:00 2001 From: Ankita Saxena Date: Fri, 27 May 2022 21:20:54 +0100 Subject: [PATCH 324/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 23d1fbe758a..bcdb6c6cf46 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -20,7 +20,8 @@ Instructions for setting up Bazel on Unix-based machines: ``` - For MacOS M1, follow the instructions [here](https://installvirtual.com/install-openjdk-8-on-mac-using-brew-adoptopenjdk/). Note that, this requires installation of brew as a pre-requisite, which can be done by following the instructions [here](https://mac.install.guide/homebrew/index.html). - You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". + + You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". 3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- Linux: `export ANDROID_HOME=$HOME/Android/Sdk/`
From 4b3763f2f69aa570eefdf6a5fcea6ca2727922e0 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 21 Jun 2022 10:47:24 -0700 Subject: [PATCH 325/374] Strengthen language around picking the correct commandline tools download. --- Bazel-Setup-Instructions-for-Windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index d0a1e0c3ab8..d3f1c12ee40 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -63,7 +63,7 @@ First, prepare the environment for the SDK by creating the default directory to 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. Once downloaded, copy the zip file to the new SDK location (note that the ``/mnt/c/...`` path is based on ``C:\Users\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: +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 ``/mnt/c/...`` path is based on ``C:\Users\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: ```sh cp /c/mnt/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk From 331fbf4316ce348f533f4a1ce03eb1d5a1f45acb Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 21 Jun 2022 10:56:18 -0700 Subject: [PATCH 326/374] Fix shell command for commandlinetools. --- Bazel-Setup-Instructions-for-Windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index d3f1c12ee40..4d295b72874 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -66,7 +66,7 @@ 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 ``/mnt/c/...`` path is based on ``C:\Users\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: ```sh -cp /c/mnt/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk +cp /mnt/c/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk ``` After that, change to the directory, unzip the archive, and remove it: From 5fd8a2341f448a45dcd4a69c16306f00115c5fd7 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 1 Jul 2022 14:12:23 -0700 Subject: [PATCH 327/374] Clarify two points that caused confusion during onboarding, thanks to KevinGitonga. --- Oppia-Bazel-Setup-Instructions.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index bcdb6c6cf46..26a8401c831 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -23,11 +23,14 @@ Instructions for setting up Bazel on Unix-based machines: You can confirm that this is set up using the command `java -version`, which should result in three lines being printed out with the first one showing "openjdk version "1.8.0_292". -3. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
+3. Ensure that you have Python 2 installed and make sure that it is currently active on your environment. You can do this by using the ``python --version`` command which should show Python 2.X.X. If it doesn’t, click [here](https://linuxconfig.org/install-python-2-on-ubuntu-20-04-focal-fossa-linux) for a resource on how to install and update Ubuntu to use Python 2 (other distros may vary in this step slightly). + +4. Ensure that your `ANDROID_HOME` environment variable is set to the location of your Android SDK. To do this, find the path to the installed SDK using Android Studio’s SDK Manager (install SDK 28). Assuming the SDK is installed to default locations, you can use the following commands to set the `ANDROID_HOME` variable:
- 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``). -4. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). +5. Follow the instructions in [oppia-bazel-tools](https://github.com/oppia/oppia-bazel-tools). #### Possible Error: ``` From 66ae4830f1e8f9c1dda58fd091edadd7dca4b485 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 15 Jul 2022 19:41:05 -0700 Subject: [PATCH 328/374] Update instructions to address some issues and pain points identified by @Ryggs. --- Bazel-Setup-Instructions-for-Windows.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Bazel-Setup-Instructions-for-Windows.md b/Bazel-Setup-Instructions-for-Windows.md index 4d295b72874..4425a088cee 100644 --- a/Bazel-Setup-Instructions-for-Windows.md +++ b/Bazel-Setup-Instructions-for-Windows.md @@ -63,10 +63,10 @@ First, prepare the environment for the SDK by creating the default directory to 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 ``/mnt/c/...`` path is based on ``C:\Users\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: +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\\Downloads`` being the default download location--this may not be the case on your system) with your Windows username filled in for ````: ```sh -cp /mnt/c/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk +cp /c/mnt/Users//Downloads/commandlinetools*.zip $HOME/Android/Sdk ``` After that, change to the directory, unzip the archive, and remove it: @@ -129,7 +129,7 @@ From there, follow [these instructions](https://github.com/oppia/oppia-bazel-too ### 6. Verifying the build -At this point, your system should be able to build Oppia Android. To verify, try building the APK (from your subsystem terminal): +At this point, your system should be able to build Oppia Android. To verify, try building the APK (from your subsystem terminal -- note that this & all other Bazel commands must be run from the root of the ‘oppia-android’ directory otherwise they will fail): ```sh bazel build //:oppia From e7bc869eb618c6244a06e4e72bbf5043a2d668b3 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 20 Jul 2022 16:54:07 -0700 Subject: [PATCH 329/374] Add details on the state of Bazel vs. Gradle. --- Contributing-to-Oppia-Android.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 639f8d2d50a..b95b7c85e0c 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -107,6 +107,11 @@ For now, you generally won't need to do this, until the Android app supports on- ``` By using this command git will detect the file as a renamed file. +* The team is currently using two build systems for the project: Gradle and Bazel. Please note that: + * It's currently recommended that all team members use **Gradle** for their active development in Android Studio. + * You may still need to use Bazel for debugging Bazel-specific tests or failures. To do this, you should follow the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions) to set up the ability to build with Bazel on your local command line. Most team members just use the console within Android Studio to run their Bazel commands. + * Bazel & Gradle sometimes don't play nicely with one another, so it's recommended that when you're verifying Bazel-specific things to do so in one go, and then delete the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. + * As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. ## Finding something to do **Starter projects for new contributors** From 801ec1a6e3faabb585dc9072474a46699a0c2e09 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 20 Jul 2022 17:10:48 -0700 Subject: [PATCH 330/374] Create dedicated Bazel migration section & clarify reasons. --- Contributing-to-Oppia-Android.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index b95b7c85e0c..569e8fc36ca 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -6,6 +6,7 @@ Thanks for your interest in contributing to the Oppia Android project, and makin * [Onboarding instructions](#onboarding-instructions) * [Install oppia-android](#install-oppia-android) * [Run the app from Android Studio](#run-the-app-from-android-studio) +* [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) * [Notes](#notes) * [Developing skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) * [Finding something to do](#finding-something-to-do) @@ -73,6 +74,17 @@ Please follow these steps to set up Oppia Android on your local machine. 3. Finally, click the "Run" button. +## Important: Ongoing Bazel migration + +The team is currently using two build systems for the project: Gradle and Bazel as we're actively migrating to Bazel. + +Please note that: +* It's currently recommended that all team members use **Gradle** for their active development in Android Studio. While some team members use the Bazel Android Studio plugin instead of Android Gradle Plugin (AGP), day-to-day Bazel development currently suffers from: + * Significant memory overhead that continues to grow without careful pruning (i.e. periodic shutdowns of the local Bazel build server). On some Linux distros this can result in a Kernel panic when memory is fully exhausted. + * Various symbolic errors throughout the codebase that can make it much more difficult to jump to specific symbols (though, unlike Gradle, all code including scripts are editable and runnable within Android Studio). +* When submitting a PR for review, you may notice that some Bazel-specific tests or workflows fail. Investigating and fixing these will require setting up Bazel in your local environment (see the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)), and then running the specific Bazel commands in your local repository (most team members just use the console within Android Studio to run their Bazel commands). +* Bazel & Gradle sometimes don't play nicely with one another, so it's recommended that when you're verifying Bazel-specific things to do so in one go, and then delete the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. +* As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. ## Installing the Oppia web app @@ -107,12 +119,6 @@ For now, you generally won't need to do this, until the Android app supports on- ``` By using this command git will detect the file as a renamed file. -* The team is currently using two build systems for the project: Gradle and Bazel. Please note that: - * It's currently recommended that all team members use **Gradle** for their active development in Android Studio. - * You may still need to use Bazel for debugging Bazel-specific tests or failures. To do this, you should follow the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions) to set up the ability to build with Bazel on your local command line. Most team members just use the console within Android Studio to run their Bazel commands. - * Bazel & Gradle sometimes don't play nicely with one another, so it's recommended that when you're verifying Bazel-specific things to do so in one go, and then delete the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. - * As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. - ## Finding something to do **Starter projects for new contributors** From 4f2cfb45c6d9abc9913773dd6c3d4552b83dccf2 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Wed, 20 Jul 2022 17:48:23 -0700 Subject: [PATCH 331/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 569e8fc36ca..8715e46cc21 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -76,14 +76,14 @@ Please follow these steps to set up Oppia Android on your local machine. ## Important: Ongoing Bazel migration -The team is currently using two build systems for the project: Gradle and Bazel as we're actively migrating to Bazel. +The team is currently using two build systems for the project: Gradle and Bazel. We're in the process of actively migrating to Bazel. Please note that: -* It's currently recommended that all team members use **Gradle** for their active development in Android Studio. While some team members use the Bazel Android Studio plugin instead of Android Gradle Plugin (AGP), day-to-day Bazel development currently suffers from: - * Significant memory overhead that continues to grow without careful pruning (i.e. periodic shutdowns of the local Bazel build server). On some Linux distros this can result in a Kernel panic when memory is fully exhausted. +* It's currently recommended that all team members use **Gradle** for their active development in Android Studio. While some team members use the Bazel Android Studio plugin instead of Android Gradle Plugin (AGP), we make this recommendation because day-to-day Bazel development currently suffers from: + * Significant memory overhead that continues to grow without careful pruning (i.e. periodic shutdowns of the local Bazel build server). On some Linux distros, this can result in a Kernel panic when memory is fully exhausted. * Various symbolic errors throughout the codebase that can make it much more difficult to jump to specific symbols (though, unlike Gradle, all code including scripts are editable and runnable within Android Studio). -* When submitting a PR for review, you may notice that some Bazel-specific tests or workflows fail. Investigating and fixing these will require setting up Bazel in your local environment (see the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)), and then running the specific Bazel commands in your local repository (most team members just use the console within Android Studio to run their Bazel commands). -* Bazel & Gradle sometimes don't play nicely with one another, so it's recommended that when you're verifying Bazel-specific things to do so in one go, and then delete the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. +* That said, when submitting a PR for review, you may notice that some Bazel-specific tests or workflows fail. Investigating and fixing these will require setting up Bazel in your local environment (see the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)), and then running the specific Bazel commands in your local repository (most team members just use the console within Android Studio to run their Bazel commands). +* Bazel & Gradle sometimes don't play nicely with one another. So, when you're verifying Bazel-specific things, we recommend doing so in one go, and then deleting the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. * As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. ## Installing the Oppia web app From d09360663cb422a034b53d0d2aef82d7e242d1e1 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 3 Aug 2022 01:37:09 +0530 Subject: [PATCH 332/374] Updated starting issues links. --- Contributing-to-Oppia-Android.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 8715e46cc21..69ba14a0a04 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -131,13 +131,13 @@ Welcome! Please make sure to follow the onboarding instructions above if you hav **UI** - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). + - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode+is%3Aopen) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). **Bazel** **Accessibility** - - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y) + - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y+no%3Aassignee) ## Communication channels From 68601756c2df779a0bc766d61906c8eb2d2fb0af Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 1 Sep 2022 16:37:23 -0700 Subject: [PATCH 333/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index d959b924447..9480f3298a9 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -149,8 +149,10 @@ You have successfully created a pull request! Now, wait for your code to get rev When your reviewer has reviewed the code, you'll get an email. You'll need to respond in two ways: 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. + + - **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. 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. From 8afa7556d4d631e18840af47325a25ed85b7b217 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 11:53:16 -0700 Subject: [PATCH 334/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 69ba14a0a04..77024d3ffa4 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -28,6 +28,9 @@ If you'd like to help out with the Android project, please follow the following Then, click "Apply" to download and install these two SDKs/Tools. +6. Read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) carefully. You'll need to understand this process well in order to create PRs to the project! + + **Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. ## Install oppia-android From 53dbf59aeb5e2edfa255dacf9112d472a04f8a4b Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 11:53:33 -0700 Subject: [PATCH 335/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 77024d3ffa4..2a047478757 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -28,7 +28,7 @@ If you'd like to help out with the Android project, please follow the following Then, click "Apply" to download and install these two SDKs/Tools. -6. Read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) carefully. You'll need to understand this process well in order to create PRs to the project! +6. Read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) carefully. You'll need to understand this process well in order to submit PRs to the project! **Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. From 3281df930caf32c222668cdc26d4d4cb597549da Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 11:54:19 -0700 Subject: [PATCH 336/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 46 ++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 2a047478757..1d73cd5dd06 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -77,6 +77,32 @@ Please follow these steps to set up Oppia Android on your local machine. 3. Finally, click the "Run" button. + +## Finding something to do +**Starter projects for new contributors** + +Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. + +Also, read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). + +After that, we’d strongly recommend tackling some part of one of the following starter issues. + +**Testing** + + - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) + +**UI** + + - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) + - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode+is%3Aopen) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). + +**Bazel** + +**Accessibility** + + - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y+no%3Aassignee) + + ## Important: Ongoing Bazel migration The team is currently using two build systems for the project: Gradle and Bazel. We're in the process of actively migrating to Bazel. @@ -122,26 +148,6 @@ For now, you generally won't need to do this, until the Android app supports on- ``` By using this command git will detect the file as a renamed file. -## Finding something to do -**Starter projects for new contributors** - -Welcome! Please make sure to follow the onboarding instructions above if you haven’t already, and also read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). After that, we’d strongly recommend tackling some part of one of the following starter issues. - -**Testing** - - - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) - -**UI** - - - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode+is%3Aopen) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). - -**Bazel** - -**Accessibility** - - - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y+no%3Aassignee) - ## Communication channels From 89c4edb9ca89d74892c82ae4fd170a4d988aca34 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:02:57 -0700 Subject: [PATCH 337/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index 9480f3298a9..c8e8a7acb87 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -5,7 +5,7 @@ Here are the steps for making a PR to the Oppia Android codebase: 1. [Make a local code change](#step-1-making-a-local-code-change) 2. [Create a PR on GitHub](#step-2-create-a-pr-on-github) -3. [Address review comments until all reviewers give LGTM](#step-3-address-review-comments-until-all-reviewers-give-lgtm) +3. [Address review comments until all reviewers give LGTM](#step-3-address-review-comments-until-all-reviewers-give-lgtm) (this section is important, please read it carefully) 4. [Tidy up and celebrate!](#step-4-tidy-up-and-celebrate-confetti_ball) Note: If your change involves more than around 500 lines of code, we recommend first creating a [design doc](https://github.com/oppia/oppia/wiki/Writing-design-docs). This helps avoid duplication of effort, and allows us to offer advice and suggestions on the implementation approach. @@ -147,29 +147,29 @@ You have successfully created a pull request! Now, wait for your code to get rev ## 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 in two ways: +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. - 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. + - 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. Resolve any merge conflicts that arise 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. -Once you've finished addressing everything, and would like the reviewer to take another look, 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. +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. -At the end, the reviewer will merge the pull request. + - 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 merged -1. Keep track of the **Assignees** section, and reply to comments in the PR itself. -2. PRs will not be merged if there are any requested changes, or if there are any unresolved conversation threads. -3. Do not resolve a conversation if you didn't open it, unless the author explicitly says that you can. You should re-assign the PR to the author once you address all of the comments so that they can verify & mark the conversations as resolved. -4. Make sure that the assignee list always reflects the contributors who have actionable items left on the PR (either to make requested changes, merge the PR, review it, or resolve open comment threads). Note that it's perfectly fine if sometimes both the author and reviewer of a PR are both assigned to it (one reviewer may have finished a review pass and requested changes--in this situation both another reviewer and author might have actionable work items to complete). -5. Address all comments before sending a PR back to a reviewer. 'Address' can mean implementing a code change, asking a clarifying question, or providing an explanation why you don't think a suggestion should implemented. Make sure each comment thread has at a reply from you before sending the PR back to that reviewer. -6. 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. +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. +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. ### Resolving merge conflicts using the terminal From 6f0955b2466792775004b1902da0785591192ee1 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:03:29 -0700 Subject: [PATCH 338/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index c8e8a7acb87..d4155ea5b2b 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -165,14 +165,14 @@ When your reviewer has reviewed the code, you'll get an email. You'll need to re 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 merged +### 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. 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. -### Resolving merge conflicts using the terminal +### Appendix: Resolving merge conflicts using the terminal To resolve conflicts between ‘new-branch-name’ (in your fork) and ‘develop’ (in the oppia repository), run: @@ -184,7 +184,7 @@ git commit -a git push origin new-branch-name ``` -### Resolving merge conflicts using Android Studio +### 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. From c3594d71a0e601cc77cde8bbbef1c208cd58020a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:14:04 -0700 Subject: [PATCH 339/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 1d73cd5dd06..6c77de82f8d 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -6,10 +6,10 @@ Thanks for your interest in contributing to the Oppia Android project, and makin * [Onboarding instructions](#onboarding-instructions) * [Install oppia-android](#install-oppia-android) * [Run the app from Android Studio](#run-the-app-from-android-studio) +* [Finding something to do](#finding-something-to-do) * [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) * [Notes](#notes) * [Developing skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) -* [Finding something to do](#finding-something-to-do) * [Communication channels](#communication-channels) ## Onboarding instructions From 48f04225c8b31dc69afd478ee7e1566b4f1c75da Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:14:47 -0700 Subject: [PATCH 340/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 6c77de82f8d..171a08a465d 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -7,9 +7,9 @@ Thanks for your interest in contributing to the Oppia Android project, and makin * [Install oppia-android](#install-oppia-android) * [Run the app from Android Studio](#run-the-app-from-android-studio) * [Finding something to do](#finding-something-to-do) +* [Developing your skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) * [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) -* [Notes](#notes) -* [Developing skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) +* [Installing the Oppia web app](#installing-the-oppia-web-app) * [Communication channels](#communication-channels) ## Onboarding instructions From 3accfe493f0fa25d9e454a40e1f9c0f00251525e Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:15:19 -0700 Subject: [PATCH 341/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 171a08a465d..adc19bd8e1d 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -4,6 +4,7 @@ Thanks for your interest in contributing to the Oppia Android project, and makin ## Table of Contents * [Onboarding instructions](#onboarding-instructions) + * [Guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) * [Install oppia-android](#install-oppia-android) * [Run the app from Android Studio](#run-the-app-from-android-studio) * [Finding something to do](#finding-something-to-do) From 064fda67ed799f640816d902caec496ad4ff36b7 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 8 Sep 2022 12:17:24 -0700 Subject: [PATCH 342/374] Updated Guidance on submitting a PR (markdown) --- Guidance-on-submitting-a-PR.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Guidance-on-submitting-a-PR.md b/Guidance-on-submitting-a-PR.md index d4155ea5b2b..40761d5b8aa 100644 --- a/Guidance-on-submitting-a-PR.md +++ b/Guidance-on-submitting-a-PR.md @@ -159,7 +159,7 @@ When your reviewer has reviewed the code, you'll get an email. You'll need to re 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. +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. @@ -167,7 +167,7 @@ At the end, the reviewer will merge the pull request. Note however PRs will only ### 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. +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. From 0557496fb9e25e0459bc4e275bad1f584da3684c Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 19 Sep 2022 16:20:07 -0700 Subject: [PATCH 343/374] Correct Bazel build instructions (relative directory was confusing and potentially wrong for later steps). --- End-to-End-Testing-Guide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/End-to-End-Testing-Guide.md b/End-to-End-Testing-Guide.md index d88897d2168..63e86fcf831 100644 --- a/End-to-End-Testing-Guide.md +++ b/End-to-End-Testing-Guide.md @@ -56,13 +56,13 @@ The android_binary of a test suite generates a test apk with the same name as th #### Steps to run the tests -1. Build the oppia_test and test suite android_binary from the instrumentation module +1. Build the oppia_test and test suite android_binary from the **root** repository directory: ``` - bazel build :oppia_test && bazel build //instrumentation: + bazel build //instrumentation:oppia_test && bazel build //instrumentation: ``` e.g.: ``` - bazel build :oppia_test && bazel build //instrumentation/src/javatests/org/oppia/android/instrumentation/player:ExplorationPlayerTestBinary + bazel build //instrumentation:oppia_test && bazel build //instrumentation/src/javatests/org/oppia/android/instrumentation/player:ExplorationPlayerTestBinary ``` 2. install the oppia_test.apk and the test suite’s APK ``` From d64e34ea31d70fb6430b19d16fb0a1a4dc9ba901 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 13 Oct 2022 09:17:33 -0700 Subject: [PATCH 344/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 5846aaaf373..f4150e60205 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,7 +7,7 @@ --- **Developing Oppia** - * [[Contributing to Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] + * [[Contributing to Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#onboarding-instructions]] * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] * [[Finding Something to do|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do]] From 9c33f76e5c8f2fc43f02f4e87d203a851ced48d8 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 9 Nov 2022 12:16:45 +0530 Subject: [PATCH 345/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index 1d392f68bb9..fd8d2aa0064 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -107,3 +107,6 @@ This entire sheet should be filled with each release as a part of audit process. * Texts should have a minimum `12sp` text size. * Images/icons should have a meaningful content description. +## Exceptional Cases +* Generally we use `sp` only for text-size/font-size of text and at all attributes related to width/height we use `dp`. But we can use width in `sp` if we have text inside a fixed width container. This will increase the size of container whenever we increase the font size, so the scaled text get enough size to fit inside a container. If this case is applied anywhere in UI, please get confirmation from @BenHenning or @rt4914 . + From 2497d9453de91c212d859756d08e92b462d09050 Mon Sep 17 00:00:00 2001 From: Rajat Talesra Date: Wed, 9 Nov 2022 12:31:46 +0530 Subject: [PATCH 346/374] Updated Accessibility (A11y) Guide (markdown) --- Accessibility-(A11y)-Guide.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/Accessibility-(A11y)-Guide.md b/Accessibility-(A11y)-Guide.md index fd8d2aa0064..603d1e28f45 100644 --- a/Accessibility-(A11y)-Guide.md +++ b/Accessibility-(A11y)-Guide.md @@ -110,3 +110,35 @@ This entire sheet should be filled with each release as a part of audit process. ## Exceptional Cases * Generally we use `sp` only for text-size/font-size of text and at all attributes related to width/height we use `dp`. But we can use width in `sp` if we have text inside a fixed width container. This will increase the size of container whenever we increase the font size, so the scaled text get enough size to fit inside a container. If this case is applied anywhere in UI, please get confirmation from @BenHenning or @rt4914 . +## Android 12 Warnings around TextViews in Fixed Layouts + +### Problem with fixed layout + +If we have scalable text inside a fixed width container then accessibility scanner is suggesting to improve text scaling, as if the text scales it won’t get enough space to expand inside a fixed width container. + + + +### 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. + + From ae8f3352d871ffdbbf1e1d34426e119396a0d4ee Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 13 Dec 2022 18:34:16 -0800 Subject: [PATCH 347/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index adc19bd8e1d..311fd6dbd26 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -80,29 +80,26 @@ Please follow these steps to set up Oppia Android on your local machine. ## Finding something to do -**Starter projects for new contributors** +**Good first issues for new contributors** Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. Also, read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). -After that, we’d strongly recommend tackling some part of one of the following starter issues. +After that, we’d strongly recommend tackling some part of one of the following good first issues. **Testing** - - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) **UI** - - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode+is%3Aopen) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). -**Bazel** - **Accessibility** - - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y+no%3Aassignee) +You may also tackle other [good first issues](https://github.com/oppia/oppia-android/labels/good%20first%20issue). When claiming an issue, please explain how you would tackle the issue (if there aren't pre-existing instructions) and tag the corresponding team lead (typically **@BenHenning**) if you wish to be assigned to it. + ## Important: Ongoing Bazel migration @@ -152,8 +149,4 @@ For now, you generally won't need to do this, until the Android app supports on- ## Communication channels -### Mailing lists - -We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! - 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). \ No newline at end of file From 12d0b3dc5161d4bac636adf9785fad905089c8a2 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Wed, 25 Jan 2023 00:54:03 +0800 Subject: [PATCH 348/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 65 +++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 21 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index 311fd6dbd26..d3a4e94d3fc 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -1,36 +1,58 @@ _These instructions are for developers who'd like to contribute code to improve the Oppia platform. If you'd prefer to help out with other things, please see our [[general contribution guidelines|Home]]._ Thanks for your interest in contributing to the Oppia Android project, and making it easier for students to learn online in an effective and enjoyable way! + +If you run into any problems along the way, we're here to help! Check out our [[wiki page on getting help|Get-Help]] for the communication channels you can use. If you find any bugs, you can also file an issue on our [issue tracker](https://github.com/oppia/oppia-android/issues). There are also lots of helpful resources in the sidebar, check that out too! + +**Important! Please read this page in its entirety before making any code changes.** It contains lots of really important information. You should also read through our [guide to making pull requests](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). + ## Table of Contents -* [Onboarding instructions](#onboarding-instructions) - * [Guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) -* [Install oppia-android](#install-oppia-android) -* [Run the app from Android Studio](#run-the-app-from-android-studio) -* [Finding something to do](#finding-something-to-do) -* [Developing your skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) -* [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) -* [Installing the Oppia web app](#installing-the-oppia-web-app) -* [Communication channels](#communication-channels) +- [Onboarding instructions](#onboarding-instructions) + - [Guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) +- [Install oppia-android](#install-oppia-android) +- [Run the app from Android Studio](#run-the-app-from-android-studio) +- [Finding something to do](#finding-something-to-do) +- [Developing your skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) +- [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) +- [Installing the Oppia web app](#installing-the-oppia-web-app) +- [Communication channels](#communication-channels) ## Onboarding instructions + If you'd like to help out with the Android project, please follow the following steps to get started: 1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). + 2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** -3. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). -4. Download and Install **Java 8** using the links from [the Java website](https://www.java.com/en/download/). + +3. Say hi and introduce yourself on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/4788)! + +4. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). + +5. 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. -5. In Android Studio, open Tools > SDK Manager. + +6. In Android Studio, open Tools > SDK Manager. - In the "SDK Platforms" tab (which is the default), select `API Level 28`. - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). Then, click "Apply" to download and install these two SDKs/Tools. -6. Read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) carefully. You'll need to understand this process well in order to submit PRs to the project! +7. Familiarize yourself with the resources linked to from the sidebar of this page, especially the [overview of the codebase](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture), the [[coding style guide|Coding-style-guide]], and the [[Frequent Errors and Solutions|Frequent-Errors-and-Solutions]]. You don't have to read all the other stuff right now, but it's a good idea to be aware of what's available, so that you can refer to it later if needed. + +8. Take up your first Oppia Android starter issue! (See [below](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do) on how to do this.) Make sure to read and follow the [[PR instructions|Guidance-on-submitting-a-PR]] closely so that your PR review proceeds smoothly. + + - In your browser, consider bookmarking the [[guide to making pull requests|Guidance-on-submitting-a-PR]] for easy reference later, as well as the ["my issues" page](https://github.com/issues/assigned) (so that you can keep track of the issues assigned to you). + + - Facing any problems (including non-coding ones)? Please feel free to create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) and get help from the Oppia community. You can use this avenue for asking anything -- questions about any issue, who to contact for specific things, etc. + - We also have onboarding mentors who would be more than happy to help you take your first steps in open source. If you'd like individual support, feel free to request a mentor [using this form](https://forms.gle/udsRP4WQgLcez9Zm8). + +9. When you have merged PRs that correspond to two different pre-existing GitHub issues, please fill in [this form](https://forms.gle/NxPjimCMqsSTNUgu5) to become an Oppia collaborator! This will grant you access to the repository, and allow you to join a team. (But please don't create your own issues and then make PRs for them -- that won't count.) + **Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. @@ -40,7 +62,7 @@ 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. + **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.): @@ -70,6 +92,7 @@ Please follow these steps to set up Oppia Android on your local machine. ## Run the app from Android Studio 1. Go to Tools > AVD Manager, click "Create Virtual Device...". Then: + - Select a preferred device definition. In general, any device is fine, but you can use Pixel 3a as a default (if you're developing for phones) or Nexus 7 (if you're developing for tablets). After selecting a device, click "Next" at the bottom right to continue. - Select a system image (in general, API Level 28, unless you're an M1 Mac user, in which case use API Level 29). Then click "Next". - Click "Finish" to complete setup. @@ -78,8 +101,8 @@ Please follow these steps to set up Oppia Android on your local machine. 3. Finally, click the "Run" button. - ## Finding something to do + **Good first issues for new contributors** Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. @@ -106,12 +129,12 @@ You may also tackle other [good first issues](https://github.com/oppia/oppia-and The team is currently using two build systems for the project: Gradle and Bazel. We're in the process of actively migrating to Bazel. Please note that: -* It's currently recommended that all team members use **Gradle** for their active development in Android Studio. While some team members use the Bazel Android Studio plugin instead of Android Gradle Plugin (AGP), we make this recommendation because day-to-day Bazel development currently suffers from: - * Significant memory overhead that continues to grow without careful pruning (i.e. periodic shutdowns of the local Bazel build server). On some Linux distros, this can result in a Kernel panic when memory is fully exhausted. - * Various symbolic errors throughout the codebase that can make it much more difficult to jump to specific symbols (though, unlike Gradle, all code including scripts are editable and runnable within Android Studio). -* That said, when submitting a PR for review, you may notice that some Bazel-specific tests or workflows fail. Investigating and fixing these will require setting up Bazel in your local environment (see the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)), and then running the specific Bazel commands in your local repository (most team members just use the console within Android Studio to run their Bazel commands). -* Bazel & Gradle sometimes don't play nicely with one another. So, when you're verifying Bazel-specific things, we recommend doing so in one go, and then deleting the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. -* As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. +- It's currently recommended that all team members use **Gradle** for their active development in Android Studio. While some team members use the Bazel Android Studio plugin instead of Android Gradle Plugin (AGP), we make this recommendation because day-to-day Bazel development currently suffers from: + - Significant memory overhead that continues to grow without careful pruning (i.e. periodic shutdowns of the local Bazel build server). On some Linux distros, this can result in a Kernel panic when memory is fully exhausted. + - Various symbolic errors throughout the codebase that can make it much more difficult to jump to specific symbols (though, unlike Gradle, all code including scripts are editable and runnable within Android Studio). +- That said, when submitting a PR for review, you may notice that some Bazel-specific tests or workflows fail. Investigating and fixing these will require setting up Bazel in your local environment (see the instructions [here](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions)), and then running the specific Bazel commands in your local repository (most team members just use the console within Android Studio to run their Bazel commands). +- Bazel & Gradle sometimes don't play nicely with one another. So, when you're verifying Bazel-specific things, we recommend doing so in one go, and then deleting the corresponding Bazel build artifacts using ``bazel clean`` before switching back over to Gradle (to avoid any issues with the two build systems crossing). Note that Bazel generally doesn't have any problems with Gradle build artifacts, so there's no need to clean the Gradle project first. +- As the team finishes the migration to Bazel, communications and instructions will be sent ahead of time for moving development environments away from Gradle so that we can officially deprecate it. ## Installing the Oppia web app From 9c9b798fe3cd5f9aa4f50269c563c8f8caa4379a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 26 Jan 2023 11:59:32 +0800 Subject: [PATCH 349/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index d3a4e94d3fc..f68bcfc1c99 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -105,23 +105,16 @@ Please follow these steps to set up Oppia Android on your local machine. **Good first issues for new contributors** -Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. +Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. Also, read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). -Also, read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). +After that, you can choose a good first issue from the [list of good first issues](https://github.com/oppia/oppia-android/labels/good%20first%20issue). These issues are hand-picked to ensure that you don't run into unexpected roadblocks while working on them, and each of them should have clear instructions for new contributors. If you see one that doesn't, please let us know via [GitHub Discussions](https://github.com/oppia/oppia-android/discussions) and we'll try to fix it. For other issues, you might need to be more independent because we might not know how to solve them either. -After that, we’d strongly recommend tackling some part of one of the following good first issues. +When you've found an issue you'd like to tackle, please leave a comment on it that: -**Testing** - - [Add missing tests](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+tests) +- @-mentions the team lead (typically **@BenHenning**), letting them know you'd like to work on it. +- describes in detail how you'd tackle the issue (e.g. explain which file(s) you would modify and what changes you would make). -**UI** - - [Merge different versions of a xml into a single xml file](https://github.com/oppia/oppia-android/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+single+xml+file) - - [Supporting dark mode](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+in%3Atitle+add+dark+mode+is%3Aopen) (see also [these instructions](https://github.com/oppia/oppia-android/wiki/Dark-Mode)). - -**Accessibility** - - [Accessibility support](https://github.com/oppia/oppia-android/issues?q=is%3Aissue+is%3Aopen+a11y+no%3Aassignee) - -You may also tackle other [good first issues](https://github.com/oppia/oppia-android/labels/good%20first%20issue). When claiming an issue, please explain how you would tackle the issue (if there aren't pre-existing instructions) and tag the corresponding team lead (typically **@BenHenning**) if you wish to be assigned to it. +If your explanation makes sense, we'll assign the issue to you. Feel free to go ahead and submit a PR for it by following the instructions for making a PR! If you run into any issues, feel free to create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) and get help from the Oppia community, or [request a mentor](https://forms.gle/udsRP4WQgLcez9Zm8) if you'd like individual support. ## Important: Ongoing Bazel migration From 4fc603b7ba9885804e1aec352f2c6385507132a5 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 2 Feb 2023 23:15:12 -0800 Subject: [PATCH 350/374] Updated _Sidebar (markdown) --- _Sidebar.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_Sidebar.md b/_Sidebar.md index f4150e60205..969ee1741ef 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -49,6 +49,7 @@ * 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 From b2ecdd0e9bae079acf6a96bbd799bdb38f01238f Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Thu, 2 Feb 2023 23:31:40 -0800 Subject: [PATCH 351/374] Created Internationalization (markdown) --- Internationalization.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 Internationalization.md diff --git a/Internationalization.md b/Internationalization.md new file mode 100644 index 00000000000..13bca2ec2f3 --- /dev/null +++ b/Internationalization.md @@ -0,0 +1,33 @@ +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. + +## Policy for enabling new languages + +Note that we only enable a select set of languages for Translatewiki. This is because we also need the lessons themselves to be sufficiently translated before we can offer the app in a given language. Therefore, in order not to waste translators' efforts, the policy for enabling languages for translation on Translatewiki is as follows: + + - The translations for all lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios 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 lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios topics on Oppia.org should be complete. + - All 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 Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios 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 Abijeet at translatewiki). + +### To enable a new language in the Android app + +Please do the following steps: + + 1. Verify that translations for all lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios 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 From 4d80a720c79cc860a2e09f2656ec4ac15f882f00 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 7 Feb 2023 12:53:23 +0800 Subject: [PATCH 352/374] Updated Internationalization (markdown) --- Internationalization.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Internationalization.md b/Internationalization.md index 13bca2ec2f3..01908e79b36 100644 --- a/Internationalization.md +++ b/Internationalization.md @@ -6,14 +6,16 @@ If you would like to help out with translations, you can do so by visiting the [ ## Policy for enabling new languages -Note that we only enable a select set of languages for Translatewiki. This is because we also need the lessons themselves to be sufficiently translated before we can offer the app in a given language. Therefore, in order not to waste translators' efforts, the policy for enabling languages for translation on Translatewiki is as follows: +Note that we only enable a select set of languages for Translatewiki. This is because we also need the lessons themselves to be sufficiently translated before we can offer the app in a given language. (We currently define this **minimal set** of topics as: Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios.) - - The translations for all lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios topics on Oppia.org should be complete, or very close to complete. +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 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 lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios topics on Oppia.org should be complete. - - All translations for that language are completed in Translatewiki. + - The translations for all topics in the minimal set on Oppia.org should be complete. + - All oppia-android-app translations for that language are completed in Translatewiki. ## Procedure for enabling new languages @@ -21,13 +23,13 @@ And the policy for enabling a language in the Android app is as follows: Please do the following steps: - 1. Verify that translations for all lessons in the Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios 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 Abijeet at translatewiki). + 1. Verify that translations for all lessons in the minimal set 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 Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios 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. + 1. Verify that translations for all lessons in the minimal set 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 From 9ba2d5b70903983339fb94a716fc0b7f70464e47 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 7 Feb 2023 12:55:21 +0800 Subject: [PATCH 353/374] Updated Internationalization (markdown) --- Internationalization.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Internationalization.md b/Internationalization.md index 01908e79b36..75782b8c297 100644 --- a/Internationalization.md +++ b/Internationalization.md @@ -4,11 +4,15 @@ We are grateful for the support of [Translatewiki](https://translatewiki.net/w/i 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. -## Policy for enabling new languages +## 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. -Note that we only enable a select set of languages for Translatewiki. This is because we also need the lessons themselves to be sufficiently translated before we can offer the app in a given language. (We currently define this **minimal set** of topics as: Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios.) +Currently, we define this **minimal set** of topics as: Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios. + +## Policy for enabling new languages -In order not to waste translators' efforts, the policy for enabling languages for translation on Translatewiki is as follows: +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 on Oppia.org should be complete, or very close to complete. From f47e57dcabae53b0ed49cdead4c6f5ecb3b36f4f Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 7 Feb 2023 12:56:36 +0800 Subject: [PATCH 354/374] Updated Internationalization (markdown) --- Internationalization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Internationalization.md b/Internationalization.md index 75782b8c297..756e597901e 100644 --- a/Internationalization.md +++ b/Internationalization.md @@ -8,13 +8,13 @@ If you would like to help out with translations, you can do so by visiting the [ 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 this **minimal set** of topics as: Place Values, Addition and Subtraction, Multiplication, Division, Fractions and Ratios. +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 on Oppia.org should be complete, or very close to complete. + - The translations for all topics in the [minimal set|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: From a316d63131277b3a903a61a1c25da51db72767f0 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 7 Feb 2023 12:56:51 +0800 Subject: [PATCH 355/374] Updated Internationalization (markdown) --- Internationalization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Internationalization.md b/Internationalization.md index 756e597901e..fece92013c6 100644 --- a/Internationalization.md +++ b/Internationalization.md @@ -14,7 +14,7 @@ Currently, we define "sufficiently translated" to mean that the **minimal set** 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|Internationalization#minimal-set-of-topics] on Oppia.org should be complete, or very close to complete. + - The translations for all topics in the [[minimal set|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: From 14db006e50ab67af053e5d4b2cd47e95f85dd93a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Tue, 7 Feb 2023 12:57:23 +0800 Subject: [PATCH 356/374] Updated Internationalization (markdown) --- Internationalization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Internationalization.md b/Internationalization.md index fece92013c6..caaff0eaee8 100644 --- a/Internationalization.md +++ b/Internationalization.md @@ -18,7 +18,7 @@ Note that we only enable a select set of languages for Translatewiki, since rele And the policy for enabling a language in the Android app is as follows: - - The translations for all topics in the minimal set on Oppia.org should be complete. + - The translations for all topics in the [[minimal set|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 @@ -27,13 +27,13 @@ And the policy for enabling a language in the Android app is as follows: Please do the following steps: - 1. Verify that translations for all lessons in the minimal set 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. + 1. Verify that translations for all lessons in the [[minimal set|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 on Oppia.org are complete in that language, by going to the Contributor Dashboard and checking that there are no translations left to do. + 1. Verify that translations for all lessons in the [[minimal set|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 From 99d6c6555d2725cd0b41b1730190d729536f89dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vojt=C4=9Bch=20Jel=C3=ADnek?= Date: Thu, 23 Feb 2023 16:51:12 +0100 Subject: [PATCH 357/374] Update instructions according to my experience --- Contributing-to-Oppia-Android.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index f68bcfc1c99..fc8941ac18c 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -28,18 +28,7 @@ If you'd like to help out with the Android project, please follow the following 3. Say hi and introduce yourself on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/4788)! -4. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). - -5. 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. - -6. In Android Studio, open Tools > SDK Manager. - - In the "SDK Platforms" tab (which is the default), select `API Level 28`. - - Also, navigate to the "SDK Tools" tab, click the "Show Package Details" checkbox at the bottom right, then click on "Android SDK Build-Tools 31" and select 29.0.2 (this is needed for Bazel support). - - Then, click "Apply" to download and install these two SDKs/Tools. +4. Prepare your [developer environment](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#prepare-developer-environment) and then [install Oppia Android](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android) 7. Familiarize yourself with the resources linked to from the sidebar of this page, especially the [overview of the codebase](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture), the [[coding style guide|Coding-style-guide]], and the [[Frequent Errors and Solutions|Frequent-Errors-and-Solutions]]. You don't have to read all the other stuff right now, but it's a good idea to be aware of what's available, so that you can refer to it later if needed. @@ -56,6 +45,21 @@ If you'd like to help out with the Android project, please follow the following **Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. +## 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. @@ -91,7 +95,7 @@ Please follow these steps to set up Oppia Android on your local machine. ## Run the app from Android Studio -1. Go to Tools > AVD Manager, click "Create Virtual Device...". Then: +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". From 15e226a8989ae13e48aa3bc828d5daa9c22a7f02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vojt=C4=9Bch=20Jel=C3=ADnek?= Date: Thu, 2 Mar 2023 15:42:51 +0100 Subject: [PATCH 358/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 26a8401c831..58fdffc1b42 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -10,6 +10,7 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). + - As of February 2023 we have verified that on Ubuntu (and similar systems) the [apt repository approach](https://bazel.build/install/ubuntu#install-on-ubuntu) works, you just need to make sure to do `sudo apt install bazeů-4.0.0` as the alst command to install the correct version. 2. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. From 897edc4ca9263247d4e65196d819af5922013aa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vojt=C4=9Bch=20Jel=C3=ADnek?= Date: Thu, 2 Mar 2023 15:44:12 +0100 Subject: [PATCH 359/374] Updated Oppia Bazel Setup Instructions (markdown) --- Oppia-Bazel-Setup-Instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Oppia-Bazel-Setup-Instructions.md b/Oppia-Bazel-Setup-Instructions.md index 58fdffc1b42..e7f47c7ccd6 100644 --- a/Oppia-Bazel-Setup-Instructions.md +++ b/Oppia-Bazel-Setup-Instructions.md @@ -10,7 +10,7 @@ Bazel is an open-source build and test tool similar to Make, Maven, and Gradle. Instructions for setting up Bazel on Unix-based machines: 1. Install Bazel from [here](https://docs.bazel.build/versions/master/install.html). Make sure that you follow the instructions for installing a specific version (Oppia Android requires 4.0.0 and won't build on other versions). - - As of February 2023 we have verified that on Ubuntu (and similar systems) the [apt repository approach](https://bazel.build/install/ubuntu#install-on-ubuntu) works, you just need to make sure to do `sudo apt install bazeů-4.0.0` as the alst command to install the correct version. + - As of February 2023 we have verified that on Ubuntu (and similar systems) the [apt repository approach](https://bazel.build/install/ubuntu#install-on-ubuntu) works, you just need to make sure to do `sudo apt install bazeů-4.0.0` as the alst command to install the correct version. 2. Oppia Android also requires OpenJDK 8. The Bazel installation instructions above include [sections on installing OpenJDK](https://docs.bazel.build/versions/main/tutorial/java.html#install-the-jdk) on different platforms. From a69c4f32cdbdc2d1808df77aa1c0b18d2df36913 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:37:46 +0800 Subject: [PATCH 360/374] Created Installing Oppia Android (markdown) --- Installing-Oppia-Android.md | 62 +++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 Installing-Oppia-Android.md diff --git a/Installing-Oppia-Android.md b/Installing-Oppia-Android.md new file mode 100644 index 00000000000..b8d6c88fde3 --- /dev/null +++ b/Installing-Oppia-Android.md @@ -0,0 +1,62 @@ +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! + + +## 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 From c5e9997541facdacd641a65ac303b3c170b9ac20 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:39:42 +0800 Subject: [PATCH 361/374] Updated Installing Oppia Android (markdown) --- Installing-Oppia-Android.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Installing-Oppia-Android.md b/Installing-Oppia-Android.md index b8d6c88fde3..5fb0aea95d9 100644 --- a/Installing-Oppia-Android.md +++ b/Installing-Oppia-Android.md @@ -1,5 +1,11 @@ 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 From 432bd8e11c301548dc3ade30305b112aa636ae45 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:55:27 +0800 Subject: [PATCH 362/374] Updated Contributing to Oppia Android (markdown) --- Contributing-to-Oppia-Android.md | 107 ++++++------------------------- 1 file changed, 19 insertions(+), 88 deletions(-) diff --git a/Contributing-to-Oppia-Android.md b/Contributing-to-Oppia-Android.md index fc8941ac18c..bcb6e35f458 100644 --- a/Contributing-to-Oppia-Android.md +++ b/Contributing-to-Oppia-Android.md @@ -10,10 +10,7 @@ If you run into any problems along the way, we're here to help! Check out our [[ - [Onboarding instructions](#onboarding-instructions) - [Guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR) -- [Install oppia-android](#install-oppia-android) -- [Run the app from Android Studio](#run-the-app-from-android-studio) -- [Finding something to do](#finding-something-to-do) -- [Developing your skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) + - [Developing your skills](https://github.com/oppia/oppia-android/wiki/Developing-skills) - [Important: Ongoing Bazel migration](#important-ongoing-bazel-migration) - [Installing the Oppia web app](#installing-the-oppia-web-app) - [Communication channels](#communication-channels) @@ -22,103 +19,35 @@ If you run into any problems along the way, we're here to help! Check out our [[ If you'd like to help out with the Android project, please follow the following steps to get started: -1. Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). +### 1. Complete the preliminaries -2. Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know what your interests are. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** +- Sign the CLA, so that we can accept your contributions. If you're contributing as an individual, use the [individual CLA](https://goo.gl/forms/AttNH80OV0). If your company owns the copyright to your contributions, a company representative should sign the [corporate CLA](https://goo.gl/forms/xDq9gK3Zcv). -3. Say hi and introduce yourself on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/4788)! +- Fill in the [Oppia contributor survey](https://goo.gl/forms/otv30JV3Ihv0dT3C3) to let us know your interests. (You can always change your responses later.) **Make sure to indicate prominently that you are interested in helping out with Android.** -4. Prepare your [developer environment](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#prepare-developer-environment) and then [install Oppia Android](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android) +- Say hi and introduce yourself on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions/4788)! -7. Familiarize yourself with the resources linked to from the sidebar of this page, especially the [overview of the codebase](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture), the [[coding style guide|Coding-style-guide]], and the [[Frequent Errors and Solutions|Frequent-Errors-and-Solutions]]. You don't have to read all the other stuff right now, but it's a good idea to be aware of what's available, so that you can refer to it later if needed. +### 2. Set up your development environment -8. Take up your first Oppia Android starter issue! (See [below](https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do) on how to do this.) Make sure to read and follow the [[PR instructions|Guidance-on-submitting-a-PR]] closely so that your PR review proceeds smoothly. +- Follow the instructions on [[Installing Oppia Android|Installing-Oppia-Android]] to prepare your developer environment and install Oppia Android. **Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which are needed to build the app. - - In your browser, consider bookmarking the [[guide to making pull requests|Guidance-on-submitting-a-PR]] for easy reference later, as well as the ["my issues" page](https://github.com/issues/assigned) (so that you can keep track of the issues assigned to you). +- Familiarize yourself with the resources linked to from the wiki sidebar, especially the [overview of the codebase](https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture), the [[coding style guide|Coding-style-guide]], and the [[Frequent Errors and Solutions|Frequent-Errors-and-Solutions]]. (You don't have to read everything else right now, but it's a good idea to be aware of what's available, so that you can refer to it later if needed.) - - Facing any problems (including non-coding ones)? Please feel free to create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) and get help from the Oppia community. You can use this avenue for asking anything -- questions about any issue, who to contact for specific things, etc. - - We also have onboarding mentors who would be more than happy to help you take your first steps in open source. If you'd like individual support, feel free to request a mentor [using this form](https://forms.gle/udsRP4WQgLcez9Zm8). - -9. When you have merged PRs that correspond to two different pre-existing GitHub issues, please fill in [this form](https://forms.gle/NxPjimCMqsSTNUgu5) to become an Oppia collaborator! This will grant you access to the repository, and allow you to join a team. (But please don't create your own issues and then make PRs for them -- that won't count.) - +### 3. Pick your first starter issue! -**Note:** Make sure you have good Internet connectivity when developing on Oppia Android, since this project uses third party libraries which will be needed to build the app. +We suggest choosing your first issue from the [list of good first issues](https://github.com/oppia/oppia-android/labels/good%20first%20issue). These issues are hand-picked to ensure that you don't run into unexpected roadblocks while working on them, and each of them should have clear instructions for new contributors. (If not, please let us know via [GitHub Discussions](https://github.com/oppia/oppia-android/discussions) and we'll try to fix it.) -## Prepare developer environment +When you've found an issue you'd like to tackle: -1. Download/Install the latest version of [Android Studio](https://developer.android.com/studio/?gclid=EAIaIQobChMI8fX3n5Lb6AIVmH8rCh24JQsxEAAYASAAEgL4L_D_BwE&gclsrc=aw.ds#downloads). +- Leave a comment that describes in detail how you'll tackle it (e.g. explain which file(s) you would modify and what changes you would make), and @-mention the team lead (typically **@BenHenning**). If your explanation makes sense, we'll assign the issue to you. +- Submit a PR, following the [[guidance on submitting a PR|Guidance-on-submitting-a-PR]]. (Consider bookmarking this guide in your browser for easy reference. We also suggest bookmarking the ["my issues" page](https://github.com/issues/assigned) so that you can keep track of the issues assigned to you.) +- If you run into any problems, feel free to create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) and get help from the Oppia community, or [request a mentor](https://forms.gle/udsRP4WQgLcez9Zm8) if you'd like individual support. -2. Download and Install **Java 8** using the links from [the Java website](https://www.java.com/en/download/). - - **Note for Windows users:** Make sure to also set up the PATH system variable correctly for `Java`, following [these instructions](https://www.java.com/en/download/help/path.html). - - [Instructions](https://www.java.com/en/download/help/linux_install.html) for Linux users. - - [Instructions](https://www.java.com/en/download/help/mac_install.html) for Mac users. +You are also welcome to tackle non-starter issues, but for those, you might need to be more independent, because we might not know how to solve them either! -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). +Once you've merged PRs that correspond to **two** different pre-existing GitHub issues, please fill in [this form](https://forms.gle/NxPjimCMqsSTNUgu5) to become an Oppia collaborator! This will grant you access to the repository, and allow you to join a team. (But please don't create your own issues and then make PRs for them -- that won't count.) - 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. - -## Finding something to do - -**Good first issues for new contributors** - -Welcome! Please make sure to follow the onboarding instructions above if you haven’t already. Also, read the [guidance on submitting a PR](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR). - -After that, you can choose a good first issue from the [list of good first issues](https://github.com/oppia/oppia-android/labels/good%20first%20issue). These issues are hand-picked to ensure that you don't run into unexpected roadblocks while working on them, and each of them should have clear instructions for new contributors. If you see one that doesn't, please let us know via [GitHub Discussions](https://github.com/oppia/oppia-android/discussions) and we'll try to fix it. For other issues, you might need to be more independent because we might not know how to solve them either. - -When you've found an issue you'd like to tackle, please leave a comment on it that: - -- @-mentions the team lead (typically **@BenHenning**), letting them know you'd like to work on it. -- describes in detail how you'd tackle the issue (e.g. explain which file(s) you would modify and what changes you would make). - -If your explanation makes sense, we'll assign the issue to you. Feel free to go ahead and submit a PR for it by following the instructions for making a PR! If you run into any issues, feel free to create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) and get help from the Oppia community, or [request a mentor](https://forms.gle/udsRP4WQgLcez9Zm8) if you'd like individual support. ## Important: Ongoing Bazel migration @@ -169,4 +98,6 @@ For now, you generally won't need to do this, until the Android app supports on- ## Communication channels -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). \ No newline at end of file +If you run into any problems (including non-coding ones), you can ask questions on [GitHub Discussions](https://github.com/oppia/oppia-android/discussions). You can use this avenue for asking anything -- questions about any issue, who to contact for specific things, etc. + +You can also check out the [developer mailing list](https://groups.google.com/forum/?fromgroups#!forum/oppia-android-dev). \ No newline at end of file From b729c16d8b46b9e2e45d387da090a38b8487506e Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:55:53 +0800 Subject: [PATCH 363/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index 969ee1741ef..ba10f9a6b11 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -8,7 +8,7 @@ --- **Developing Oppia** * [[Contributing to Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#onboarding-instructions]] - * [[Installing Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#install-oppia-android]] + * [[Installing Oppia-Android|Installing-Oppia-Android]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] * [[Finding Something to do|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do]] * [[How to Get Help | https://github.com/oppia/oppia-android/wiki/Get-Help]] From bb80309ac018da04cf251c70bd8468adc9eae34a Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:56:57 +0800 Subject: [PATCH 364/374] Updated _Sidebar (markdown) --- _Sidebar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_Sidebar.md b/_Sidebar.md index ba10f9a6b11..d10ae0f6cea 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -7,10 +7,10 @@ --- **Developing Oppia** - * [[Contributing to Oppia-Android|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#onboarding-instructions]] + * Contributing to Oppia Android + * [[Getting Started|Contributing-to-Oppia-android]] * [[Installing Oppia-Android|Installing-Oppia-Android]] * [[Troubleshooting Installation|https://github.com/oppia/oppia-android/wiki/Troubleshooting-Installation]] - * [[Finding Something to do|https://github.com/oppia/oppia-android/wiki/Contributing-to-Oppia-android#finding-something-to-do]] * [[How to Get Help | https://github.com/oppia/oppia-android/wiki/Get-Help]] * Bazel * [[Bazel setup instructions|https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions]] From d0700056bfe1a1a0d13859fa8cbbd276c253e6f4 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 18:58:33 +0800 Subject: [PATCH 365/374] Updated Troubleshooting Installation (markdown) --- Troubleshooting-Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Troubleshooting-Installation.md b/Troubleshooting-Installation.md index ff2bf4e9ccc..08e1910adb6 100644 --- a/Troubleshooting-Installation.md +++ b/Troubleshooting-Installation.md @@ -20,4 +20,4 @@ Here are some general troubleshooting tips for oppia-android. The specific platf **Can’t find the 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 **@FareesHussain**. +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**. From 38fc5211b6a883aad7ab677b5265f99e9d20ee1c Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 19:04:04 +0800 Subject: [PATCH 366/374] Updated Get Help (markdown) --- Get-Help.md | 30 +++++++++++------------------- 1 file changed, 11 insertions(+), 19 deletions(-) diff --git a/Get-Help.md b/Get-Help.md index ce2b796f885..809f2e19141 100644 --- a/Get-Help.md +++ b/Get-Help.md @@ -2,10 +2,9 @@ * [Communication channels](#communication-channels) * [Email](#email) - * [Gitter](#gitter) + * [GitHub Discussions](#github-discussions) * [Google Chat or Hangouts](#google-chat-or-hangouts) * [GitHub](#github) - * [GitHub Discussions](#github-discussions) * [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) @@ -30,11 +29,15 @@ We have several mailing lists in the form of Google Groups that you can join: 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. -### Gitter +### GitHub Discussions -We have a developer chat room [here](https://gitter.im/oppia/oppia-android). Feel free to drop in and say hi! 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. For questions about setting up Oppia or regarding the codebase or tests you can create a [GitHub Discussion](https://github.com/oppia/oppia-android/discussions) where Oppia's Welfare team and other developers will assist you in resolving the issue. +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. -You can also directly message developers over Gitter. However, some developers don't monitor their Gitter messages regularly, so you might not get a response very quickly (or at all). +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 @@ -46,17 +49,6 @@ If you have a question about a pull request or issue, you can also reach out 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). -### GitHub Discussions -If you have questions regarding Oppia you can create a discussion here where Oppia's Welfare team and other developers will assist you in resolving the issue. 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. -* Setup Issues: Any issues that developers are facing with setting up or starting the server. -* Q&A: Any questions that developers have. -* Ideas: Any developer can place an idea here and it can be discussed here. -* Release: Discussion for bugs & PRs targeting the release. - -You can refer to [this guide](https://docs.github.com/en/discussions/quickstart#creating-a-new-discussion) on how to create a new discussion. - ## 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. @@ -152,15 +144,15 @@ Follow the template below for asking questions (fill in the values inside {{}} b * 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**, you can drop a message on the [gitter](https://gitter.im/oppia/oppia-chat#) chat too. + 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://gitter.im/oppia/oppia-android) and include the link to it in your question. It’s always better to see the code you are talking about! +* 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 the [gitter chat](https://gitter.im/oppia/oppia-android) if your question is not issue-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 From 48188b22cb2723cbec82c320ff79424937e8523f Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 19:05:15 +0800 Subject: [PATCH 367/374] Updated _Sidebar (markdown) --- _Sidebar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_Sidebar.md b/_Sidebar.md index d10ae0f6cea..b2bebf984a2 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -12,6 +12,7 @@ * [[Installing Oppia-Android|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]] @@ -19,7 +20,6 @@ * [[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]] - * [[Overview of the Oppia Android codebase and architecture|https://github.com/oppia/oppia-android/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture]] * 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]] From 31eef2543bc4dc718944ddaa846505d86ec30856 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 19:08:24 +0800 Subject: [PATCH 368/374] Updated Teams at Oppia Android (markdown) --- Teams-at-Oppia-Android.md | 37 +++++-------------------------------- 1 file changed, 5 insertions(+), 32 deletions(-) diff --git a/Teams-at-Oppia-Android.md b/Teams-at-Oppia-Android.md index a1d9a0f64ff..726504e26d8 100644 --- a/Teams-at-Oppia-Android.md +++ b/Teams-at-Oppia-Android.md @@ -6,7 +6,7 @@ This wiki page explains the different teams in Oppia and their composition. CLaM team is responsible for most of the UI based code (app-layer), which includes exploration player, question player, concept-card, subtopics, topics, etc. All these user-facing features must be RTL supportive, accessible by all and should work on all devices (mobile + tablet). -**Team contact:** Rajat Talesra (@rt4914) (lead), Ayush Kumar (@ayush0402), Yash Verma (@yash10019coder) +**Team contacts:** Ben Henning (@BenHenning) (lead), Adhiambo Peres (@adhiamboperes) ### Dev-workflow Team The dev-workflow team ensures that the Oppia development process is smooth, stable and enjoyable, by ensuring that the following always hold: @@ -25,23 +25,10 @@ Long-term projects include: * enabling Oppiabot to automatically handle review/code-owner assignments * speeding up the CI processes. -**Team contact:** Vinita Murthi (@vinitamurthi) (lead), Arjun Gupta (@ARJUPTA) +**Team contact:** Ben Henning (@BenHenning) (lead) ### Infrastructure Teams -##### Core Maintainers Team -The core maintainers team is accountable to the Oppia developer community with regards to preserving the stability of the entire Oppia codebase, by ensuring that the following things are true at all times for the "develop" branch on GitHub: -1. It is free of serious bugs that adversely impact the end-user experience. -2. It passes the CI checks. -3. It has no security issues. - -Because this group understands the "big picture" of Oppia, other contributors are expected to take their advice seriously, especially when members of this group are acting in an incident-response capacity. - -Membership of this group is decided by appointment, by a committee made up of the currently-serving core maintainers. - -Contributors should notify the members of this team when they see major bugs or security vulnerabilities. The Core Maintainers group can be contacted via the @oppia/core-maintainers alias or at oppia-core-maintainers@googlegroups.com. - - ##### Release Process Team This team is responsible for ensuring that Oppia releases happen smoothly, correctly, and on time. Long-term projects include: 1. Streamlining the release process, and automating as many parts as possible, in order to reduce the chance of human error. @@ -50,22 +37,8 @@ This team is responsible for ensuring that Oppia releases happen smoothly, corre **Team Contact:** Ben Henning (@BenHenning) -##### Quality Assurance Team -This team is responsible for ensuring that the Oppia codebase and releases are bug-free. Long-term projects include: -1. Deciding on a strategy for maintaining test coverage. -2. Improving test coverage to 100%. -3. Reducing the StackDriver error count to 0. -4. Organize the QA and bug fixing teams for each release. -5. Fix any known bugs in Oppia (especially user-facing ones). - -**Team Contact:** Ben Henning (@BenHenning) - -### Onboarding Team -The onboarding team aims to welcome new contributors and answer their questions. - -**Team contact:** Rajat Talesra (@rt4914) (lead), Sarthak Aggarwal (@Sarthak2601) -### Welfare Team -The welfare team is a group of Oppia developers who are committed to helping developers to be able to unblock themselves when they face any problems. +### Onboarding/Welfare Team +This team is a group of Oppia developers who are committed to helping developers to be able to unblock themselves when they face any problems. They also aim to welcome new contributors and answer their questions. -**Team contact:** Farees Hussain (@FareesHussain) (lead), Apoorv Srivastava (@MaskedCarrot) \ No newline at end of file +**Team contact:** Mohit Gupta (@MohitGupta121) \ No newline at end of file From 2e5395809b11a1da6cc1e3b2a733a482a098bd79 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 6 Mar 2023 19:10:10 +0800 Subject: [PATCH 369/374] Updated Get Help (markdown) --- Get-Help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Get-Help.md b/Get-Help.md index 809f2e19141..a40f9c589bb 100644 --- a/Get-Help.md +++ b/Get-Help.md @@ -101,7 +101,7 @@ paste a screenshot ### 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). +* 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 From 7d5737b380916c33e30d24cff76a7404feafd331 Mon Sep 17 00:00:00 2001 From: Praneeth Date: Wed, 8 Mar 2023 16:03:14 +0530 Subject: [PATCH 370/374] Move files to wiki folder --- .../Accessibility-(A11y)-Guide.md | 0 Background-Processing.md => wiki/Background-Processing.md | 0 .../Bazel-Setup-Instructions-for-Windows.md | 0 Buf-Guide.md => wiki/Buf-Guide.md | 0 Coding-style-guide.md => wiki/Coding-style-guide.md | 0 .../Contributing-to-Oppia-Android.md | 0 Creating-a-screenshot.md => wiki/Creating-a-screenshot.md | 0 Dagger.md => wiki/Dagger.md | 0 Dark-Mode.md => wiki/Dark-Mode.md | 0 DataProvider-&-LiveData.md => wiki/DataProvider-&-LiveData.md | 0 Dependency-Injection.md => wiki/Dependency-Injection.md | 0 Developing-skills.md => wiki/Developing-skills.md | 0 End-to-End-Testing-Guide.md => wiki/End-to-End-Testing-Guide.md | 0 Firebase-Console-Guide.md => wiki/Firebase-Console-Guide.md | 0 .../Fork-and-Clone-Oppia-Android.md | 0 .../Frequent-Errors-and-Solutions.md | 0 Get-Help.md => wiki/Get-Help.md | 0 .../Gradle--Bazel-Migration-Best-Practices-and-FAQ.md | 0 .../Guidance-on-submitting-a-PR.md | 0 Home.md => wiki/Home.md | 0 Installing-Oppia-Android.md => wiki/Installing-Oppia-Android.md | 0 .../Instructions-for-making-a-code-change.md | 0 Internationalization.md => wiki/Internationalization.md | 0 Interpreting-CI-Results.md => wiki/Interpreting-CI-Results.md | 0 Kotlin-Coroutines.md => wiki/Kotlin-Coroutines.md | 0 Ktlint-Guide.md => wiki/Ktlint-Guide.md | 0 Oppia's-Mission.md => wiki/Oppia's-Mission.md | 0 Oppia-Android-Testing.md => wiki/Oppia-Android-Testing.md | 0 .../Oppia-Bazel-Setup-Instructions.md | 0 .../Overview-of-the-Oppia-Android-codebase-and-architecture.md | 0 .../PersistentCacheStore-&-In-Memory-Blocking-Cache.md | 0 .../Platform-Parameters-&-Feature-Flags.md | 0 RTL-Guidelines.md => wiki/RTL-Guidelines.md | 0 .../Revert-&-regression-policy.md | 0 SLoP-2020.md => wiki/SLoP-2020.md | 0 Static-Analysis-Checks.md => wiki/Static-Analysis-Checks.md | 0 Teams-at-Oppia-Android.md => wiki/Teams-at-Oppia-Android.md | 0 .../Troubleshooting-Installation.md | 0 .../Updating-Maven-Dependencies.md | 0 Work-Manager.md => wiki/Work-Manager.md | 0 Working-on-UI.md => wiki/Working-on-UI.md | 0 Writing-design-docs.md => wiki/Writing-design-docs.md | 0 _Sidebar.md => wiki/_Sidebar.md | 0 43 files changed, 0 insertions(+), 0 deletions(-) rename Accessibility-(A11y)-Guide.md => wiki/Accessibility-(A11y)-Guide.md (100%) rename Background-Processing.md => wiki/Background-Processing.md (100%) rename Bazel-Setup-Instructions-for-Windows.md => wiki/Bazel-Setup-Instructions-for-Windows.md (100%) rename Buf-Guide.md => wiki/Buf-Guide.md (100%) rename Coding-style-guide.md => wiki/Coding-style-guide.md (100%) rename Contributing-to-Oppia-Android.md => wiki/Contributing-to-Oppia-Android.md (100%) rename Creating-a-screenshot.md => wiki/Creating-a-screenshot.md (100%) rename Dagger.md => wiki/Dagger.md (100%) rename Dark-Mode.md => wiki/Dark-Mode.md (100%) rename DataProvider-&-LiveData.md => wiki/DataProvider-&-LiveData.md (100%) rename Dependency-Injection.md => wiki/Dependency-Injection.md (100%) rename Developing-skills.md => wiki/Developing-skills.md (100%) rename End-to-End-Testing-Guide.md => wiki/End-to-End-Testing-Guide.md (100%) rename Firebase-Console-Guide.md => wiki/Firebase-Console-Guide.md (100%) rename Fork-and-Clone-Oppia-Android.md => wiki/Fork-and-Clone-Oppia-Android.md (100%) rename Frequent-Errors-and-Solutions.md => wiki/Frequent-Errors-and-Solutions.md (100%) rename Get-Help.md => wiki/Get-Help.md (100%) rename Gradle--Bazel-Migration-Best-Practices-and-FAQ.md => wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md (100%) rename Guidance-on-submitting-a-PR.md => wiki/Guidance-on-submitting-a-PR.md (100%) rename Home.md => wiki/Home.md (100%) rename Installing-Oppia-Android.md => wiki/Installing-Oppia-Android.md (100%) rename Instructions-for-making-a-code-change.md => wiki/Instructions-for-making-a-code-change.md (100%) rename Internationalization.md => wiki/Internationalization.md (100%) rename Interpreting-CI-Results.md => wiki/Interpreting-CI-Results.md (100%) rename Kotlin-Coroutines.md => wiki/Kotlin-Coroutines.md (100%) rename Ktlint-Guide.md => wiki/Ktlint-Guide.md (100%) rename Oppia's-Mission.md => wiki/Oppia's-Mission.md (100%) rename Oppia-Android-Testing.md => wiki/Oppia-Android-Testing.md (100%) rename Oppia-Bazel-Setup-Instructions.md => wiki/Oppia-Bazel-Setup-Instructions.md (100%) rename Overview-of-the-Oppia-Android-codebase-and-architecture.md => wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md (100%) rename PersistentCacheStore-&-In-Memory-Blocking-Cache.md => wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md (100%) rename Platform-Parameters-&-Feature-Flags.md => wiki/Platform-Parameters-&-Feature-Flags.md (100%) rename RTL-Guidelines.md => wiki/RTL-Guidelines.md (100%) rename Revert-&-regression-policy.md => wiki/Revert-&-regression-policy.md (100%) rename SLoP-2020.md => wiki/SLoP-2020.md (100%) rename Static-Analysis-Checks.md => wiki/Static-Analysis-Checks.md (100%) rename Teams-at-Oppia-Android.md => wiki/Teams-at-Oppia-Android.md (100%) rename Troubleshooting-Installation.md => wiki/Troubleshooting-Installation.md (100%) rename Updating-Maven-Dependencies.md => wiki/Updating-Maven-Dependencies.md (100%) rename Work-Manager.md => wiki/Work-Manager.md (100%) rename Working-on-UI.md => wiki/Working-on-UI.md (100%) rename Writing-design-docs.md => wiki/Writing-design-docs.md (100%) rename _Sidebar.md => wiki/_Sidebar.md (100%) diff --git a/Accessibility-(A11y)-Guide.md b/wiki/Accessibility-(A11y)-Guide.md similarity index 100% rename from Accessibility-(A11y)-Guide.md rename to wiki/Accessibility-(A11y)-Guide.md diff --git a/Background-Processing.md b/wiki/Background-Processing.md similarity index 100% rename from Background-Processing.md rename to wiki/Background-Processing.md diff --git a/Bazel-Setup-Instructions-for-Windows.md b/wiki/Bazel-Setup-Instructions-for-Windows.md similarity index 100% rename from Bazel-Setup-Instructions-for-Windows.md rename to wiki/Bazel-Setup-Instructions-for-Windows.md diff --git a/Buf-Guide.md b/wiki/Buf-Guide.md similarity index 100% rename from Buf-Guide.md rename to wiki/Buf-Guide.md diff --git a/Coding-style-guide.md b/wiki/Coding-style-guide.md similarity index 100% rename from Coding-style-guide.md rename to wiki/Coding-style-guide.md diff --git a/Contributing-to-Oppia-Android.md b/wiki/Contributing-to-Oppia-Android.md similarity index 100% rename from Contributing-to-Oppia-Android.md rename to wiki/Contributing-to-Oppia-Android.md diff --git a/Creating-a-screenshot.md b/wiki/Creating-a-screenshot.md similarity index 100% rename from Creating-a-screenshot.md rename to wiki/Creating-a-screenshot.md diff --git a/Dagger.md b/wiki/Dagger.md similarity index 100% rename from Dagger.md rename to wiki/Dagger.md diff --git a/Dark-Mode.md b/wiki/Dark-Mode.md similarity index 100% rename from Dark-Mode.md rename to wiki/Dark-Mode.md diff --git a/DataProvider-&-LiveData.md b/wiki/DataProvider-&-LiveData.md similarity index 100% rename from DataProvider-&-LiveData.md rename to wiki/DataProvider-&-LiveData.md diff --git a/Dependency-Injection.md b/wiki/Dependency-Injection.md similarity index 100% rename from Dependency-Injection.md rename to wiki/Dependency-Injection.md diff --git a/Developing-skills.md b/wiki/Developing-skills.md similarity index 100% rename from Developing-skills.md rename to wiki/Developing-skills.md diff --git a/End-to-End-Testing-Guide.md b/wiki/End-to-End-Testing-Guide.md similarity index 100% rename from End-to-End-Testing-Guide.md rename to wiki/End-to-End-Testing-Guide.md diff --git a/Firebase-Console-Guide.md b/wiki/Firebase-Console-Guide.md similarity index 100% rename from Firebase-Console-Guide.md rename to wiki/Firebase-Console-Guide.md diff --git a/Fork-and-Clone-Oppia-Android.md b/wiki/Fork-and-Clone-Oppia-Android.md similarity index 100% rename from Fork-and-Clone-Oppia-Android.md rename to wiki/Fork-and-Clone-Oppia-Android.md diff --git a/Frequent-Errors-and-Solutions.md b/wiki/Frequent-Errors-and-Solutions.md similarity index 100% rename from Frequent-Errors-and-Solutions.md rename to wiki/Frequent-Errors-and-Solutions.md diff --git a/Get-Help.md b/wiki/Get-Help.md similarity index 100% rename from Get-Help.md rename to wiki/Get-Help.md diff --git a/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md b/wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md similarity index 100% rename from Gradle--Bazel-Migration-Best-Practices-and-FAQ.md rename to wiki/Gradle--Bazel-Migration-Best-Practices-and-FAQ.md diff --git a/Guidance-on-submitting-a-PR.md b/wiki/Guidance-on-submitting-a-PR.md similarity index 100% rename from Guidance-on-submitting-a-PR.md rename to wiki/Guidance-on-submitting-a-PR.md diff --git a/Home.md b/wiki/Home.md similarity index 100% rename from Home.md rename to wiki/Home.md diff --git a/Installing-Oppia-Android.md b/wiki/Installing-Oppia-Android.md similarity index 100% rename from Installing-Oppia-Android.md rename to wiki/Installing-Oppia-Android.md diff --git a/Instructions-for-making-a-code-change.md b/wiki/Instructions-for-making-a-code-change.md similarity index 100% rename from Instructions-for-making-a-code-change.md rename to wiki/Instructions-for-making-a-code-change.md diff --git a/Internationalization.md b/wiki/Internationalization.md similarity index 100% rename from Internationalization.md rename to wiki/Internationalization.md diff --git a/Interpreting-CI-Results.md b/wiki/Interpreting-CI-Results.md similarity index 100% rename from Interpreting-CI-Results.md rename to wiki/Interpreting-CI-Results.md diff --git a/Kotlin-Coroutines.md b/wiki/Kotlin-Coroutines.md similarity index 100% rename from Kotlin-Coroutines.md rename to wiki/Kotlin-Coroutines.md diff --git a/Ktlint-Guide.md b/wiki/Ktlint-Guide.md similarity index 100% rename from Ktlint-Guide.md rename to wiki/Ktlint-Guide.md diff --git a/Oppia's-Mission.md b/wiki/Oppia's-Mission.md similarity index 100% rename from Oppia's-Mission.md rename to wiki/Oppia's-Mission.md diff --git a/Oppia-Android-Testing.md b/wiki/Oppia-Android-Testing.md similarity index 100% rename from Oppia-Android-Testing.md rename to wiki/Oppia-Android-Testing.md diff --git a/Oppia-Bazel-Setup-Instructions.md b/wiki/Oppia-Bazel-Setup-Instructions.md similarity index 100% rename from Oppia-Bazel-Setup-Instructions.md rename to wiki/Oppia-Bazel-Setup-Instructions.md diff --git a/Overview-of-the-Oppia-Android-codebase-and-architecture.md b/wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md similarity index 100% rename from Overview-of-the-Oppia-Android-codebase-and-architecture.md rename to wiki/Overview-of-the-Oppia-Android-codebase-and-architecture.md diff --git a/PersistentCacheStore-&-In-Memory-Blocking-Cache.md b/wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md similarity index 100% rename from PersistentCacheStore-&-In-Memory-Blocking-Cache.md rename to wiki/PersistentCacheStore-&-In-Memory-Blocking-Cache.md diff --git a/Platform-Parameters-&-Feature-Flags.md b/wiki/Platform-Parameters-&-Feature-Flags.md similarity index 100% rename from Platform-Parameters-&-Feature-Flags.md rename to wiki/Platform-Parameters-&-Feature-Flags.md diff --git a/RTL-Guidelines.md b/wiki/RTL-Guidelines.md similarity index 100% rename from RTL-Guidelines.md rename to wiki/RTL-Guidelines.md diff --git a/Revert-&-regression-policy.md b/wiki/Revert-&-regression-policy.md similarity index 100% rename from Revert-&-regression-policy.md rename to wiki/Revert-&-regression-policy.md diff --git a/SLoP-2020.md b/wiki/SLoP-2020.md similarity index 100% rename from SLoP-2020.md rename to wiki/SLoP-2020.md diff --git a/Static-Analysis-Checks.md b/wiki/Static-Analysis-Checks.md similarity index 100% rename from Static-Analysis-Checks.md rename to wiki/Static-Analysis-Checks.md diff --git a/Teams-at-Oppia-Android.md b/wiki/Teams-at-Oppia-Android.md similarity index 100% rename from Teams-at-Oppia-Android.md rename to wiki/Teams-at-Oppia-Android.md diff --git a/Troubleshooting-Installation.md b/wiki/Troubleshooting-Installation.md similarity index 100% rename from Troubleshooting-Installation.md rename to wiki/Troubleshooting-Installation.md diff --git a/Updating-Maven-Dependencies.md b/wiki/Updating-Maven-Dependencies.md similarity index 100% rename from Updating-Maven-Dependencies.md rename to wiki/Updating-Maven-Dependencies.md diff --git a/Work-Manager.md b/wiki/Work-Manager.md similarity index 100% rename from Work-Manager.md rename to wiki/Work-Manager.md diff --git a/Working-on-UI.md b/wiki/Working-on-UI.md similarity index 100% rename from Working-on-UI.md rename to wiki/Working-on-UI.md diff --git a/Writing-design-docs.md b/wiki/Writing-design-docs.md similarity index 100% rename from Writing-design-docs.md rename to wiki/Writing-design-docs.md diff --git a/_Sidebar.md b/wiki/_Sidebar.md similarity index 100% rename from _Sidebar.md rename to wiki/_Sidebar.md From ccc259e110649f35d85b0632cfd4ccadf016e0ea Mon Sep 17 00:00:00 2001 From: Praneeth Date: Wed, 8 Mar 2023 16:07:43 +0530 Subject: [PATCH 371/374] Add deploy to wiki GitHub Action --- .github/workflows/wiki.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/wiki.yml diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml new file mode 100644 index 00000000000..9714c4fa2e5 --- /dev/null +++ b/.github/workflows/wiki.yml @@ -0,0 +1,23 @@ +name: Deploy to Wiki +on: + push: + branches: + - develop + gollum: + +jobs: + wiki-deploy: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-20.04] + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Add remote + run: | + git filter-branch --subdirectory-filter wiki/ -- -- all + git remote set-url origin https://github.com/oppia/oppia-android.wiki.git + git checkout -b master + git push origin master --force From 12859c10a62b88aa1dc21faa3c5e2a1c505b6f1e Mon Sep 17 00:00:00 2001 From: Praneeth Date: Wed, 8 Mar 2023 16:34:36 +0530 Subject: [PATCH 372/374] Lint fixes --- .github/CODEOWNERS | 3 +++ scripts/assets/todo_open_exemptions.textproto | 22 +++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 20202b40440..7b789f7ecd8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -48,6 +48,9 @@ gradlew.bat @BenHenning /.github/workflows/ @BenHenning /.github/stale.yml @BenHenning +# Wiki +/wiki/ @BenHenning + # Devbots configurations. /.devbots/ @BenHenning diff --git a/scripts/assets/todo_open_exemptions.textproto b/scripts/assets/todo_open_exemptions.textproto index d6d2945190e..8878af6c89b 100644 --- a/scripts/assets/todo_open_exemptions.textproto +++ b/scripts/assets/todo_open_exemptions.textproto @@ -290,3 +290,25 @@ todo_open_exemption { exempted_file_path: "scripts/src/java/org/oppia/android/scripts/todo/model/Todo.kt" line_number: 10 } + +todo_open_exemptions { + exempted_file_path: "wiki/Coding-style-guide.md:" + line_number: 33 +} + +todo_open_exemptions { + exempted_file_path: "wiki/Static-Analysis-Checks.md" + line_number: 33 + line_number: 155 + line_number: 163 + line_number: 168 + line_number: 172 + line_number: 176 + line_number: 178 + line_number: 193 + line_number: 203 + line_number: 206 + line_number: 209 + line_number: 212 + line_number: 215 +} From f16f3963afb1ef05aba4a6dc1c440508ac03b9e9 Mon Sep 17 00:00:00 2001 From: Praneeth Date: Wed, 8 Mar 2023 18:24:41 +0530 Subject: [PATCH 373/374] minor fixes --- .github/workflows/wiki.yml | 2 ++ scripts/assets/todo_open_exemptions.textproto | 4 ++-- wiki/{Oppia's-Mission.md => Oppias-Mission.md} | 0 3 files changed, 4 insertions(+), 2 deletions(-) rename wiki/{Oppia's-Mission.md => Oppias-Mission.md} (100%) diff --git a/.github/workflows/wiki.yml b/.github/workflows/wiki.yml index 9714c4fa2e5..d486156aad7 100644 --- a/.github/workflows/wiki.yml +++ b/.github/workflows/wiki.yml @@ -3,6 +3,8 @@ on: push: branches: - develop + paths: + - 'wiki/**' gollum: jobs: diff --git a/scripts/assets/todo_open_exemptions.textproto b/scripts/assets/todo_open_exemptions.textproto index 8878af6c89b..5c6164fa22c 100644 --- a/scripts/assets/todo_open_exemptions.textproto +++ b/scripts/assets/todo_open_exemptions.textproto @@ -291,12 +291,12 @@ todo_open_exemption { line_number: 10 } -todo_open_exemptions { +todo_open_exemption { exempted_file_path: "wiki/Coding-style-guide.md:" line_number: 33 } -todo_open_exemptions { +todo_open_exemption { exempted_file_path: "wiki/Static-Analysis-Checks.md" line_number: 33 line_number: 155 diff --git a/wiki/Oppia's-Mission.md b/wiki/Oppias-Mission.md similarity index 100% rename from wiki/Oppia's-Mission.md rename to wiki/Oppias-Mission.md From ad25d3a200a80a673bee230a14942ff428825d4f Mon Sep 17 00:00:00 2001 From: Praneeth Date: Wed, 8 Mar 2023 18:57:48 +0530 Subject: [PATCH 374/374] minor fixes --- scripts/assets/todo_open_exemptions.textproto | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scripts/assets/todo_open_exemptions.textproto b/scripts/assets/todo_open_exemptions.textproto index 5c6164fa22c..34352a5fca0 100644 --- a/scripts/assets/todo_open_exemptions.textproto +++ b/scripts/assets/todo_open_exemptions.textproto @@ -292,13 +292,12 @@ todo_open_exemption { } todo_open_exemption { - exempted_file_path: "wiki/Coding-style-guide.md:" + exempted_file_path: "wiki/Coding-style-guide.md" line_number: 33 } todo_open_exemption { exempted_file_path: "wiki/Static-Analysis-Checks.md" - line_number: 33 line_number: 155 line_number: 163 line_number: 168