A Beginner's Guide to Debugging

To get straight to the point, let me share some lessons I’ve picked up recently while diving into open source contributions and working on bug fixes:

So, you spot an issue you want to work on that (ideally) has a detailed description of the problem and steps to reproduce the bug. You signal that you want to work on it, but then what?

How do you actually get started?

1. Search Existing Issues First, search all existing issues or tickets—both closed and open—to see if someone has worked on a similar problem, what they changed, and how they did it.

   For example, I once had to fix a bug where API queries were returning truncated responses. The solution involved implementing a mechanism to continue requesting data until all responses were fully retrieved.

   The first thing I did was check the API documentation, which is always a good starting point. However, the docs were lacking; there were no code examples or detailed explanations of how to implement the continuation logic. I spent hours trying to figure it out, growing increasingly frustrated. And frustration, I’ve learned, is a red flag—too much of it clouds my brain and slows my progress.

   I took a break, and the next day, I decided to check past issues to see if anyone had implemented a similar solution. Sure enough, I found an example, copied the logic, and tweaked it for my needs.

   Lesson learned: I wasted hours, when I could have just checked the past issues to start with. Searching past issues can be a hit or miss, but it’s fundamental to check anyway.

2. Inspect Elements on a Website If your issue is web-based, use the browser's Inspect tool (especially Chrome DevTools) to dig into the page. Modify elements, check network requests, and analyze headers or responses as needed. In my opinion, Chrome DevTools is one of the most underrated debugging tools. Using this, you can identify the classes, methods, variables, or requests relevant to your bug and then search the codebase for them.

3. Leverage Codebase Search Tools Once in the codebase, the search functionality is your best friend. Use it to locate files, methods, or anything relevant. If your search is complex, apply search filters or even use regex to tailor your search more precisely.

4. Don’t Be Afraid to Use AI If you need help understanding a block of code, feel free to ask an AI tool to explain it—just make sure you’re not violating your company’s policies or exposing any sensitive or private code.

5. If you’re lucky and find a fix soon enough, congrats! But here’s a mini tip: There are always multiple ways to solve a problem. Pick one approach, follow it to the end, and if it doesn’t work, move on—but document everything. Whether you use Word, Notion, or draft comments on GitHub, keep track of your efforts. For example, this is a snippet of a GitHub comment I have made on an issue:

The following are steps I have taken in investigating the bug: 

1. I utilized the [WikiTemplate UDL tool](https://en.wikipedia.org/wiki/User:Equazcion/WikiTemplate_UDL) to compare the wikitexts (both the `wikitext` and the `parser.extended_wiki_text` of affected and unaffected pages, confirming no significant differences in template formats.

2. I attempted the following actions without success:
   - Adding an additional action=expandtemplates request to the handler and utils .py to make a call to the mediawiki expand templates action first to expand all the templates in the wikitext and then pass the result from that to the action=parse, but it did not resolve the issue.
   - Increasing the request header timeout from 0 to 180 seconds, which also yielded no improvements.
   - Modifying the `default_task_soft_time_limit` in `deployment/celery_config.py` from 120 to 300 seconds, yet no change was observed.
   - Uncommenting redundant markup for `<ref>` tags in the markup file, which had no impact.

3. I also utilized the [Wikipedia Special:ExpandTemplates](https://en.wikipedia.org/wiki/Special:ExpandTemplates) tool with both the wikitext and the expanded wikitext (including injected editor tokens) of a buggy page. The templates in the response expanded correctly with both of the input wikitexts, indicating that the injected editor tokens are not likely to be responsible for the problem.

In conclusion, I cannot pinpoint a cause because:

1. If the cause is attributed to parsing logic, I found no evidence supporting this claim, as the same dashboard logic works on other pages, and templates expand properly using the Special:ExpandTemplates tool.
2. If the cause is attributed to excessive template usage and citations, the same page with the same templates and citations renders correctly on Wikipedia and also the initial parsed article view.
3. If the cause is attributed to timeouts, increasing request timeout and task limits did not yield any improvements.

6. Write Tests to Validate Your Fix Writing tests is crucial. For example, in the API issue I mentioned, I had to create tests to ensure my solution returned full, untruncated responses. My initial test was subpar, but with the guidance of a reviewer, it improved dramatically. Here’s some precious advice my reviewer and potential mentor shared:

   A good test is one where it's very hard to break the corresponding code without also causing the test to fail, but here we could make any any sort of changes to the API code (that would affect the results of the test) without breaking this test.“

   This feedback was a clear sign that I needed to learn more about writing strong tests. I’m planning to read a book on the topic to improve.

7. Branch Management and Commit Etiquette Once you’ve got your solution, make a branch, commit your changes, and open a PR. Follow any commit message guidelines that are standard in your project or this.

   I have a bad habit: I fear creating branches I won’t end up using, so I’d start making changes directly on main or master and then switch later. It works but is unnecessarily tedious, especially in larger codebases. Proper branching saves you from painful rebasing and conflicts.

   For example, in one of the projects I work on, the workflow requires:

    git checkout master
    git fetch upstream
    git merge upstream/master
    git checkout branch-name
    git rebase master
   

   If you skip any steps (like I once did with the rebase), you may face merge conflicts. Thankfully, tools like ChatGPT / a simple google search can guide you through resolving these. Still, it’s better to avoid the hassle.

8. Run Tests and Linters Locally Before pushing your changes, run all tests and linting tools locally to catch any issues. Trust me, you don’t want to get an email about a failed CI/CD build because of a trailing whitespace or a broken test. It’s a rookie mistake. It can happen once, maybe twice, but the third time, It just shows carelessness.

9. Make Your PRs Reviewer-Friendly Use any provided PR templates and fill them out thoroughly. Include as many relevant screenshots as possible and explain your changes clearly. Use descriptive PR titles and commit messages. If your work is ongoing, create a draft PR.

Final Tips

• Your job isn’t done after opening the PR. The review may come at any moment, and you should expect back-and-forth with the reviewer. Appreciate their feedback; they’re often senior engineers offering their valuable time to guide you. I started working on an issue Nov 6th but it was only merged and accepted on Nov 15th after numerous changes and multiple PRs closed and opened. My experience working on the issue prompted me to write this article to share the lessons I learned.

• Consider sharing your proposed changes as comments and get the go ahead before committing. This keeps your commit history clean and organized, for example there’s no reason a simple bug fix should have like 10 commits all changing minor things.

• In the end, remember: taking breaks is not just good advice—it’s essential. When you’re frustrated, a walk or a quick nap can clear your mind and help you return with a fresh perspective.

That’s all I can think of right now. If you read this till the end, I hope you have learned something useful! 😊✨