Hello NVDA users, A few days ago I promised to the community that I will talk about things developers are looking for when we (NV Access and interested third parties) review GitHub issues for NVDA screen reader. Originally planned for last week, I didn’t have time to post the following due to academics. My hope is that you will find the below post helpful in understanding why you get deep questions when posting on GitHub, as well as tips to make lives of everyone easier: Every week, NVDA developers (NV Access and third-party code contributors) review several feature suggestions and bug reports on GitHub. For people new to what I just talked about, GitHub is a software project and repository hosting service (formerly independent but bought by Microsoft a while back) optimized for open-source projects. As an open-source project, NVDA and related components are hosted on GitHub (GH for short), with many community add-ons hosting their code and issues on the service as well. For an overview on GitHub, visit www.github.com, and for specific info on using GitHub for NVDA users, see a tutorial made by Brian Vogel. For folks using GitHub, when you submit a new issue (bug report or a feature suggestion), you may notice that a template is generated to help you fill in details. Information asked include a brief description of the problem, steps to reproduce bugs, NVDA version, and for feature requests, what you would like to see in the future. For a general overview on writing good bug reports, see the articles listed in the references list below, because what I will talk about are things not addressed in these references, or if addressed, details are scant as it concerns screen reader bug reports and suggestions. So what are things expected from folks submitting bug reports and feature suggestions? In addition to being detailed (see the references please), you should: - Fill out the template. Sometimes an issue gets posted that are not using the template to the fullest (such as ones with just a paragraph of a bug description or describes a problem). I guarantee that you will get a comment to the effect of, “please fill out the template,” and in some cases, issues might get closed if this request is not honored.
- Be specific about NVDA+Windows+app versions if appropriate. If you just say, “NVDA is installed,” then you may get a reply that says, “hmmm, which version of NVDA are you using?”. Or if you just say, “this problem occurs when using this specific app” without specifying a version, you will get a reply that goes something like, “we need app version information please.” For Windows releases, if you happen to be using Windows 10 or later, you should specify exactly which feature update/build you have; for instance, if I read an issue report that does not specify which Windows 10 build you have, then I will ask you, “hmmm, build please.” I will talk about how to get NvDA+Windows+app version information later in this post.
- Write steps to reproduce the issue being reported. Suppose you report an issue with NVDA announcing something other than what you need to know. If you write a report that says, “NVDA says something in an app whereas I want NVDA to say something else” but do not specify how to reproduce steps to hear that announcement, then NV Access will flatly tell you, “please provide steps to reproduce this announcement.”
- Describe a feature suggestion. Suppose you want NvDA to do something everywhere, or perhaps change its behavior in a specific context. A report that simply says, “I want NVDA to do this and that” without describing this suggestion in detail is a good way to build a circular road where NV Access and third parties spend days to years trying to understand what’s going on (trust me, this has happened multiple times).
- Respond to comments from issue readers. As folks come up with a refined understanding of what your bug report is trying to communicate, you will often receive comments that will ask you to elaborate or give specific scenarios. Please respond to these comments whenever possible. I will come back to this item later when I talk about GitHub etiquette.
To elaborate a bit, what are things developers are REALLY looking for when you submit a bug report or a feature suggestion? At a minimum, we (the developers) are looking for: - Your thought process. Think, think, and think again BEFORE you post a bug report or a feature suggestion. Treat GitHub issue writing as writing a formal essay: you need time to gather your thoughts and observations, you need materials such as NVDA version you are using, and you need a strategy to help you write an organized piece of writing.
- An organized writing with a clear picture. I realize that I sound like a writing instructor, but GitHub issue writing is, after all, a practice in writing in a professional setting (I will get to the ‘professional setting” concept in a moment). The issue template is there to help you stay organized and to guide you in presenting a clear picture as to an issue that needs to be fixed or a suggestion you have.
- Detailed description of the problem you are experiencing (mostly applicable to bug reports). Without a clear and detailed description of the problem you are facing, it becomes harder for developers to picture the scene in their minds, and to developers, this is their worst nightmare. Steps to reproducing a problem (such as keyboard commands used and the version of the app you are using) is a must, otherwise developers will go around in circles. This is what I mean by thinking before you post, because you can make lives of developers easier by taking the time to describe reproduction steps and observing things.
- A clear rationale (applicable to feature suggestions). Suppose you wish to talk about a feature suggestion. What would win the hearts of developers: the status quo (what’s going on now) and a suggestion, or a suggestion with a justifiable rationale? Remember that I said to treat GitHub issue writing (including feature suggestions) as formal writing, and you will come to the conclusion that the latter is preferred. Or even better, tell us (developers) the background information so people can research it further.
- A professional attitude. As stated in at least one of the references (and many more), developers (including open-source developers and volunteers) are busy professionals. Therefore you must approach and communicate with them in a professional way, including being mindful of the fact that folks are busy, submissions are detailed, and ready to respond when asked. Does this mean contributions should only come from adults? I don’t think so – at least students can provide suggestions and report problems (I have seen folks in their late teens and early twenties who have shown professional attitude when communicating with developers). However, when it comes to code contributions, students must understand where to find credible resources and consequences of their actions (especially their code) before volunteering to submit pull requests (to my younger friends, you must understand that NVDA is a lifeline to thousands around the world). I understand that the latter part of this item would be uncomfortable – my intent is not to discourage students, but to let them know the reality they will face (or are facing) when you submit bug reports and feature suggestions via GitHub, or if you are willing, submit pull requests in the future.
You will notice that I emphasize the process before, during, and after submitting an issue on GitHub, more so the “before” moment and the attitude involved. It takes more time and effort (at least I think) in preparing a GitHub issue (as you will see below) than writing and filling out the issue template. The biggest takeaway from the above list is that you MUST think a lot and stay organized (searching for an existing issue is one way to think a lot and stay organized). As I noted above, as part of submitting an issue on GitHub, you must gather needed materials. An important material is software versions, and here’s how to get them: - NVDA: open NVDA menu (NVDA+N), then select Help/About. Listen carefully to the NVDA version text.
- Windows: open Start (Windows key), type “winver” without quotes, then press Enter. Listen carefully to the version and build texts.
- App: from the focused app, retrieve developer info from the log (NVDA+F1), then look for “appModule.productVersion” text.
References: Hope this helps. Cheers, Joseph
|
Joseph, Thank you so very much for taking the time and effort to put this together and present it. It is invaluable information and it is essential information as well. You have mentioned my tutorial, Creating an Issue in GitHub for NVDA, so I am posting a direct link to it. In the context of your own offering, I think it is even more important for those who are considering becoming bug report contributors, who may not as yet have a GitHub Account, or wish to create one prior to making up their minds, download my MS-Word template for a GitHub Bug Report, activate that template to open a new, blank fillable form, and have a look around. It is based, precisely, on the GitHub template that is used, but is a bit more user friendly (in my opinion) to fill out. But even if you don't want to use the template once you "take the plunge" and become a bug reporter, this is still an excellent way to familiarize yourself with each and every part of the bug report and what you need to fill out to the maximum extent possible (there will, on occasion, be something that's either not applicable or which you simply cannot fill out initially, but those should be few). Here are the two bug report templates I created:
MS-Word Fillable Form for an NVDA Bug Report Including Pre and Post Filling-Out Instructions
MS-Word Fillable Form for an NVDA Bug Report Including Only Post Filling-Out Instructions
The only difference between the two is that the first, which has pre-filling out instructions, is targeted at those completely new to the exercise including information they need to know. The one with only post filling-out instructions reminds you that you need to unprotect the document created from the template before you can copy and paste it as a filled out whole in GitHub itself. They are DOTX files, which means if you have one selected and activate while on it, you are NOT opening the template file itself, but it is being used to generate a blank, fillable MS-Word form for you. You have not changed a blessed thing about the template itself, and can play and generate blank form after blank form without altering the form structure, so play away!
If you want to acquaint yourself with what's asked for, without the need to actually create a GitHub account before you decide if "being a bug reporter is for me," then have a look at the document that gets created after you activate that template and have a fillable word form.
I did not do one specifically for feature requests, but that would be easy enough to make were there a call for it.
Thank you again for your contribution and for all you have done, and continue to do, in relation to NVDA.
--
Brian - Windows 10, 64-Bit, Version 21H2, Build 19044
I neither need nor want to be appeased, but apprised. Inconvenient truth is preferable to convenient (for the liar) lies.
~ Brian Vogel
|
