Topics

Devlearning unit 5: code contribution

 

 

For the last two years, we’ve been talking about NVDA internals, and to some extent, contributions. We started out by looking at the high-level overview of NVDA’s architecture, then going into details of various subsystems such as input and output, add-ons, objects, and a host of other components. I’m sure many of you would like to use things we’ve learned in the past two years to contribute something meaningful to NVDA screen reader project, and in this final lesson, that’s what we will learn.

 

Note that contribution doesn’t have to be code – it can include documentation and promotion. Translating NVDA is a form of contribution, and so is teaching community members (both old and new). But because this course has focused on code, we’ll focus on code contributions.

 

The first step in code contribution isn’t programming – it is learning about what the given system is and things surrounding it. Sometimes, I and other contributors have seen offers to add features to NVDA from people who do have programming skills but needed guidance in understanding NVDA and associated culture. I bring this up now because it is crucial that you do some preparations before submitting pull requests and filing issues on GitHub (or other platforms in the future).

 

Besides the big one above, other things to note are:

 

  1. Be prepared to write (a lot): code contribution isn’t programming; it is writing. That is, you’ll find yourself writing English or other languages more than Python when you need to respond to reviews and feedback, talk to users, and write documentation. For this reason, I consider coding as part of writing.
  2. Do not strive for perfection the first time (even if you are tempted to become a perfectionist): expect to see failures and rejection (no, I’m not joking), along with some praises and review approvals. Some newbies might say that a good code is something that runs perfectly; that’s a myth unless you are a genius. Rather, a good piece of code is something that does what it is supposed to do and makes an impact.
  3. Have several cups of coffee handy (for debugging purposes): unless you are a real genius, your writing won’t score a perfect score; you’ll find that even what appears to be a perfect code are filled with subtle errors. Be prepared to debug these, which can take minutes to days (and weeks).
  4. Be prepared to give speeches (a lot of them, in fact): your code contributions are not only destined for code reviewers at NV Access and others, but to anyone. At various times you’ll be asked to explain what your code does to a new user. Be prepared to have an explanation handy, and one way to do that (in a subtle way) is giving meaningful variable names.

 

With these out of the way, here is a high-level list of code contribution steps:

 

Step 1: prepare NVDA from source:

 

No, you can’t just submit code changes with just a bare source code – you need to actually compile NVDA from source, test changes, document it, and then submit edits for code review.

 

First, install Git (either through a Windows build or provided through layers such as Windows Subsystem for Linux or Cygwin). Once Git is ready, clone the NvDA source code repository from https://github.com/nvaccess/nvda, complete with submodules (git clone –recursive https://github.com/nvaccess/nvda). Once NVDA source code has been downloaded, follow the readme file and install Python and Visual Studio.

 

Special note on Python: if I sent this post around say, January, I would have said use both Python 2 and 3. That is no longer the case: once Python 3 staging snapshot comes to master branch (any moment now), all of you will need to move to Python 3 in order to start contributing code; no exceptions.

 

Once Python and Visual Studio are ready, compile NVDA from source (using Command Prompt or PowerShell, switch to the root of the NVDA source code and run scons source). If things go well, after several minutes, SCons will say, “dong building targets”.

 

Step 2: Run NVDA from source:

By now NVDA has been compiled from source, but it isn’t the time to think about code edits. Before doing that, you need to actually run NVDA from source (python/pythonw source/nvda.pyw). Notice the added “w” in the second variant, which allows Python to run GUI apps. If you know NVDA quite well, you’ll be able to get around it quite quickly; if not, you’ll need to consult the user guide, various tutorials, and even development guide (hosted on NV Access).

 

Note that there are several restrictions tied to running NVDA from source. These include inability to interact with secure screens, no touchscreen support, no audio ducking, and other system privileges.

 

Step 3: trace NVDA’s features from source code:

 

In other words, do not be satisfied when NVDA starts speaking, or use certain advanced features while using NVDA from source. You must actively seek out parts of source code that allows NvDA to speak, enables certain advanced features, and in case you wish to provide a bug fix, the source of the bug. Most NVDA features are found in source code, but there are other things (such as the scenario from step 4) that will require you to venture into other areas such as wxPython, Espeak nG, and a host of other dependencies.

 

