From ff0dffc4addb9c20f3d07fc7ddd74b382a522a2b Mon Sep 17 00:00:00 2001 From: MOHIT GUPTA <76530270+MohitGupta121@users.noreply.github.com> Date: Fri, 20 Oct 2023 18:21:28 +0530 Subject: [PATCH] Fix #5192, #4610 : [Developer Video] Understanding CI check failures & Replace wiki broken links (#5199) ## Explanation Fix #5192, #4610 : [Developer Video] Understanding CI check failures & Replace Wiki broken links This PR include developer video that explains how to handle failures in our Continuous Integration (CI) checks in oppia-android. It also includes the replacement of broken links in our Wiki, improving the documentation for a smoother developer experience. ## Essential Checklist - [x] 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. - [x] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide). - [x] 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)). - [x] The PR is made from a branch that's **not** called "develop" and is up-to-date with "develop". - [x] 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)). --- scripts/assets/todo_open_exemptions.textproto | 24 +++++++++---------- wiki/Accessibility-A11y-Guide.md | 2 +- wiki/Bazel-Setup-Instructions-for-Windows.md | 2 +- wiki/Buf-Guide.md | 2 +- wiki/Developing-skills.md | 4 ++-- wiki/Guidance-on-submitting-a-PR.md | 2 +- wiki/Instructions-for-making-a-code-change.md | 6 ++--- wiki/Interpreting-CI-Results.md | 8 +++++++ wiki/Ktlint-Guide.md | 2 +- wiki/RTL-Guidelines.md | 1 - wiki/Static-Analysis-Checks.md | 4 ++++ wiki/Troubleshooting-Installation.md | 2 +- wiki/Updating-Maven-Dependencies.md | 2 +- wiki/Work-Manager.md | 6 ++--- 14 files changed, 39 insertions(+), 28 deletions(-) diff --git a/scripts/assets/todo_open_exemptions.textproto b/scripts/assets/todo_open_exemptions.textproto index 0fa81fd297d..cb81317adae 100644 --- a/scripts/assets/todo_open_exemptions.textproto +++ b/scripts/assets/todo_open_exemptions.textproto @@ -294,16 +294,16 @@ todo_open_exemption { todo_open_exemption { exempted_file_path: "wiki/Static-Analysis-Checks.md" - line_number: 170 - line_number: 178 - line_number: 183 - line_number: 187 - line_number: 191 - line_number: 193 - line_number: 208 - line_number: 218 - line_number: 221 - line_number: 224 - line_number: 227 - line_number: 230 + line_number: 171 + line_number: 179 + line_number: 184 + line_number: 188 + line_number: 192 + line_number: 194 + line_number: 209 + line_number: 219 + line_number: 222 + line_number: 225 + line_number: 228 + line_number: 231 } diff --git a/wiki/Accessibility-A11y-Guide.md b/wiki/Accessibility-A11y-Guide.md index 54e713469f4..a9e01c6c59e 100644 --- a/wiki/Accessibility-A11y-Guide.md +++ b/wiki/Accessibility-A11y-Guide.md @@ -95,7 +95,7 @@ TalkBack is the Google **screen reader** included on Android devices. TalkBack g * [Presentation Slides](https://docs.google.com/presentation/d/17SeKJLKT-rUNa_Yupe97bMFSsjTNzp83jX-lZPKEtnQ/edit?usp=sharing) ## 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. +[AccessibilityTestRule](https://github.com/oppia/oppia-android/blob/develop/testing/src/main/java/org/oppia/android/testing/OppiaTestRule.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**) diff --git a/wiki/Bazel-Setup-Instructions-for-Windows.md b/wiki/Bazel-Setup-Instructions-for-Windows.md index 42c564c51fb..7a72fa86c34 100644 --- a/wiki/Bazel-Setup-Instructions-for-Windows.md +++ b/wiki/Bazel-Setup-Instructions-for-Windows.md @@ -14,7 +14,7 @@ ## Overview & Disclaimer -This page outlines one way to allow Bazel to be used in CLI form on Windows. Please note that **this support is currently experimental**. You may run into some problems--we suggest that you [file an issue](https://github.com/oppia/oppia-android/issues/new/choose) ior contact us at [gitter](https://gitter.im/oppia/oppia-android). +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) or contact us at [github-discussions](https://github.com/oppia/oppia-android/discussions). 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. diff --git a/wiki/Buf-Guide.md b/wiki/Buf-Guide.md index 895e2de625a..184c747e033 100644 --- a/wiki/Buf-Guide.md +++ b/wiki/Buf-Guide.md @@ -5,7 +5,7 @@ - [Configuration File](#configuration-file) # 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.
+Once you have completed all the [installation steps](https://github.com/oppia/oppia-android/wiki/Installing-Oppia-Android), you will have a `buf` file in your `opensource/oppia-android-tools` folder.
**Note: Currently, Buf is not available for windows.** ## Commands diff --git a/wiki/Developing-skills.md b/wiki/Developing-skills.md index 562b07e321e..fab285b222c 100644 --- a/wiki/Developing-skills.md +++ b/wiki/Developing-skills.md @@ -7,11 +7,11 @@ That said, we strongly recommend that you be open to learning new things. If you - [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. + - [Introduction to GitHub](https://learn.microsoft.com/en-us/training/modules/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. + - GitHub's [managing merge conflicts page](https://github.com/skills/resolve-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. diff --git a/wiki/Guidance-on-submitting-a-PR.md b/wiki/Guidance-on-submitting-a-PR.md index 5f7541e70f9..0124b44eb90 100644 --- a/wiki/Guidance-on-submitting-a-PR.md +++ b/wiki/Guidance-on-submitting-a-PR.md @@ -1,5 +1,5 @@ **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) +- The free series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/courses/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). Here are the steps for making a PR to the Oppia Android codebase: diff --git a/wiki/Instructions-for-making-a-code-change.md b/wiki/Instructions-for-making-a-code-change.md index ca91ee920ff..850f252220c 100644 --- a/wiki/Instructions-for-making-a-code-change.md +++ b/wiki/Instructions-for-making-a-code-change.md @@ -1,12 +1,12 @@ **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). +**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/courses/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.* +*If your change isn't trivial, please talk to us via [github-discussions](https://github.com/oppia/oppia-android/discussions) 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. +You might also find this reference for the [Android Studio 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) 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: diff --git a/wiki/Interpreting-CI-Results.md b/wiki/Interpreting-CI-Results.md index b0135d27293..2adf2685b53 100644 --- a/wiki/Interpreting-CI-Results.md +++ b/wiki/Interpreting-CI-Results.md @@ -1,3 +1,8 @@ +## Table of Contents + +- [How to find the error message for a Failing CI check](#how-to-find-error-message-for-failing-ci-checks) +- [Developer Video - Understanding CI check failures](#developer-video---understanding-ci-check-failures) + ## 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. @@ -14,3 +19,6 @@ Example in the below check the second job has some error or failure Navigate to logs or search the keyword ‘error’ to find the error message to understand what might have caused the failure in the checks. + +### Developer Video - Understanding CI check failures +Learn how to interpret and troubleshoot oppia-android CI check failures in this insightful [developer video](https://youtu.be/I2bRf6fvgJ0?si=35sAagbUFSk6bOBA). \ No newline at end of file diff --git a/wiki/Ktlint-Guide.md b/wiki/Ktlint-Guide.md index 9c1b4c11549..83f27e8dd0c 100644 --- a/wiki/Ktlint-Guide.md +++ b/wiki/Ktlint-Guide.md @@ -7,7 +7,7 @@ - [How to fix the most common issues?](#how-to-fix-the-most-common-issues) # 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. +Once you have completed all the [installation steps](https://github.com/oppia/oppia-android/wiki/Installing-Oppia-Android), you will have a `ktlint` file in your `opensource/oppia-android-tools` folder. # Commands diff --git a/wiki/RTL-Guidelines.md b/wiki/RTL-Guidelines.md index dc004760827..cd16760ecd4 100644 --- a/wiki/RTL-Guidelines.md +++ b/wiki/RTL-Guidelines.md @@ -51,5 +51,4 @@ 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) diff --git a/wiki/Static-Analysis-Checks.md b/wiki/Static-Analysis-Checks.md index a3d350fedf9..e4252c7c445 100644 --- a/wiki/Static-Analysis-Checks.md +++ b/wiki/Static-Analysis-Checks.md @@ -12,6 +12,7 @@ - [TODO open checks](#todo-open-checks) - [TODO issue resolved check](#todo-issue-resolved-check) - [How to run static checks locally](#how-to-run-static-checks-locally) + - [Developer Video - Understanding CI check failures](#developer-video---understanding-ci-check-failures) # 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. @@ -241,3 +242,6 @@ To fix failing tests from GitHub CI individually, follow the steps below. - You can also go to scripts/static_checks.sh to view the failing check and run it locally. Note: Before running the script command in your local terminal, make sure you have Bazel installed. To learn how to set up Bazel for Oppia Android, follow these [instructions](https://github.com/oppia/oppia-android/wiki/Oppia-Bazel-Setup-Instructions). Also make sure you have oppia-android-tools installed since static checks rely on these tools to be able to perform some of the checks. To install oppia-android-tools, run `bash scripts/setup.sh` in the oppia-android directory. + +### Developer Video - Understanding CI check failures +Learn how to interpret and troubleshoot oppia-android CI check failures in this insightful [developer video](https://youtu.be/I2bRf6fvgJ0?si=35sAagbUFSk6bOBA). \ No newline at end of file diff --git a/wiki/Troubleshooting-Installation.md b/wiki/Troubleshooting-Installation.md index d88c4bf01ad..a05144fa2ed 100644 --- a/wiki/Troubleshooting-Installation.md +++ b/wiki/Troubleshooting-Installation.md @@ -14,7 +14,7 @@ Here are some general troubleshooting tips for oppia-android. The specific platf 2. If you find any error which says `java: command not found`, please check you have Java installed correctly in your machine and the [environment path variable](https://www.java.com/en/download/help/path.html) is also set up correctly. -3. If you find any error related to Kotlin or Java/Checkstyle while pushing the code, please check [this link](https://github.com/oppia/oppia-android/wiki/Android-Studio-UI-based-Github-workflow#how-to-fix-push-failures). +3. If you find any error related to Kotlin or Java/Checkstyle while pushing the code, please check [this link](https://github.com/oppia/oppia-android/wiki/Frequent-Errors-and-Solutions#push-failed). 4. If you see the error diff --git a/wiki/Updating-Maven-Dependencies.md b/wiki/Updating-Maven-Dependencies.md index cb08415d296..6e0653f844b 100644 --- a/wiki/Updating-Maven-Dependencies.md +++ b/wiki/Updating-Maven-Dependencies.md @@ -70,7 +70,7 @@ If the link does point to a valid license then choose the most appropriate categ 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 can not be scraped directly from the original_link of the license. - e.g - https://www.opensource.org/licenses/bsd-license + e.g - https://opensource.org/license/bsd-3-clause 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 diff --git a/wiki/Work-Manager.md b/wiki/Work-Manager.md index bcede9e03f2..2547ee7b457 100644 --- a/wiki/Work-Manager.md +++ b/wiki/Work-Manager.md @@ -34,8 +34,8 @@ There are a few WorkManager classes you need to know about: 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) +- 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-web-developer-docs/blob/develop/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-web-developer-docs/blob/develop/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 : @@ -168,4 +168,4 @@ In Oppia we write tests for both the Worker and its Initializer class. You can t 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 +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/LogReportWorkManagerInitializerTest.kt)* \ No newline at end of file