Joseph, this is a great mail or article :) . I read it with all my attention. Thank you so much.

Here writes a lot of thought about NVDA’s code database.
I’m just curious about one thing:
NVDA’s code database is big.
I’m looking for a document describing NVDA’s folder layout.

• For example, which module of NVDA is processing notifications to Action Center?

I’m very new to NVDA. I have been using it for years and now I want to support coding.
Do you know any documents or methods on this subject?
How should we consider the NVDA’s folder hierarchy?

On 02/08/2020 05:42, Joseph Lee wrote:

Hi NVDA users,

The below post was sent to NVDA developers (including code contributors outside of NV Access) and add-on authors, but figured it would be a good idea to let you (users) see what it takes to propose, develop, and submit changes to NVDA through code. Before we get into that, a few things to note:

• Some of the things I wrote are rough at times (my apologies for these).
• The biggest takeaway is that coding is not for everyone.
• Although I produced various NVDA tutorials (including tutorials on add-on development), I do not work for NV Access nor my views represent that of the organization.

 

With that out of the way:

 

Hi all,

 

While editing the latest edition of NVDA Add-on Dev Guide and in the midst of planning a pull request strategy, I thought about something that was nagging at the back of my mind and I’m sure many are wondering about: submitting pull requests. This stems from a discussion on NVDA add-ons list several weeks ago regarding add-on development strategies such as code layout and such. I hope the following serves as sort of a rough map as to how to navigate the complex landscape of pull requests for any project, specifically for NVDA.

 

One of the reasons why NVDA is popular is because people can suggest and submit changes publicly. Sometimes this is needed to keep up with technology and accessibility standards. Sometimes a braille display manufacturer would like to see drivers for their products integrated into NVDA. Sometimes people submit spelling and grammar fixes for documentation. Whatever the suggestion might be, they go through a review process – the moment a pull request is submitted, it goes through several checks, culminating in improving your work based on feedback from stable version users (I’ll talk about this phrasing later, as that is going to be important).

 

Some of you might be wondering what a pull request is. A pull request is the act of submitting changes you made to a piece of software for inclusion in the original product. It starts with you thinking about an idea, a change, or a bug, then you go through researching, coding, and testing your idea, and if you believe your idea is ready for the world, publish a pull request. The maintainer of the product you are sending a pull request for would review your idea, suggest improvements if any, and if things are looking fine, integrate it into the original product.

 

No, forget the above definition. In truth, a pull request is a collection of your thought process, research and coding skills, test cases, real-world (and sometimes hypothetical) justifications, user impact, empathy and communication, refinements, feedback, and life-long learning. A successful pull request contains ALL of these. For example, a pull request is not complete without impactful justifications, code without tests will come back to haunt you years later, and your brilliant fix becomes meaningless when you don’t show empathy and effective communication skills.

 

So I guess some of you might insist on writing pull requests. There is one more thing that makes or breaks a pull request: do you understand the project itself? I don’t want you to think that code is everything – beginning computer science and software engineering students may think that coding is all there is to it. A project, as a complete system, contains not only code, but personnel, history, culture, assumptions, norms, expectations, and impact. This is more so for a specialized project such as NVDA: screen reader users have different expectations about what it means to use computers and using software. For instance, one of the cultural artifacts of NVDA is keyboard accessibility, which is different than say, a touch-based user interface. After these warnings, if you are not willing to or not comfortable with learning to appreciate screen reading, cultural assumptions about disability, and accessibility norms, then I’m afraid that writing pull requests for NVDA might not be a good idea for you at this time.

 

I’m saying all these (in a long way) to give you this solemn warning: without understanding the context in which NVDA operates (computer accessibility and usability for people with disabilities), writing effective NVDA pull requests is impossible. Sure, we (NVDA developers and code contributors) look for coding style, test cases, and good justifications when reviewing pull requests. But what we are after is your willingness to understand the culture in which NVDA is used. Do not give us a brilliant algorithm that can solve hundreds of different IAccessible2 issues at once. Rather, let us know that you are learning the NVDA source code and culture.

 

So how do you write an effective NVDA pull request? Well, the second step is thinking carefully (the first step was the above warning). After being part of NVDA community and culture for a while (obviously you need to be familiar with bits of NVDA source code and coding style), you may come across an interesting idea, a user suggestion or two, or perhaps you found an ancient bug. Do not be tempted to start coding right away – sit down, get a drink (not alcohol please), and think about what you just heard or discovered (the latter in case you found a bug). Depending on what’s bothering you, you can think about the following:

 

