Topics

Unit 5: key terms, and a high-level overview of code contribution steps

 

Hi all,

 

For those on nvda-devel list, don’t worry about “?unit 5” bit in the subject line, as it is for devlearning people.

 

For those who’ve joined us lately: we’re in the middle of a course on how to contribute code to NVDA. We looked at what code contribution is (and is not), along with mindset associated with it. We’ll now get into the details of this process, starting with definitions of key terms and a high-level overview of code contribution steps.

 

A few definitions you’ll encounter in your journey through NVDA code contributions:

 

  • Branch: a separate tree of Git commits.
  • Pull request: contributing changes to source code of a project.
  • Code review: discussion surrounding a code change proposed through a pull request.
  • Reviewers: people reviewing a pull request.

 

Let’s take a look at how code contribution works from a high level:

 

One day, out of the blue (or perhaps while you were eating, walking, typing, sleeping, etc.), a sudden thought about NVDA source code comes to your mind. It could be triggered by a bug report, a lengthy (or not so lengthy) discussion about a feature, or perhaps you might be feeling adventurous. In case you get an email about a bug report, you’d read it, think about it, and do some readings (or research, if you will).

 

While thinking about whatever that triggered your mind, you feel that you can help make a difference in a person’s life by coding it. So you start going through NVDA source code, experimenting here and there, and write how you are going to solve a problem (or rather, how this unknown user will benefit from the code changes you’re making). You then plan, write, and test your edits.

 

Once you’re satisfied that the edits are working as intended, you would commit to a branch (a separate branch, in fact, not master; at least one NVDA pull request had to be rewritten simply because the pull request came from master branch from a forked copy). You then send in a pull request, detailing what your code will do and ask for a code review. Then people will comment on a pull request, suggesting changes, approving it, or rejecting it (rejection is rare). Then, once you and the reviewer agree that it is ready, it’ll be approved and merged (which can take hours to years).

 

And that’s just the beginning. The pull request will still need to be validated (tested) by more people, and only after going through several rounds of testing by people using alpha snapshots, it is declared ready. In the intervening time there will be zero or more bug reports on the feature you’ve provided, and you must be ready to respond if a bug report is traced to your pull request.

 

A follow-up comment stemming from what I just described goes something like this: a contributor posted a pull request, it was approved, then it was backed out (removed from master branch). The contributor wrote a follow-up pull request and wants it merged as soon as possible. To that, I have no definitive recommendation, but I think it’d be best for both sides to explain their reasoning in a civil manner (this is the reason why I stressed importance of one’s conduct as a code contributor).

 

Another follow-up comment, or more towards a question: how long does it for a pull request to be merged into NVDA? Depends on many things, including the scope of the pull request, time for code review, follow-ups, major changes that necessitate rewriting a pull request and such. Some of my own pull requests were reviewed and approved within hours, while the longest one lasted at least a year; the longest in my memory is wxPython 4 upgrade, which took more than three years, including conception, researching, planning, elaborating, writing, testing, reviewing, and looking for follow-up comments.

 

The rest of this series will focus on diving into individual parts of code contribution steps noted above.

Cheers,

Joseph