Code contributions: an upcoming series of discussion on ins and outs of giving back to the community with code

 

Hi all,

 

Some of you may recall that there is a subgroup of NVDA users list called “devlearning”. After asking on the list, folks over there felt it would be best to combine the lists into one – bringing folks from the devlearning subgroup to this mailing list in the next few months. But before doing so, there is an important series of topics I need to teach: code contributions.

 

In 2019, NV Access was selected as a mentor organization for Google Summer of Code (GSoC), an event where college students studying computer science and related fields can work with an organization to code various features. NV Access has posted a list of code contributions they would like to receive from participants of GSoC 2019, including experimenting with 64-bit NVDA, performance improvements and others.

 

Prior to that, since late 2017, I’ve been teaching NVDA internals to a group of new developers. I discussed how to download and compile NVDA source code, code layout and folder structure, internals of NVDA objects, working with accessibility API’s, input and output and many other things. As a result, at least one person provided pull requests recently based on lessons I taught.

 

Given that one avenue for GSoC participants to meet NV Access and the NVDA community is through this mailing list, coupled with a desire from those who studied with me to come over and join this list, I decided to open up NVDA Internals unit 5 (code contributions) to everyone on both lists. For members of devlearning, it should serve as a last set of lessons before everyone is brought to this mailing list and devlearning group closed. For members of nvda-devel mailing list, a chance to learn from a seasoned NVDA code contributor regarding code contribution and a chance for GSoC students to learn more about what to expect as they work on bringing their dream features to life. For me, it would be a chance to demonstrate my know-how and serving as a teaching experience in teaching a large group of people (already sort of doing that with speech competitions). Of course, because these two lists are geared towards a bit more technically abled, we’ll talk about NVDA internals here and there (see below for an example).

 

The content of this combined course will include:

 

  • A really high-level introduction to NVDA (for benefit of GSoC students)
  • What exactly is code contribution
  • Important terms: pull request, code review
  • Thinking about a dream feature (or a bug fix, for some)
  • Listen, elaborate, plan, explain, write, test (mandatory)
  • Write, write, and write again (mandatory)
  • Tests, tests, and more tests (mandatory)
  • Packaging a dream feature into a branch
  • Pull request basics
  • Code reviews
  • Having willingness to say, “you are right”
  • Yay, my feature is now part of NVDA… or maybe not
  • So now what?

 

At the end of this course, you should be able to:

 

  1. Explain what NVDA is to a new user or a developer.
  2. Define code contribution and related terms.
  3. Explain steps involved in code contribution.
  4. Ready to assist NV Access and the community with contributions (for those planning to do so).

 

For those curious about my statement on NVDA internals, let me give you an example:

 

What is the process involved in choosing overlay classes? In a nutshell, NVDA itself doesn’t know how to deal with overlay classes at first. The only NVDA object classes it knows about are those that come with NVDA – built-in app modules, and most importantly, API classes (UIA, MSAA, etc.).

 

So one day NVDA comes across a curious screen element – say, an unknown UIA slider control. At least NVDA can tell it is a UIA object because it can detect them (not all UIA objects are detected by NVDA, by the way). In an attempt to find out more about this screen element, NVDA will go through the following:

 

  1. Create a class list (clsList) to hold a record of object types it has seen so far.
  2. Ask the app module about this element (calls obj.appModule.chooseNVDAObjectOverlayClasses if defined).
  3. NVDA will then ask a group of shareholders to come forward and explain the object (i.e. loops through global plugins and ask globalPlugin.chooseNVDAObjectOverlayClasses).
  4. If the app module and one or more global plugins provided suitable answers about the object, the class list should be filled with all sorts of entries about what the object is now, helping NVDA “unfog the future” (pardon the pun).
  5. NVDA will now invoke Python to construct a proper method resolution order (MRO) for this object, which is then used to build script lookup order, inheritance, and other information.

 

With this finished, the newly “awakened” overlay NVDA object is ready for use. For a source code explanation, take a look at source/NVDAObjects/__init__.py under dynamic object type.

 

My overall hope is that this course will serve as an eye-opening experience for many of you.

 

Cheers,

Joseph

Join nvda-devel@groups.io to automatically receive all group messages.