• Someone suggested something. How can I better understand what this person is talking about? If you want, start talking to the person who suggested such and such change.
• I discovered a bug. Do I understand what this bug might be (or what the bug is), or is this something wrong with my NVDA settings? If it is truly an ancient bug, how can I reproduce it, and are there potential causes, impact, and solutions?
• I have this brilliant idea I want to test. Can I articulate it to NVDA beginners? How can I test this idea? What will its impact be for users? What potential issues can it cause?

 

But don’t just think aloud to yourself: talk to someone. The best way to do so is searching GitHub, and if you know the idea you have (or a bug you found) wasn’t found, file a new issue. Chances are that someone will talk to you through various means (including commenting on the issue you filed); after all, humans are social beings.

 

So you talked to someone, and either you know you’re going to work on this idea or may get help from someone (or perhaps artificial intelligence might come to the rescue). If you are comfortable (and confident) enough to work on researching, coding, testing, explaining, and justifying your idea, go ahead with research, coding, and testing. Do not spend all night coding (trust me, I and many others have gone through countless all-night hackathons and regretted afterwards).

 

When you research, code, and test your idea (which may or may not become your dream pull request), keep the following in mind:

 

• You need to read a lot. You need to prepare your mind so that when it comes time to code and test, you will know what you are up to.
• You are writing an essay. After all, coding is responding to an essay prompt (or two).
• You are teaching a machine to think differently. You are a movie director, an architect, a tutor, a politician (maybe that’s going too far), or any job that requires you to teach someone (or something) new skills.
• Don’t forget to “taste your wine”. An effective software is not complete without extensive tests. And no, just compiling and running your changes does not constitute a complete test – you MUST try your best to comply with pull request expectations (including, yes, linting BEFORE you commit).
• You are a user, after all. In other words, perform tests as though you are the person who suggested the idea you are “talking” about in your code.

 

After you think, research, code, and test your idea (or a pull request), and verifying that it is ready to be sent to NV Access for review (via GitHub), prepare to explain and justify your changes. An effective pull request is more subjective than objective. That is, how you explain and justify your changes will have great impact on acceptance of your pull request. For example, if you just tell NVDA Developers that you fixed an ancient bug without specifying what it is or how you did it, reviewers might say, “hmmm, tell us more.” Or you come up with a brilliant algorithm for fixing hundreds of IAccessible2 issues at once but do not justify the impact of your algorithm on users. The overwhelming response will be, “how will your idea affect users as they use NVDA in hundreds of different scenarios?” Or in some cases, you submit a pull request based on a user’s suggestion, thinking that it is in scope for screen reading. How reviewers react to that pull request will depend on how effective your justifications are going to be (after all, persuasion matters).

 

At some point, reviewers will review your work and either approve your idea, suggest changes, or direct you elsewhere. Do not worry if reviewers tell you that your idea does not fit NVDA and its culture; think of that decision as a way for you to reflect on your thought process. If reviewers suggest changes, think about what these are and respond accordingly (perhaps make suggested changes, discuss changes, or something else).

 

Now your pull request has been approved and integrated into NVDA. This is not the time to pop open that champagne bottle you kept for this purpose. Rather, prepare to receive feedback from users, even when your idea makes it to the next public release of NVDA. This is so that you can learn and refine your work. Also, if you are willing, take some time to help others with their pull requests (reviewing, suggesting things, researching on behalf of others if asked, or drop some occasional joke or two (joking)).

 

I did briefly mention humor as an interesting way to help others. I included it to highlight the serious and rigorous nature of writing and submitting NVDA pull requests. NVDA development through pull requests is a serious and rigorous process, as a small change you make will be used in many scenarios by thousands of users around the world. More importantly, as a seasoned code contributor (I joined NVDA community in 2012), the most important thing you should learn is understanding the culture (disability culture) in which NVDA operates – I want you to become advocates, not just programmers.

 

Before I forget: some of you might be wondering about NVDA add-on development. Although not as rigorous as NVDA itself, you should take that process seriously, as your add-on(s) will be used by many people.

 

