Skip to main content
Creating a well-structured pull request (PR) is essential for getting your contributions accepted into NVDA. This guide explains how to fill out the PR template and navigate the review process.
Before creating a PR, ensure you’ve discussed your changes in an issue (except for minor/trivial changes). See the contributing guide for details.

​
The Pull Request Template

When you create a PR, GitHub provides a template with sections to fill out. This template helps reviewers understand your changes and ensures nothing is overlooked.

​
Title

Use a descriptive title of the changes. Avoid relying solely on issue or PR references - ensure the title is self-descriptive.
Good examples:
  • “Fix speech output for emoji in Chrome”
  • “Add support for XYZ braille display”
  • “Improve performance of text navigation”
Bad examples:
  • “Fix for #1234”
  • “Update file.py”
  • “Changes”

​
Template Sections

Include the issue number and how the PR relates to it: 
Fixes #1234
Closes #5678
Related to #9012
GitHub automatically closes issues using keywords. When you write closes #7777 or fixes #4242, the mentioned issue will automatically close when the PR is merged.
For minor/trivial changes, an issue is not required. If in doubt, create one.

​
Summary of the Issue

Provide a quick summary of the problem you’re solving: 
NVDA was not announcing emoji characters in Chrome browser,
making it difficult for users to understand emoji in web content.

​
Description of User-Facing Changes

Explain how the user experience has changed: 
Users will now hear the description of emoji characters when 
navigating web pages in Chrome. For example, "😀" will be 
announced as "grinning face".

​
Description of Developer-Facing Changes

Describe how the developer experience has changed: 
Added new method `getEmojiDescription()` to the textInfo module.
Updated the Chrome virtual buffer to call this method when 
processing text content.
Include:
  • API changes
  • New interfaces or extension points
  • Breaking changes
  • Call signature modifications

​
Description of Development Approach

This is a critical section. Provide a detailed description of the technical changes and your reasoning.
Include:
  1. Technical implementation details
    • What modules/classes were modified
    • New files or functions added
    • How the solution works
  2. External resources
    • Links to documentation you referenced
    • Relevant specifications or standards
    • Similar implementations in other projects
  3. Alternative approaches considered
    • Why you chose this approach over others
    • Trade-offs made
    • Why rejected alternatives wouldn’t work
  4. History of changes
    • How the approach evolved during development
    • What you learned along the way
Example: 
Created a new app module for the XYZ application which handles 
the custom UI framework's events. The app module:

1. Overrides the UIA event handler to catch focus changes
2. Maps the application's custom roles to NVDA roles
3. Provides custom navigation commands for the tree view

I considered using IAccessible2 instead of UIA, but the 
application only exposes partial information through IA2. 
UIA provides complete access to the custom controls.

Useful resources:
- Application's accessibility documentation: [link]
- UIA documentation on custom controls: [link]

​
Testing Strategy

This section allows you to convince reviewers (and yourself) that your change works correctly and should be merged.
Outline the steps you took to test the change. Answer these questions:
  1. How did you test to ensure the change works as intended?
  2. Have you tested across all supported operating systems?
  3. Have you considered possible regressions?
Provide step-by-step testing instructions:
1

Configure NVDA settings

In NVDA settings ensure that:
  • Keyboard category:
    • “speak typed characters” is unchecked
    • “speak typed words” is checked
2

Perform test actions

  1. Open Notepad
  2. Type “hello”
  3. Press space
3

Expected result

Expect “hello” to be announced.
Tips for testing instructions:
  • If many NVDA settings are required, consider attaching a sample nvda.ini file
  • If a complicated document is needed, attach it to the PR for others to test with
  • Be specific enough that anyone can replicate your testing

​
Known Issues with Pull Request

Be transparent about limitations or downsides: 
- Will not work with UIA disabled in advanced settings
- Performance may be slower with large documents (>1000 lines)
- Does not support custom emoji added by the application
If there are no known issues, you can state that explicitly.

​
Code Review Checklist

The PR template includes a checklist of considerations. Go through each item and check it off after you’ve considered it. Not all items apply to all PRs.

​
Testing

