Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create separate debugging-doc wiki page for oppia-android #4974

Merged
merged 3 commits into from
May 15, 2023
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions wiki/Debugging-Docs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
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.

**Note:** In general, we strongly recommend writing and sharing a debugging doc if you can't figure out a solution to a problem within the **first 2 hours** of working on it.

## Table of Contents

- [Benefits](#benefits)
- [How to Write a Debugging Doc](#how-to-write-a-debugging-doc)
- [1. Begin with Describing What Goes Wrong](#1-begin-with-describing-what-goes-wrong)
- [2. Describe Your Investigations](#2-describe-your-investigations)
- [3. Document Your Guesses and Testing](#3-document-your-guesses-and-testing)
- [4. Continue/Review from Mentor](#4-continuereview-from-mentor)
- [5. Document Your Solution](#5-document-your-solution)
- [Get Started](#get-started)

## 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.

Finally, these documents can serve as records of debugging strategies and bug causes that we can reference later on. For example, we might search these debugging docs for an error message we are encountering to see if it has been fixed before.

## 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) to get started.
3 changes: 2 additions & 1 deletion wiki/Debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,5 @@ Generally, finding the root cause of a bug is a question of strategically checki
3. Based on the environment you've identified in steps 1 + 2, write a test case which the bug causes to fail (if one doesn't already exist). This gives you an automatic way to check whether or not the bug is fixed.
4. Then, work towards the solution, until the test case you wrote in step 3 passes.

Unless the bug you are trying to fix is trivial, we strongly recommend creating a debugging doc to organize your work. You can use this debugging doc to write down any pertinent information about the issue and to organize your debugging process, and it will make it much easier to ask for help from others since all the necessary information is there. You can find more guidance [here](https://github.com/oppia/oppia-android/wiki/Get-Help#before-you-ask-a-general-question) on how to write a debugging doc.
Unless the bug you are trying to fix is trivial, we recommend creating a debugging doc to organize your work:
seanlip marked this conversation as resolved.
Show resolved Hide resolved
- [Debugging Docs](https://github.com/oppia/oppia-android/wiki/Debugging-Docs)
27 changes: 1 addition & 26 deletions wiki/Frequent-Errors-and-Solutions.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,29 +30,4 @@ To solve this
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.
Follow the guidelines outlined on this [wiki page](https://github.com/oppia/oppia-android/wiki/Debugging).
6 changes: 3 additions & 3 deletions wiki/Get-Help.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,9 @@ 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). For more information on how to prepare a debugging doc, follow the guidelines provided on [this wiki page](https://github.com/oppia/oppia-android/wiki/Frequent-Errors-and-Solutions#how-to-write-a-debugging-doc).
* 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.
- 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 [the guidelines provided on the wiki page](https://github.com/oppia/oppia-android/wiki/Debugging-Docs).
seanlip marked this conversation as resolved.
Show resolved Hide resolved
- 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.
seanlip marked this conversation as resolved.
Show resolved Hide resolved

### How to ask a general question

Expand Down
1 change: 1 addition & 0 deletions wiki/_Sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
* [Accessibility Guide](https://github.com/oppia/oppia-android/wiki/Accessibility-A11y-Guide)
* [Debugging](https://github.com/oppia/oppia-android/wiki/Debugging)
* [How do I find the root cause of a bug?](https://github.com/oppia/oppia-android/wiki/Debugging#How-do-I-find-the-root-cause-of-a-bug)
* [Debugging Docs](https://github.com/oppia/oppia-android/wiki/Debugging-Docs)
* [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)
Expand Down