For me, among recent pull requests I wrote, the one I’m proud of is introducing foundations to support UIA notification event. It took me days to understand the scope of the problem and work on a stable solution. The pull request that brought you UIA notification event support was merged in 2018, and we have seen refinements since.

 

Perhaps the most intriguing pull request I submitted was ability to enable and disable individual add-ons. I spent days trying to understand the internal logic required to support this scenario. I received feedback from many people on this regard, including from several core NVDA developers. Ever since this pull request was merged in 2016, many improvements were made, some of which I provided feedback on.

 

I’m sure many of you would like to contribute to NVDA for months and years to come (including for the eventual new developer hired by NV Access). But remember my warning above: coding, specifically writing and submitting pull requests is not for everyone. Writing and submitting pull requests is a serious and rigorous task, and if you are not willing to learn the culture surrounding NVDA, your pull requests will not be effective. I and other developers can teach you the inner workings of NVDA for weeks to months (or years), but it is up to potential pull request writers themselves to show willingness to make an impactful difference for a community who must now rely on the double-edged sword that is technological progress, especially given the era we live in.

 

To those writing pull requests, good luck. To those contributing in other ways, keep up the good work. Please stay safe and healthy.

Cheers,

Joseph

--

Sean

• Email: seantolstoyevski@...
• GitHub: SeanTolstoyevski

👨‍🦯 I’m programmer. I coding often Python, sometimes Go and rarely C++.

Hi, and thanks for the article

One thing maybe off topic but I'd like to ask. If I see misspell in NVDA's documentations or interface, and I just a translater, should I fix, and submit pull request, or I should report it in NVDA translation mailing list for other people in NVDA developer to fix it? Right now I'm a translater, and I could contribute that way if I see any.

Appreciated your help.
Cuong

Joseph, this is a great mail or article :) . I read it with all my attention. Thank you so much.

Here writes a lot of thought about NVDA’s code database.
I’m just curious about one thing:
NVDA’s code database is big.
I’m looking for a document describing NVDA’s folder layout.

• For example, which module of NVDA is processing notifications to Action Center?

I’m very new to NVDA. I have been using it for years and now I want to support coding.
Do you know any documents or methods on this subject?
How should we consider the NVDA’s folder hierarchy?

On 02/08/2020 05:42, Joseph Lee wrote:

Hi NVDA users,

The below post was sent to NVDA developers (including code contributors outside of NV Access) and add-on authors, but figured it would be a good idea to let you (users) see what it takes to propose, develop, and submit changes to NVDA through code. Before we get into that, a few things to note:

• Some of the things I wrote are rough at times (my apologies for these).
• The biggest takeaway is that coding is not for everyone.
• Although I produced various NVDA tutorials (including tutorials on add-on development), I do not work for NV Access nor my views represent that of the organization.

 

With that out of the way:

 

Hi all,

 

While editing the latest edition of NVDA Add-on Dev Guide and in the midst of planning a pull request strategy, I thought about something that was nagging at the back of my mind and I’m sure many are wondering about: submitting pull requests. This stems from a discussion on NVDA add-ons list several weeks ago regarding add-on development strategies such as code layout and such. I hope the following serves as sort of a rough map as to how to navigate the complex landscape of pull requests for any project, specifically for NVDA.

 

One of the reasons why NVDA is popular is because people can suggest and submit changes publicly. Sometimes this is needed to keep up with technology and accessibility standards. Sometimes a braille display manufacturer would like to see drivers for their products integrated into NVDA. Sometimes people submit spelling and grammar fixes for documentation. Whatever the suggestion might be, they go through a review process – the moment a pull request is submitted, it goes through several checks, culminating in improving your work based on feedback from stable version users (I’ll talk about this phrasing later, as that is going to be important).

 

Some of you might be wondering what a pull request is. A pull request is the act of submitting changes you made to a piece of software for inclusion in the original product. It starts with you thinking about an idea, a change, or a bug, then you go through researching, coding, and testing your idea, and if you believe your idea is ready for the world, publish a pull request. The maintainer of the product you are sending a pull request for would review your idea, suggest improvements if any, and if things are looking fine, integrate it into the original product.

 

