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

Fix #1820 : How to approach Bugs? - Documentation #4957

Merged
merged 5 commits into from
Apr 26, 2023
Merged

Fix #1820 : How to approach Bugs? - Documentation #4957

merged 5 commits into from
Apr 26, 2023

Conversation

MohitGupta121
Copy link
Member

@MohitGupta121 MohitGupta121 commented Apr 22, 2023

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

Copy link
Member Author

@MohitGupta121 MohitGupta121 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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
Copy link
Member Author

@gp201 Please you also add your suggestions.
Thanks.

@gp201
Copy link
Member

gp201 commented Apr 23, 2023

@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
Copy link
Member

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
Copy link
Member Author

MohitGupta121 commented Apr 25, 2023

@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
Copy link
Member

@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
Copy link
Member Author

MohitGupta121 commented Apr 25, 2023

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

@seanlip
Copy link
Member

seanlip commented Apr 25, 2023

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

Copy link
Member

@seanlip seanlip left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @MohitGupta121, left some suggestions.

wiki/Debugging.md Outdated Show resolved Hide resolved
wiki/Debugging.md Outdated Show resolved Hide resolved
@seanlip seanlip assigned MohitGupta121 and unassigned seanlip Apr 25, 2023
Copy link
Member Author

@MohitGupta121 MohitGupta121 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@seanlip seanlip left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@seanlip seanlip merged commit 7e25274 into oppia:develop Apr 26, 2023
@MohitGupta121 MohitGupta121 deleted the debugging_wiki_approach branch April 26, 2023 12:11
@MohitGupta121
Copy link
Member Author

@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
Copy link
Member

seanlip commented Apr 28, 2023

@MohitGupta121 Yes please go ahead. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

How to approach Bugs? - Documentation
4 participants