Fix #1820 : How to approach Bugs? - Documentation

[MohitGupta121]

Explanation

Fix #1820 : How to approach Bugs? - Documentation

Essential Checklist

• 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 files have their rationale included in the PR explanation.
• The PR follows the style guide.
• The PR does not contain any unnecessary code changes from Android Studio (reference).
• 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).

For UI-specific PRs only

If your PR includes UI-related changes, then:

• Add screenshots for portrait/landscape for both a tablet & phone of the before & after UI changes
• For the screenshots above, include both English and pseudo-localized (RTL) screenshots (see RTL guide)
• Add a video showing the full UX flow with a screen reader enabled (see accessibility guide)
• Add a screenshot demonstrating that you ran affected Espresso tests locally & that they're passing

[MohitGupta121]

@seanlip @BenHenning PTAL,
I added this wiki from taking inspiration from the debugging wiki of oppia-web, if we see oppia-web debugging it contains different approaches for different common bugs that contributor faces.
Oppia-web also has a complete guide to writing debugging-doc.

So I think this is a good start to Debugging wiki for android, after this, we can directly add-on or link different debugging techniques for different features, and "Guide for writing debugging-doc for oppia-android" directly into this particular "Debugging" wiki for oppia-android.

Please suggest to me if we can do this more effectively or what we can add more.
We can make separate issues for that or just update the current issue #1820

Thanks.

[MohitGupta121]

@gp201 Please you also add your suggestions.
Thanks.

[gp201]

@MohitGupta121 Can we add a section for how to debug CI tests and a section about how to write debugging docs similar to what we have in the Oppia wiki https://github.com/oppia/oppia/wiki/Debugging

@BenHenning What do you think?

[BenHenning]

Thanks @MohitGupta121! I'll need to take a pass on this a bit later in the week.

@MohitGupta121 Can we add a section for how to debug CI tests and a section about how to write debugging docs similar to what we have in the Oppia wiki https://github.com/oppia/oppia/wiki/Debugging

@BenHenning What do you think?

@gp201 @MohitGupta121 I think suggestions on how to investigate CI issues is a good idea. Re: the debugging doc, could we maybe just link to Oppia web's page on it? It seems preferable not to duplicate work since that way we can keep the docs fresher by just having to update one source. Could that work?

[MohitGupta121]

@BenHenning Thanks,
Also have one question that me and @gp201 have in meeting, what exactly the issue #1820 by Rajat supposed to target ( Is it a general blockage that contributor face while working on issue? Or something else like Tests debug?, etc )

I think @BenHenning you know the proper plan of this particular issue?

[BenHenning]

@BenHenning Thanks, Also have one question that me and @gp201 have in meeting, what exactly the issue #1820 by Rajat supposed to target ( Is it a general blockage that contributor face while working on issue? Or something else like Tests debug?, etc )

I think @BenHenning you know the proper plan of this particular issue?

@MohitGupta121 The issue is a bit old, but I still see the need for it. I think the idea is to provide specific suggestions for how to do each of the steps listed in #1820. For example for step (1), we could provide instructions on how to interpret the most common types of errors (some types: a build failure, a test failure, something not updating in the UI, etc.) and how to interpret and then debug those.

It might be worthwhile to ask around the team to get an idea on the most common issues people run into (especially during onboarding) so that we can catalog those types and focus on those.

Does this help clarify?

[MohitGupta121]

Yes thanks @BenHenning , I think this much more clear now.

[seanlip]

Re #4957 (comment):

@MohitGupta121 Can we add a section for how to debug CI tests and a section about how to write debugging docs similar to what we have in the Oppia wiki https://github.com/oppia/oppia/wiki/Debugging

... Re: the debugging doc, could we maybe just link to Oppia web's page on it? It seems preferable not to duplicate work since that way we can keep the docs fresher by just having to update one source. Could that work?

I think here I actually lean towards the Android team having their own format and documentation for debugging docs (which could initially be seeded from Web). One of the things I want to do in the longer term is make the debugging doc for Web call out specific Web things, so that it can be more like a debugging recipe. My expectation is that Web/Android will diverge here in the recommended "here are the first things you should do", and we do want to try and be prescriptive here since it helps newer contributors. So my suggestion is to make a copy and not worry about keeping both of these in sync in the long run since I don't think there's a case where Web folks will ever need to look at the Android debugging docs, and vice versa (and I also think the docs will, in the long run, end up being 80% different in terms of content).

[seanlip]

Thanks @MohitGupta121, left some suggestions.

[MohitGupta121]

Thanks @seanlip, PTAL.
Updated the review changes requested.

[seanlip]

Thanks @MohitGupta121, no concerns from my end, but we should monitor the use of this and see if it actually helps developers. If not, let's try to update the docs to help get them unstuck more easily (maybe with examples / case studies).

[MohitGupta121]

@seanlip Thanks, Yes I will take monitor on that particular doc and take feedbacks from new contributors. Also what ever new technique we find for debugging such as for Bazel, Dark-mode or any specific thing we can directly link it to this wiki.

Also I talk to @BenHenning in last meeting and he suggest to make new Debugging Doc similar to that of oppia-web but with changes in screenshots and some web related stuff. Otherwise most of the debugging-wiki is good to have in Android.
But it is good to have Android separate debugging-doc wiki.
So @BenHenning @seanlip can I go ahead with android version of Debugging-Doc wiki?

Thanks.

[seanlip]

@MohitGupta121 Yes please go ahead. Thanks!