No, forget the above definition. In truth, a pull request is a collection of your thought process, research and coding skills, test cases, real-world (and sometimes hypothetical) justifications, user impact, empathy and communication, refinements, feedback, and life-long learning. A successful pull request contains ALL of these. For example, a pull request is not complete without impactful justifications, code without tests will come back to haunt you years later, and your brilliant fix becomes meaningless when you don’t show empathy and effective communication skills.

 

So I guess some of you might insist on writing pull requests. There is one more thing that makes or breaks a pull request: do you understand the project itself? I don’t want you to think that code is everything – beginning computer science and software engineering students may think that coding is all there is to it. A project, as a complete system, contains not only code, but personnel, history, culture, assumptions, norms, expectations, and impact. This is more so for a specialized project such as NVDA: screen reader users have different expectations about what it means to use computers and using software. For instance, one of the cultural artifacts of NVDA is keyboard accessibility, which is different than say, a touch-based user interface. After these warnings, if you are not willing to or not comfortable with learning to appreciate screen reading, cultural assumptions about disability, and accessibility norms, then I’m afraid that writing pull requests for NVDA might not be a good idea for you at this time.

 

I’m saying all these (in a long way) to give you this solemn warning: without understanding the context in which NVDA operates (computer accessibility and usability for people with disabilities), writing effective NVDA pull requests is impossible. Sure, we (NVDA developers and code contributors) look for coding style, test cases, and good justifications when reviewing pull requests. But what we are after is your willingness to understand the culture in which NVDA is used. Do not give us a brilliant algorithm that can solve hundreds of different IAccessible2 issues at once. Rather, let us know that you are learning the NVDA source code and culture.

 

So how do you write an effective NVDA pull request? Well, the second step is thinking carefully (the first step was the above warning). After being part of NVDA community and culture for a while (obviously you need to be familiar with bits of NVDA source code and coding style), you may come across an interesting idea, a user suggestion or two, or perhaps you found an ancient bug. Do not be tempted to start coding right away – sit down, get a drink (not alcohol please), and think about what you just heard or discovered (the latter in case you found a bug). Depending on what’s bothering you, you can think about the following:

 

• Someone suggested something. How can I better understand what this person is talking about? If you want, start talking to the person who suggested such and such change.
• I discovered a bug. Do I understand what this bug might be (or what the bug is), or is this something wrong with my NVDA settings? If it is truly an ancient bug, how can I reproduce it, and are there potential causes, impact, and solutions?
• I have this brilliant idea I want to test. Can I articulate it to NVDA beginners? How can I test this idea? What will its impact be for users? What potential issues can it cause?

 

But don’t just think aloud to yourself: talk to someone. The best way to do so is searching GitHub, and if you know the idea you have (or a bug you found) wasn’t found, file a new issue. Chances are that someone will talk to you through various means (including commenting on the issue you filed); after all, humans are social beings.

 

So you talked to someone, and either you know you’re going to work on this idea or may get help from someone (or perhaps artificial intelligence might come to the rescue). If you are comfortable (and confident) enough to work on researching, coding, testing, explaining, and justifying your idea, go ahead with research, coding, and testing. Do not spend all night coding (trust me, I and many others have gone through countless all-night hackathons and regretted afterwards).

 

When you research, code, and test your idea (which may or may not become your dream pull request), keep the following in mind:

 

• You need to read a lot. You need to prepare your mind so that when it comes time to code and test, you will know what you are up to.
• You are writing an essay. After all, coding is responding to an essay prompt (or two).
• You are teaching a machine to think differently. You are a movie director, an architect, a tutor, a politician (maybe that’s going too far), or any job that requires you to teach someone (or something) new skills.
• Don’t forget to “taste your wine”. An effective software is not complete without extensive tests. And no, just compiling and running your changes does not constitute a complete test – you MUST try your best to comply with pull request expectations (including, yes, linting BEFORE you commit).
• You are a user, after all. In other words, perform tests as though you are the person who suggested the idea you are “talking” about in your code.

 

After you think, research, code, and test your idea (or a pull request), and verifying that it is ready to be sent to NV Access for review (via GitHub), prepare to explain and justify your changes. An effective pull request is more subjective than objective. That is, how you explain and justify your changes will have great impact on acceptance of your pull request. For example, if you just tell NVDA Developers that you fixed an ancient bug without specifying what it is or how you did it, reviewers might say, “hmmm, tell us more.” Or you come up with a brilliant algorithm for fixing hundreds of IAccessible2 issues at once but do not justify the impact of your algorithm on users. The overwhelming response will be, “how will your idea affect users as they use NVDA in hundreds of different scenarios?” Or in some cases, you submit a pull request based on a user’s suggestion, thinking that it is in scope for screen reading. How reviewers react to that pull request will depend on how effective your justifications are going to be (after all, persuasion matters).

 