Step 4 (optional): tackle dependencies if needed:

 

If a bug fix requires looking at dependencies (such as wxPython), the first place to start isn’t the source code for these dependencies; rather, it is the documentation for the dependencies or websites introducing such dependencies (for example, for wxPython, it is wxPython.org; note that the actual place to search in regards to wxPython work is wxWidgets). Same goes when you wish to experiment with newer versions of various dependencies.

 

Step 5: think about and communicate what you want to do:

 

At least by now you should have traced the NVDA source code (or played with it for a while). If you are really interested in providing code contribution, the next step is to think about and communicate what you want to do (and get a GitHub account if you don’t have one yet). Think about what NVDA is doing now, what you want it done, and tradeoffs. Of course, you should map out which source code files to edit before you can do the physical work of editing the source code.

 

If you wish to communicate your thoughts to everyone, the best way to do that (apart from mailing lists) is creating a GitHub issue. You may need to do this if what you wish to do require coordination with NV Access and the community (the most recent case being a series of changes to add UIA support for console windows). Once you do write out your thoughts (making sure to follow the template if needed), others in the community will provide feedback (doesn’t happen on all issues, but for most of them, someone will comment on your idea or two). You can then take feedback into consideration as you map out what to do next.

 

Step 6: write, test, repeat:

 

As I noted earlier, it isn’t enough to write source code changes; more than writing, you must test it under various conditions. Sometimes the first draft is just a draft i.e. bugs to be squashed and tested. Make sure to test, edit, test, edit, test, and repeat these steps until you are confident NVDA is doing what you want it to do.

 

In case you do get feedback from others, think and incorporate feedback as you write code changes, appl7ying them as you perform tests.

 

Step 7 (optional): draft a “speech” about your work:

 

If you are adding a user-visible change (or two) that merits editing the user guide, do that BEFORE you submit your changes for code review.

 

Special note on what’s new document: please DO NOT edit them yourself!

 

Step 8: package your work for code review:

 

This involves creating a new branch (git checkout -b hbranchname) to contain your work, creating a fork of NV Access’s NVDA repo (if you haven’t done so yet), adding your repo as a remote (git remote add yourreponame address), committing changes (git commit), and pushing your branch to your fork (git push yourreponame branch). This is when you need your Git skills.

 

Step 9: submit a pull request:

 

The easiest way to submit a pull request is going to your NVDA repo fork/branches (https://github.com/youraccount/nvda/branches). Locate the branch you wish to submit as a pull request, and click New pull request button. You’ll then be asked to specify the base branch (usually “master” is fine unless NV Access people directs you to a different base branch), the title, and other info as directed by the pull request template.


One of the most difficult questions concerns what’s new entry. Here, you need to construct another “speech” – a sentence, in fact – that summarizes what your pull request does. You don’t have to give it a perfect sentence, as someone from NV Access will edit the what’s new entry for you when it is time to merge your pull requests.

 

Step 10: more communication and refinements:

 

Unless your pull request is very trivial or clearly resolves an issue or two (and get approved without any changes), you’ll get feedback. Reviewers can either submit a comment about your work, or request changes. In case you are asked to change things here and there, you must address them. This is when you need to communicate effectively – thinking, writing, testing, submitting changes.

 

Step 11: pull request approved:

 

Most pull requests are approved (unless it is a draft pull request or not ready yet). This can take anywhere from mere minutes to years. But your work is not done yet – other people (especially snapshot/beta/release candidate/stable version users) will provide feedback at some point. Be prepared to repeat majority of steps described above.

 

Step 12 (if you are up for it): review code from others:

 

Another way to contribute through code is reviewing someone else’s work. Sometimes NV Access people would ask some members of the community (typically contributors outside NV Access) to review their own code. In this case, you’ll check out the pull request branch (and sometimes adding new remotes and checking out branches from there), reading the differences between the base branch and the pull request, test them yourself, and offer feedback (and sometimes approve changes).

 

So what’s next? If you are up for it, contribute something to NVDA via code!

 

And with that, I’m done teaching this course.

 

P.S. Although my work is done here, there are other people throughout the community who can teach you more interesting things.

 

Note: no final exam as noted above – your “final exam” is code contributions using concepts and skills you’ve learned for the last two years.

 

Cheers,

Joseph