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

# Contributing to NVDA

> Guide for contributing code and documentation to the NVDA project

Thank you for your interest in contributing to NVDA! The NVDA project welcomes contributions from developers around the world. Whether you're fixing bugs, adding features, or improving documentation, your help is valuable.

<Note>
  Please read and abide by the [Citizen and Contributor Code of Conduct](https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md) while participating in this project.
</Note>

## Before You Start

The NVDA project is guided by a [product vision statement and set of principles](https://github.com/nvaccess/nvda/blob/master/projectDocs/product_vision.md). Always consider the vision and principles when planning features and prioritizing work.

### Finding Issues to Work On

If you're new to the project or looking for ways to help, check out:

* [Good first issues](https://github.com/nvaccess/nvda/issues?q=label%3A%22good+first+issue%22)
* [Documentation issues](https://github.com/nvaccess/nvda/issues?q=label%3Acomponent%2Fdocumentation)
* [Issues needing new authors](https://github.com/nvaccess/nvda/issues?q=label%3Aclosed%2Fneeds-new-author)
* [Abandoned issues](https://github.com/nvaccess/nvda/issues?q=label%3AAbandoned)

## Guidelines

### Discuss Before You Code

<Warning>
  For anything other than minor bug fixes, please comment on an existing issue or create a new issue before starting to code.
</Warning>

* **Unrelated changes** should be addressed in separate issues
* Include information about:
  * Use cases
  * Design considerations
  * User experience implications
* Wait for acceptance of your proposal before coding
  * A `triaged` label indicates an issue is ready for a fix
  * Focus on higher priority issues (p1-p3) over lower priority ones (p4-p5)
* Consider starting a [GitHub discussion](https://github.com/nvaccess/nvda/discussions) or [mailing list topic](https://groups.io/g/nvda-devel/topics) to gauge interest

<Tip>
  We very likely will not accept changes that are not discussed first. If in doubt, use an issue to discuss your ideas before submitting code.
</Tip>

### Minor Changes Exception

You can create a pull request directly for minor/trivial changes that don't require design or implementation discussion:

* Typo fixes
* Obvious coding errors
* Simple synthesizer or braille display drivers

This should be fairly rare.

### Translation Issues

Issues with translations should be reported to the [NVDA Translators list](https://groups.io/g/nvda-translations).

## Contribution Process

<Steps>
  <Step title="Set up your development environment">
    [Set up your development environment](/development/setup) or use GitHub Actions to build NVDA for you by following the [CI/CD README](https://github.com/nvaccess/nvda/tree/master/ci/README.md).
  </Step>

  <Step title="Ensure the issue is triaged">
    Make sure the issue you plan to fix has been [triaged](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/triage.md) and has a priority assigned.
  </Step>

  <Step title="Create a branch">
    Create a branch for your contribution based on the latest commit in the official master branch. This helps reduce merge conflicts.
  </Step>

  <Step title="Build and test">
    * [Build NVDA](/development/building) and run from source
    * [Manually test your changes](/development/testing)
    * [Run automated tests](/development/testing#automated-tests)
  </Step>

  <Step title="Run pre-submission checks">
    Before opening your pull request, run:

    ```bash theme={null}
    rununittests.bat    # Run unit tests
    runlint.bat         # Check code style
    runcheckpot.bat     # Check translatable strings
    runlicensecheck.bat # Check dependency licenses
    ```

    All tests must pass before submission.
  </Step>

  <Step title="Update documentation">
    If you're adding a feature or changing something noticeable to users:

    * Update the User Guide
    * Document new commands, drivers, settings, dialogs, etc.
    * Follow the [User Guide standards](https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/userGuideStandards.md)
  </Step>

  <Step title="Create a change log entry">
    Add an entry to the [`changes.md` file](https://github.com/nvaccess/nvda/blob/master/user_docs/en/changes.md) in this format:

    ```markdown theme={null}
    ### New Features

    * Added a command to announce useful thing. (#1234, #4321, @myGitHub)

    ### Changes

    * Old command now also uses new useful command. (#1234)
    ```

    Available sections:

    * New features
    * Changes
    * Bug fixes
    * Changes for developers

    <Note>
      Change log entries are not required for changes with no/minor user impact or no developer impact.
    </Note>
  </Step>

  <Step title="Create a pull request">
    Fill out the [Pull Request template](https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/githubPullRequestTemplateExplanationAndExamples.md) including:

    * Link to issue number
    * Summary of the issue
    * Description of user-facing changes
    * Description of developer-facing changes
    * Development approach
    * Testing strategy
    * Known issues

    **Important:**

    * Enable "Allow edits from maintainers" (default for new PRs)
    * Use draft PRs for early feedback
    * Mark as "ready for review" when you want code review
    * Consider targeting `beta` or `rc` for bugs in the current release cycle
  </Step>

  <Step title="CI/CD checks">
    Every time you push a commit:

    * **pre-commit.ci** applies linting fixes automatically
      * Re-run with comment: `pre-commit.ci run`
      * Skip with `[skip ci]` in commit message
    * **GitHub Actions** builds NVDA and creates artifacts for testing
    * **System tests** run automatically
    * **Security checks** verify code safety

    Review any failures. Sometimes system tests fail unexpectedly - if you believe it's unrelated, note it in the PR.
  </Step>

  <Step title="Participate in code review">
    * Answer questions from reviewers
    * Discuss and implement suggested changes
    * Be proactive to speed up the review process
    * CoPilot AI may review your code - engage with helpful comments and explain why you're ignoring others

    When approved, your PR will be merged and included in the next alpha build.
  </Step>

  <Step title="Monitor feedback">
    After merging, watch for feedback from alpha users and testers. You may need to follow up to address bugs or missed use-cases.
  </Step>
</Steps>

## Code Style

Please follow the [coding standards](/development/code-standards) documented separately. Key points:

* Follow [PEP 8](https://peps.python.org/pep-0008/) except where it contradicts NVDA-specific guidance
* Use tabs for indentation, not spaces
* Include type hints for all new code
* Add docstrings for public functions and classes
* Use descriptive names for identifiers

The Ruff linter enforces Python code style automatically.

## Technical Design

Review the [technical design overview](https://github.com/nvaccess/nvda/blob/master/projectDocs/design/technicalDesignOverview.md) to understand NVDA's architecture.

## Copyright Headers

Refer to the guide on creating or updating [copyright headers](https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/copyrightHeaders.md).

## Ways to Contribute

Beyond code contributions, you can help NVDA in many ways:

* **[Reporting issues](/community/reporting-issues)** - Help identify bugs and suggest improvements
* **[Issue triage](/community/triage)** - Help investigate and categorize issues
* **[Testing](/development/testing)** - Test alpha and beta releases
* **[Translating](/development/translating)** - Localize NVDA to your language
* **[Creating add-ons](/development/addons)** - Extend NVDA's functionality

## Getting Help

If you need assistance:

* Join the [NVDA Developers Mailing List](https://groups.io/g/nvda-devel)
* Start a [GitHub discussion](https://github.com/nvaccess/nvda/discussions)
* Check the [NVDA Wiki](https://github.com/nvaccess/nvda/wiki) for additional guides

<Tip>
  The NVDA community is welcoming and supportive. Don't hesitate to ask questions!
</Tip>