At some point, reviewers will review your work and either approve your idea, suggest changes, or direct you elsewhere. Do not worry if reviewers tell you that your idea does not fit NVDA and its culture; think of that decision as a way for you to reflect on your thought process. If reviewers suggest changes, think about what these are and respond accordingly (perhaps make suggested changes, discuss changes, or something else).

 

Now your pull request has been approved and integrated into NVDA. This is not the time to pop open that champagne bottle you kept for this purpose. Rather, prepare to receive feedback from users, even when your idea makes it to the next public release of NVDA. This is so that you can learn and refine your work. Also, if you are willing, take some time to help others with their pull requests (reviewing, suggesting things, researching on behalf of others if asked, or drop some occasional joke or two (joking)).

 

I did briefly mention humor as an interesting way to help others. I included it to highlight the serious and rigorous nature of writing and submitting NVDA pull requests. NVDA development through pull requests is a serious and rigorous process, as a small change you make will be used in many scenarios by thousands of users around the world. More importantly, as a seasoned code contributor (I joined NVDA community in 2012), the most important thing you should learn is understanding the culture (disability culture) in which NVDA operates – I want you to become advocates, not just programmers.

 

Before I forget: some of you might be wondering about NVDA add-on development. Although not as rigorous as NVDA itself, you should take that process seriously, as your add-on(s) will be used by many people.

 

For me, among recent pull requests I wrote, the one I’m proud of is introducing foundations to support UIA notification event. It took me days to understand the scope of the problem and work on a stable solution. The pull request that brought you UIA notification event support was merged in 2018, and we have seen refinements since.

 

Perhaps the most intriguing pull request I submitted was ability to enable and disable individual add-ons. I spent days trying to understand the internal logic required to support this scenario. I received feedback from many people on this regard, including from several core NVDA developers. Ever since this pull request was merged in 2016, many improvements were made, some of which I provided feedback on.

 

I’m sure many of you would like to contribute to NVDA for months and years to come (including for the eventual new developer hired by NV Access). But remember my warning above: coding, specifically writing and submitting pull requests is not for everyone. Writing and submitting pull requests is a serious and rigorous task, and if you are not willing to learn the culture surrounding NVDA, your pull requests will not be effective. I and other developers can teach you the inner workings of NVDA for weeks to months (or years), but it is up to potential pull request writers themselves to show willingness to make an impactful difference for a community who must now rely on the double-edged sword that is technological progress, especially given the era we live in.

 

To those writing pull requests, good luck. To those contributing in other ways, keep up the good work. Please stay safe and healthy.

Cheers,

Joseph

--

Sean

• Email: seantolstoyevski@...
• GitHub: SeanTolstoyevski

👨‍🦯 I’m programmer. I coding often Python, sometimes Go and rarely C++.

Joseph, this is a great mail or article :) . I read it with all my attention. Thank you so much.

Here writes a lot of thought about NVDA’s code database.
I’m just curious about one thing:
NVDA’s code database is big.
I’m looking for a document describing NVDA’s folder layout.

• For example, which module of NVDA is processing notifications to Action Center?

I’m very new to NVDA. I have been using it for years and now I want to support coding.
Do you know any documents or methods on this subject?
How should we consider the NVDA’s folder hierarchy?

Hi NVDA users,

The below post was sent to NVDA developers (including code contributors outside of NV Access) and add-on authors, but figured it would be a good idea to let you (users) see what it takes to propose, develop, and submit changes to NVDA through code. Before we get into that, a few things to note:

• Some of the things I wrote are rough at times (my apologies for these).
• The biggest takeaway is that coding is not for everyone.
• Although I produced various NVDA tutorials (including tutorials on add-on development), I do not work for NV Access nor my views represent that of the organization.

 

With that out of the way:

 

Hi all,

 

