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

 

Hi,
There's no separate course - a series of email discussions.
Cheers,
Joseph

----- Original Message -----
From: "Juan Hernandez" <juanhernandez98@...
To: <nvda-devel@groups.io
Date sent: Tue, 9 Apr 2019 09:04:12 -0700
Subject: Re: [nvda-devel] Code contributions: an upcoming series of discussion on ins and outs of giving back to the community with code

Hi, how does one join this course?



Best,



Juan



From: nvda-devel@groups.io <nvda-devel@groups.io> On Behalf Of Joseph Lee
Sent: Monday, April 08, 2019 11:00 PM
To: nvda-devel@groups.io
Subject: [nvda-devel] 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.