> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Pull Requests

> Guide for creating and managing pull requests in the NVDA project

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.

<Note>
  Before creating a PR, ensure you've discussed your changes in an issue (except for minor/trivial changes). See the [contributing guide](/development/contributing) for details.
</Note>

## 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

<Warning>
  Use a descriptive title of the changes. Avoid relying solely on issue or PR references - ensure the title is self-descriptive.
</Warning>

**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

### Link to Issue Number

Include the issue number and how the PR relates to it:

```markdown theme={null}
Fixes #1234
Closes #5678
Related to #9012
```

<Tip>
  GitHub [automatically closes issues using keywords](https://help.github.com/en/articles/closing-issues-using-keywords). When you write `closes #7777` or `fixes #4242`, the mentioned issue will automatically close when the PR is merged.
</Tip>

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:

```markdown theme={null}
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:

```markdown theme={null}
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:

```markdown theme={null}
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

<Warning>
  This is a critical section. Provide a detailed description of the technical changes and your reasoning.
</Warning>

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:**

```markdown theme={null}
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

<Note>
  This section allows you to convince reviewers (and yourself) that your change works correctly and should be merged.
</Note>

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:

<Steps>
  <Step title="Configure NVDA settings">
    In NVDA settings ensure that:

    * Keyboard category:
      * "speak typed characters" is unchecked
      * "speak typed words" is checked
  </Step>

  <Step title="Perform test actions">
    1. Open Notepad
    2. Type "hello"
    3. Press space
  </Step>

  <Step title="Expected result">
    Expect "hello" to be announced.
  </Step>
</Steps>

<Tip>
  **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
</Tip>

### Known Issues with Pull Request

Be transparent about limitations or downsides:

```markdown theme={null}
- 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](https://github.com/nvaccess/nvda/tree/master/tests/manual)?
  * 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](https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/deprecations.md)

### Documentation

* **Change log entries** - [Ensure there's an entry if required](/development/contributing#change-log-entry)
* **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

<Warning>
  Windows allows NVDA to access secure information while the lock screen is activated. Special precautions are needed.
</Warning>

When handling NVDAObjects, check if an object should be available while the lock screen is activated:

```python theme={null}
if utils.security._isSecureObjectWhileLockScreenActivated(obj):
    # Object should not be processed - return gracefully
    return
```

For code that should not run on [secure screens](https://download.nvaccess.org/documentation/userGuide.html#SecureScreens):

```python theme={null}
# 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

<Tabs>
  <Tab title="Draft PR">
    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.
  </Tab>

  <Tab title="Ready for Review">
    Mark your PR as ready for review when:

    * All code is complete
    * Tests are passing
    * Documentation is updated
    * Template is fully filled out
  </Tab>
</Tabs>

### Important Settings

<Warning>
  All pull requests must have "Allow edits from maintainers" checkbox ticked. This is the GitHub default for new PRs, except for organisation forks.
</Warning>

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

<Note>
  Sometimes system tests fail unexpectedly. If you believe the failure is unrelated, feel free to ignore it unless raised by a reviewer.
</Note>

### Security Checks

Automated security checks verify code safety.

## Code Review Process

Participate actively in the review process:

<Steps>
  <Step title="Core developers review">
    Core NVDA developers will:

    * Understand the intent of the change
    * Read the code changes
    * Ask questions or suggest changes
  </Step>

  <Step title="Respond to feedback">
    * Answer questions promptly
    * Discuss suggested changes
    * Update code based on feedback
    * Be proactive to speed up the process
  </Step>

  <Step title="Address review comments">
    If issues are raised:

    * PR may be marked as draft
    * Fix the issues
    * Mark as ready for review again
  </Step>

  <Step title="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
  </Step>

  <Step title="Approval and merge">
    When approved:

    * PR will be merged
    * Change will be active in the next alpha build
  </Step>
</Steps>

## After Merging

<Warning>
  Your responsibility doesn't end at merge! Watch for feedback from alpha users and testers.
</Warning>

You may need to follow up to:

* Address bugs discovered in testing
* Handle missed use-cases
* Clarify documentation
* Fix regressions

## Best Practices

<CardGroup cols={2}>
  <Card title="Be thorough" icon="magnifying-glass">
    Fill out all sections of the template completely. Reviewers need context.
  </Card>

  <Card title="Be responsive" icon="comments">
    Respond to review comments promptly. This speeds up the review process.
  </Card>

  <Card title="Be patient" icon="clock">
    Reviews take time. Reviewers are volunteers with limited time.
  </Card>

  <Card title="Be collaborative" icon="handshake">
    Work with reviewers to improve your PR. Their feedback helps you grow.
  </Card>
</CardGroup>

## Getting Help

If you need help with your PR:

* Ask questions in the PR comments
* Join the [NVDA Developers Mailing List](https://groups.io/g/nvda-devel)
* Start a [GitHub discussion](https://github.com/nvaccess/nvda/discussions)

<Tip>
  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!
</Tip>