While editing the latest edition of NVDA Add-on Dev Guide and in the midst of planning a pull request strategy, I thought about something that was nagging at the back of my mind and I’m sure many are wondering about: submitting pull requests. This stems from a discussion on NVDA add-ons list several weeks ago regarding add-on development strategies such as code layout and such. I hope the following serves as sort of a rough map as to how to navigate the complex landscape of pull requests for any project, specifically for NVDA.

 

One of the reasons why NVDA is popular is because people can suggest and submit changes publicly. Sometimes this is needed to keep up with technology and accessibility standards. Sometimes a braille display manufacturer would like to see drivers for their products integrated into NVDA. Sometimes people submit spelling and grammar fixes for documentation. Whatever the suggestion might be, they go through a review process – the moment a pull request is submitted, it goes through several checks, culminating in improving your work based on feedback from stable version users (I’ll talk about this phrasing later, as that is going to be important).

 

Some of you might be wondering what a pull request is. A pull request is the act of submitting changes you made to a piece of software for inclusion in the original product. It starts with you thinking about an idea, a change, or a bug, then you go through researching, coding, and testing your idea, and if you believe your idea is ready for the world, publish a pull request. The maintainer of the product you are sending a pull request for would review your idea, suggest improvements if any, and if things are looking fine, integrate it into the original product.

 

No, forget the above definition. In truth, a pull request is a collection of your thought process, research and coding skills, test cases, real-world (and sometimes hypothetical) justifications, user impact, empathy and communication, refinements, feedback, and life-long learning. A successful pull request contains ALL of these. For example, a pull request is not complete without impactful justifications, code without tests will come back to haunt you years later, and your brilliant fix becomes meaningless when you don’t show empathy and effective communication skills.

 

So I guess some of you might insist on writing pull requests. There is one more thing that makes or breaks a pull request: do you understand the project itself? I don’t want you to think that code is everything – beginning computer science and software engineering students may think that coding is all there is to it. A project, as a complete system, contains not only code, but personnel, history, culture, assumptions, norms, expectations, and impact. This is more so for a specialized project such as NVDA: screen reader users have different expectations about what it means to use computers and using software. For instance, one of the cultural artifacts of NVDA is keyboard accessibility, which is different than say, a touch-based user interface. After these warnings, if you are not willing to or not comfortable with learning to appreciate screen reading, cultural assumptions about disability, and accessibility norms, then I’m afraid that writing pull requests for NVDA might not be a good idea for you at this time.

 

I’m saying all these (in a long way) to give you this solemn warning: without understanding the context in which NVDA operates (computer accessibility and usability for people with disabilities), writing effective NVDA pull requests is impossible. Sure, we (NVDA developers and code contributors) look for coding style, test cases, and good justifications when reviewing pull requests. But what we are after is your willingness to understand the culture in which NVDA is used. Do not give us a brilliant algorithm that can solve hundreds of different IAccessible2 issues at once. Rather, let us know that you are learning the NVDA source code and culture.

 

So how do you write an effective NVDA pull request? Well, the second step is thinking carefully (the first step was the above warning). After being part of NVDA community and culture for a while (obviously you need to be familiar with bits of NVDA source code and coding style), you may come across an interesting idea, a user suggestion or two, or perhaps you found an ancient bug. Do not be tempted to start coding right away – sit down, get a drink (not alcohol please), and think about what you just heard or discovered (the latter in case you found a bug). Depending on what’s bothering you, you can think about the following:

 

• Someone suggested something. How can I better understand what this person is talking about? If you want, start talking to the person who suggested such and such change.
• I discovered a bug. Do I understand what this bug might be (or what the bug is), or is this something wrong with my NVDA settings? If it is truly an ancient bug, how can I reproduce it, and are there potential causes, impact, and solutions?
• I have this brilliant idea I want to test. Can I articulate it to NVDA beginners? How can I test this idea? What will its impact be for users? What potential issues can it cause?

 

But don’t just think aloud to yourself: talk to someone. The best way to do so is searching GitHub, and if you know the idea you have (or a bug you found) wasn’t found, file a new issue. Chances are that someone will talk to you through various means (including commenting on the issue you filed); after all, humans are social beings.

 

So you talked to someone, and either you know you’re going to work on this idea or may get help from someone (or perhaps artificial intelligence might come to the rescue). If you are comfortable (and confident) enough to work on researching, coding, testing, explaining, and justifying your idea, go ahead with research, coding, and testing. Do not spend all night coding (trust me, I and many others have gone through countless all-night hackathons and regretted afterwards).

 