Consider and document:
  • Unit tests
    • Coverage of automated unit tests
    • Can the changed code be covered by unit tests?
  • System tests
    • Coverage of automated system tests
    • Can the changed code be covered by system tests?
  • Manual tests
    • Have you followed relevant manual test plans?
    • Clear steps for replicating your testing
    • For commonly tested features, add steps to manual test documentation

​
API Compatibility

  • If this is not a .1 breaking release, ensure all API changes are backwards compatible
  • Ensure proposed API changes are in the change log under “Changes for Developers”
  • See deprecations documentation

​
Documentation

  • Change log entries - Ensure there’s an entry if required
  • User Documentation - Does the user guide need updating?
  • Context sensitive help - New GUI options require context sensitive help
  • Developer Documentation - Does technical documentation need updating?

​
UX of All Users Considered

Users rely on different parts of NVDA. Ensure the change caters to users of:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers (Firefox, Chrome, Edge)
  • Localization in languages other than English
If any of these cannot be supported, highlight it under “Known issues.”

​
Security Precautions

Windows allows NVDA to access secure information while the lock screen is activated. Special precautions are needed.
When handling NVDAObjects, check if an object should be available while the lock screen is activated: 
if utils.security._isSecureObjectWhileLockScreenActivated(obj):
    # Object should not be processed - return gracefully
    return
For code that should not run on secure screens: 
# Check if running in secure mode
if globalVars.appArgs.secure:
    return

# Or use the decorator for user-initiated actions
@blockAction.when(blockAction.Context.SECURE_MODE)
def myFunction():
    pass
This ensures information from secure objects does not reach the user.

​
Submission Process

​
Draft vs. Ready for Review

Use draft PRs when:
  • Publishing unfinished work to seek early feedback
  • Demonstrating an approach
  • Work is in progress
Mark as “ready for review” when you want code review from NV Access.

​
Important Settings

All pull requests must have “Allow edits from maintainers” checkbox ticked. This is the GitHub default for new PRs, except for organisation forks.
For organisation forks, you must invite NV Access developers to collaborate directly.

​
Target Branch

Consider if the PR should target:
  • master - For new features and most bug fixes (default)
  • beta - For bugs introduced in the current beta cycle
  • rc - For critical bugs in release candidates

​
CI/CD Testing

Every time you push a commit to your PR:

​
pre-commit.ci

  • Applies linting fixes automatically
  • Re-run: Comment pre-commit.ci run
  • Skip: Use [skip ci], [ci skip], [skip pre-commit.ci], or [pre-commit.ci skip] in commit message

​
GitHub Actions

  • Builds NVDA
  • Creates build artifact for testing
  • Runs system tests and other automated tests
Sometimes system tests fail unexpectedly. If you believe the failure is unrelated, feel free to ignore it unless raised by a reviewer.

​
Security Checks

Automated security checks verify code safety.

​
Code Review Process

Participate actively in the review process:
1

Core developers review

Core NVDA developers will:
  • Understand the intent of the change
  • Read the code changes
  • Ask questions or suggest changes
2

Respond to feedback

  • Answer questions promptly
  • Discuss suggested changes
  • Update code based on feedback
  • Be proactive to speed up the process
3

Address review comments

If issues are raised:
  • PR may be marked as draft
  • Fix the issues
  • Mark as ready for review again
4

CoPilot AI review

CoPilot may review your code automatically or on request:
  • Participate in the AI review process
  • Respond to helpful comments
  • Indicate comments you’ll ignore and why
  • Some AI comments may not be useful - that’s okay
5

Approval and merge

When approved:
  • PR will be merged
  • Change will be active in the next alpha build

​
After Merging

Your responsibility doesn’t end at merge! Watch for feedback from alpha users and testers.
You may need to follow up to:
  • Address bugs discovered in testing
  • Handle missed use-cases
  • Clarify documentation
  • Fix regressions

​
Best Practices

Be thorough

Fill out all sections of the template completely. Reviewers need context.

Be responsive

Respond to review comments promptly. This speeds up the review process.

Be patient

Reviews take time. Reviewers are volunteers with limited time.

Be collaborative

Work with reviewers to improve your PR. Their feedback helps you grow.

​
Getting Help

If you need help with your PR:
Reviewers appreciate well-documented PRs with clear testing instructions. The more effort you put into your PR description, the faster the review process will go!

Build docs developers (and LLMs) love

Get started for freeTalk to us