Contributing

Contributing to NVDA

If you would like to contribute code or documentation to NVDA, please follow these guidelines.

Submitting Changes

For anything other than minor bug fixes, please comment on an existing issue or create a new issue providing details about your proposed change. Unrelated changes should be addressed in separate issues. Include information about use cases, design, user experience, etc. This allows us to discuss these aspects and any other concerns that might arise, thus potentially avoiding a great deal of wasted time. You should generally wait for acceptance of your proposal before you start coding. Please understand that we very likely will not accept changes that are not discussed first.

If this is a minor/trivial change which definitely wouldn't require design, user experience or implementation discussion (e.g. a fix for a typo/obvious coding error or a simple synthesizer/braille display driver), you can just create a pull request rather than using an issue first. However, this should be fairly rare. If in doubt, use an issue first.

If this is your first contribution, you will first need to "fork" the NVDA repository on GitHub.

When you fork the repository, GitHub will create a copy of the master branch. However, this branch will not be updated when the official master branch is updated. To ensure your work is always based on the latest commit in the official master branch, it is recommended that your master branch be linked to the official master branch, rather than the master branch in your GitHub fork. If you have cloned your GitHub fork, you can do this from the command line as follows:

# Add a remote for the NV Access repository.
git remote add nvaccess https://github.com/nvaccess/nvda.git
# Fetch the nvaccess branches.
git fetch nvaccess
# Switch to the local master branch.
git checkout master
# Set the local master to use the nvaccess master as its upstream.
git branch -u nvaccess/master
# Update the local master.
git pull

You should use a separate "topic" branch for each issue. All code should usually be based on the latest commit in the official master branch at the time you start the work unless the code is entirely dependent on the code for another issue. Branches should never be based on the "next" branch.

If you are adding a feature or changing something that will be noticeable to the user, you should update the User Guide accordingly.

When it is time to submit your code, you should open a pull request referring to the original issue. Code review will then be done on this pull request.

Code Style

Indentation

• Indentation must be done with tabs (one per level), not spaces.
• When splitting a single statement over multiple lines, just indent one or more additional levels. Don't use vertical alignment; e.g. lining up with the bracket on the previous line.

Identifier Names

• Functions, variables, properties, etc. should use mixed case to separate words, starting with a lower case letter; e.g. speakText.
• Classes should use mixed case to separate words, starting with an upper case letter; e.g. BrailleHandler.
• Constants should be all upper case, separating words with underscores; e.g. LANGS_WITH_CONJUNCT_CHARS.

Translatable Strings

• All strings that could be presented to the user should be marked as translatable using the _() function; e.g. _("Text review").
• All translatable strings should have a preceding translators comment describing the purpose of the string for translators. For example:

# Translators: The name of a category of NVDA commands.
SCRCAT_TEXTREVIEW = _("Text review")