When you research, code, and test your idea (which may or may not become your dream pull request), keep the following in mind:

 

• You need to read a lot. You need to prepare your mind so that when it comes time to code and test, you will know what you are up to.
• You are writing an essay. After all, coding is responding to an essay prompt (or two).
• You are teaching a machine to think differently. You are a movie director, an architect, a tutor, a politician (maybe that’s going too far), or any job that requires you to teach someone (or something) new skills.
• Don’t forget to “taste your wine”. An effective software is not complete without extensive tests. And no, just compiling and running your changes does not constitute a complete test – you MUST try your best to comply with pull request expectations (including, yes, linting BEFORE you commit).
• You are a user, after all. In other words, perform tests as though you are the person who suggested the idea you are “talking” about in your code.

 

After you think, research, code, and test your idea (or a pull request), and verifying that it is ready to be sent to NV Access for review (via GitHub), prepare to explain and justify your changes. An effective pull request is more subjective than objective. That is, how you explain and justify your changes will have great impact on acceptance of your pull request. For example, if you just tell NVDA Developers that you fixed an ancient bug without specifying what it is or how you did it, reviewers might say, “hmmm, tell us more.” Or you come up with a brilliant algorithm for fixing hundreds of IAccessible2 issues at once but do not justify the impact of your algorithm on users. The overwhelming response will be, “how will your idea affect users as they use NVDA in hundreds of different scenarios?” Or in some cases, you submit a pull request based on a user’s suggestion, thinking that it is in scope for screen reading. How reviewers react to that pull request will depend on how effective your justifications are going to be (after all, persuasion matters).

 

At some point, reviewers will review your work and either approve your idea, suggest changes, or direct you elsewhere. Do not worry if reviewers tell you that your idea does not fit NVDA and its culture; think of that decision as a way for you to reflect on your thought process. If reviewers suggest changes, think about what these are and respond accordingly (perhaps make suggested changes, discuss changes, or something else).

 

Now your pull request has been approved and integrated into NVDA. This is not the time to pop open that champagne bottle you kept for this purpose. Rather, prepare to receive feedback from users, even when your idea makes it to the next public release of NVDA. This is so that you can learn and refine your work. Also, if you are willing, take some time to help others with their pull requests (reviewing, suggesting things, researching on behalf of others if asked, or drop some occasional joke or two (joking)).

 

I did briefly mention humor as an interesting way to help others. I included it to highlight the serious and rigorous nature of writing and submitting NVDA pull requests. NVDA development through pull requests is a serious and rigorous process, as a small change you make will be used in many scenarios by thousands of users around the world. More importantly, as a seasoned code contributor (I joined NVDA community in 2012), the most important thing you should learn is understanding the culture (disability culture) in which NVDA operates – I want you to become advocates, not just programmers.

 

Before I forget: some of you might be wondering about NVDA add-on development. Although not as rigorous as NVDA itself, you should take that process seriously, as your add-on(s) will be used by many people.

 

For me, among recent pull requests I wrote, the one I’m proud of is introducing foundations to support UIA notification event. It took me days to understand the scope of the problem and work on a stable solution. The pull request that brought you UIA notification event support was merged in 2018, and we have seen refinements since.

 

Perhaps the most intriguing pull request I submitted was ability to enable and disable individual add-ons. I spent days trying to understand the internal logic required to support this scenario. I received feedback from many people on this regard, including from several core NVDA developers. Ever since this pull request was merged in 2016, many improvements were made, some of which I provided feedback on.

 

I’m sure many of you would like to contribute to NVDA for months and years to come (including for the eventual new developer hired by NV Access). But remember my warning above: coding, specifically writing and submitting pull requests is not for everyone. Writing and submitting pull requests is a serious and rigorous task, and if you are not willing to learn the culture surrounding NVDA, your pull requests will not be effective. I and other developers can teach you the inner workings of NVDA for weeks to months (or years), but it is up to potential pull request writers themselves to show willingness to make an impactful difference for a community who must now rely on the double-edged sword that is technological progress, especially given the era we live in.

 

To those writing pull requests, good luck. To those contributing in other ways, keep up the good work. Please stay safe and healthy.

Cheers,

Joseph