Update our debugging instructions. (#406)

* Update our debugging instructions. * Further updates to make debugging docs more prominent * Clarify starter instructions. * Fix plurals * Fix alt text
oppia · Dec 7, 2024 · 7167812 · 7167812
1 parent 78faf70
commit 7167812
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 113 deletions.
diff --git a/Contributing-code-to-Oppia.md b/Contributing-code-to-Oppia.md
@@ -40,7 +40,7 @@ Additionally, GitHub also provides an advanced search syntax that allows you to
 
 3. Say hi and introduce yourself on [GitHub Discussions](https://github.com/oppia/oppia/discussions/16715)!
 
-4. Install Oppia following the [[installation instructions|Installing-Oppia]]. If you run into any issues, please check out the [[troubleshooting instructions|Troubleshooting]]. If you want help setting up a code editor, also check out our [[guide to common IDEs|Tips-for-common-IDEs]]. If the above resources don't help and you're still stuck, please check [GitHub Discussions](https://github.com/oppia/oppia/discussions/categories/q-a-installation) to see if any existing threads address the issue. If not, feel free to start a new thread explaining what you've tried and what you're seeing, so that we can try and help you!
+4. Install Oppia following the [[installation instructions|Installing-Oppia]]. If you run into any issues, please check out the [[troubleshooting instructions|Troubleshooting]]. If you want help setting up a code editor, also check out our [[guide to common IDEs|Tips-for-common-IDEs]]. If the above resources don't help and you're still stuck, please check [GitHub Discussions](https://github.com/oppia/oppia/discussions/categories/q-a-installation) to see if any existing threads address the issue. If not, feel free to start a new thread explaining what you've tried and what you're seeing, so that we can try and help you! (You will probably get a faster response if you include a [[debugging doc|Debugging-Docs]] explaining what local investigations you have tried so far.)
 
 5. Update your GitHub settings:
 
@@ -103,7 +103,8 @@ When you've found a good first issue you'd like to tackle, please investigate it
 
 Once you have a good understanding of the issue, you can ask for it to be assigned to you by leaving a comment as follows:
 
-- Show a video of the fix working correctly on your local machine. (For user-facing changes, your video should show a URL that starts with localhost:8181.)
+- Show a video of the fix working correctly on your local machine. (For user-facing changes, your video should show a URL that starts with localhost:8181.) When creating a video, make sure to follow exactly the same steps as the issue author did in their video/description, so that your video can be compared to theirs to confirm that it fixes the problem.
+- (If fixing a bug) Explain clearly what the **root cause** of the bug is, pointing to specific lines of code in the Oppia codebase if needed.
 - Explain clearly what you did to tackle the issue (at a minimum, point to which file(s) you modified and describe the changes you made). You can include code snippets if you like.
 - @-mention the leads of the corresponding project (you can find their details [here](https://github.com/orgs/oppia/projects)), letting them know you'd like to work on it and when you can submit a PR by.
 

diff --git a/Debugging-Docs.md b/Debugging-Docs.md
@@ -1,23 +1,16 @@
-If you're running into an issue that you have trouble solving, you might find it useful to keep a record of your debugging process so that you can easily organize your thoughts and get help from other members of the team. The format we use for this is called a "debugging doc".
+At Oppia, we use debugging docs to compile all the investigation that has been done on an issue that we're facing, so that others can understand the background of the issue and what has been tried before.
 
-To get started, make a copy of [this "debugging doc" template](https://docs.google.com/document/d/1qRbvKjJ0A7NPVK8g6XJNISMx_6BuepoCL7F2eIfrGqM/edit?usp=sharing) and fill it in. If you're new to debugging, filling out as much of this template as you can is a great way to practice and improve your debugging skills. In general, we strongly recommend writing and sharing a debugging doc if you can't figure out the solution to a problem after working on it for **30 minutes**.
+If you plan to ask for help from the community, creating a debugging doc is **necessary**. This provides a record of your debugging process so that you can organize your thoughts, and also helps avoid long back-and-forths to determine what the issue actually is.
 
-Once you've filled out the "Background" and "Initial investigation" parts of the template, share the debugging doc in your team's group chat or the relevant issue thread, so that others can look at it in parallel. Then, continue working on the "Hypotheses Testing" section (search the Internet, narrow down the problem window, etc.) and fill out as much of it as you can.
+To get started, make a copy of [this "debugging doc" template](https://docs.google.com/document/d/1qRbvKjJ0A7NPVK8g6XJNISMx_6BuepoCL7F2eIfrGqM/edit) and fill it in, then post it to the ['Debugging Docs' category on GitHub Discussions](https://github.com/oppia/oppia/discussions/categories/q-a-debugging-docs). If you're new to debugging, filling out as much of this template as you can is a great way to practice and improve your debugging skills.
 
-When it's not clear what to do further, please ask for help immediately on your team chat or [GitHub Discussions](https://github.com/oppia/oppia/discussions). Note that, at this stage, reviewers will reasonably expect, at minimum, at least one hypothesis to be proposed and under investigation.
+In general, we strongly recommend writing and sharing a debugging doc if you can't figure out the solution to a problem after working on it for **30 minutes**. Note that, at this stage, reviewers will reasonably expect, at minimum, at least one hypothesis to be proposed and under investigation.
 
 
 ## 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. For example, one time a member of the Automated QA team was debugging an end-to-end test flake. The flake was blocking nearly all PRs from being merged, but the member had to go to sleep before they could figure it out. They sent the [debugging doc](https://docs.google.com/document/d/1LAsDc1EMISjpwnn-FcdH-7TNrU20xfkJEO3uSLj_nyM/edit#heading=h.jl2gn54iqprw) to another contributor who read through the document and quickly spotted a problem. They worked with another team member to have a PR up to fix the issue before the first member woke up the next morning! The debugging doc made it easy for team members to hand the bug off and get it fixed fast.
+Debugging docs also make it easy for you to bring someone else up to speed on your bug. For example, once, a member of the dev workflow team was debugging an end-to-end test flake which was blocking nearly all PRs from being merged, but they had to go to sleep before they could figure it out. They sent the debugging doc to another contributor who read through the document, quickly spotted a problem, and worked with another team member to create a PR up to fix the issue before the first member woke up the next morning! The debugging doc made it easy for team members to hand the bug off and get it fixed fast.
 
 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.
-
-## Examples
-
-To see these debugging docs in action, check out these examples:
-
-* [2021-02-08 E2E Flake: session deleted because of page crash](https://docs.google.com/document/d/1LAsDc1EMISjpwnn-FcdH-7TNrU20xfkJEO3uSLj_nyM/edit#heading=h.jl2gn54iqprw)
-* [2020-12-23 E2E Flake: Skill Editor is Taking Too Long to Appear](https://docs.google.com/document/d/1cI8fqAIFqsmZj5v35y49ohhNvgmE0_vH_sT02Aws77Y/edit?usp=sharing)
diff --git a/Debugging.md b/Debugging.md
@@ -2,17 +2,16 @@ We do a lot of debugging at Oppia, whether because tests are failing on a PR or
 
 Start here if failing tests are stopping you from pushing or merging a PR:
 
-* [[If your presubmit checks fail|If-your-presubmit-check-fails]]
+* [[If your local presubmit checks fail|If-your-presubmit-check-fails]]
 * [[If CI checks fail on your PR|If-CI-checks-fail-on-your-PR]]
 
-Unless the bug you are trying to fix is trivial, we recommend creating a debugging doc to organize your work:
+Unless the bug you are trying to fix is trivial, we recommend creating a debugging doc to organize your work. This **must be done** if you plan to ask for help from the community:
 
 * [[Debugging Docs|Debugging-Docs]]
 
 Here are some debugging guides for particular kinds of issues you might encounter or types of tests:
 
-* [[Interpreting GitHub Actions Results|Interpreting-GitHubActions-Results]]
-* [[Finding the commit that introduced a bug|How-to-find-the-commit-which-introduced-a-bug]]
+* [[Finding which commit introduced a bug|How-to-find-the-commit-which-introduced-a-bug]]
 * [[Debugging end-to-end tests|Debug-end-to-end-tests]]
 * [[Debugging backend tests|Debug-backend-tests]]
 * [[Debugging frontend tests|Debug-frontend-tests]]