diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 351c8e087a6..f0dcac354fa 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,91 +1,15 @@ # Contributing to NVDA -There are several ways in which you can contribute to the NVDA project: -- By testing NVDA -- Issue triage and investigation -- Code or documentation contributions - -## Testing - -Testing alpha / beta / and release candidates help to ensure the quality of the NVDA. -User / community testing is particularly important for languages other than English. -There are several approaches you may take for this: -- Unfocused usage: Just use NVDA as you normally would, and try to complete everyday tasks. -- Recent change focused testing: By following the changes that are being made to NVDA and purposefully testing these changes and looking for edge-cases. -- Regression testing: Testing older features and behavior to look for unintended regressions in behavior that don't seem related to recent changes. - -Forming a group can help you to get good coverage, brainstorm on what should be tested, and perhaps learn new ways to use NVDA. - -## Issue triage and investigation: -You can also make non-code contributions by helping process incoming GitHub issues. -For information on this please see the [triage process](../projectDocs/issues/triage.md). - -## Code/Docs contributions - -If you are new to the project, or looking for some way to help take a look at: -- [label:"good first issue"](https://github.com/nvaccess/nvda/issues?q=label%3A%22good+first+issue%22) -- [label:component/documentation](https://github.com/nvaccess/nvda/issues?q=label%3Acomponent%2Fdocumentation) -- [label:closed/needs-new-author](https://github.com/nvaccess/nvda/issues?q=label%3Aclosed%2Fneeds-new-author) -- [label:Abandoned](https://github.com/nvaccess/nvda/issues?q=label%3AAbandoned) - -### Guidelines: -- 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. -- It is recommended to wait for acceptance of your proposal before you start coding. - - A `triaged` label is an indicator that an issue is ready for a fix. - - Please understand that we very likely will not accept changes that are not discussed first. - - Consider starting a [GitHub discussion](https://github.com/nvaccess/nvda/discussions) or [mailing list topic](https://groups.io/g/nvda-devel/topics) to see if there is interest. -- A minor/trivial change which definitely wouldn't require design, user experience or implementation discussion, you can just create a pull request rather than using an issue first. - - e.g. a fix for a typo/obvious coding error or a simple synthesizer/braille display driver - - This should be fairly rare. -- If in doubt, use an issue first. Use this issue to discuss the alternatives you have considered in regards to implementation, design, and user experience. Then give people time to offer feedback. +Please note: the NVDA project has a [Citizen and Contributor Code of Conduct](./CODE_OF_CONDUCT.md). +NV Access expects that all contributors and other community members will read and abide by the rules set out in this document while participating or contributing to this project. -### GitHub process: -#### 1. "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: - ```sh - # 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 - ``` +The NVDA project is guided by a [product vision statement and set of principles](./projectDocs/product_vision.md). +The vision and principles should be always considered when planning features and prioritizing work. -#### 2. Use a separate "topic" branch for each contribution - 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. - If you are adding a feature or changing something that will be noticeable to the user, you should update the User Guide accordingly. - -#### 3. Run unit tests and lint check - - Run `rununittests` (`rununittests.bat`) before you open your Pull Request, and make sure all the unit tests pass. - - If possible for your PR, please consider creating a set of unit tests to test your changes. - - The lint check ensures your changes comply with our code style expectations. Use `runlint nvaccess/master` (`runlint.bat`) - -#### 4. Create a Pull Request (PR) - When you think a contribution is ready, or you would like feedback, open a draft pull request. - Please fill out the Pull Request Template, including the checklist of considerations. - The checklist asks you to confirm that you have thought about each of the items, if any of the items are missing it is helpful to explain elsewhere in the PR why it has been left out. - When you would like a review, mark the PR as "ready for review". - -#### 5. Participate in the code review process - This process requires core NVDA developers to understand the intent of the change, read the code changes, asking questions or suggesting changes. - Please participate in this process, answering questions, and discussing the changes. - Being proactive will really help to speed up the process of code review. - When the PR is approved it will be merged, and the change will be active in the next alpha build. - -#### 6. Feedback from alpha users - After a PR is merged, watch for feedback from alpha users / testers. - You may have to follow up to address bugs or missed use-cases. - -## Code Style - -Refer to [our coding standards document](../projectDocs/dev/codingStandards.md) +There are several ways in which you can contribute to the NVDA project: +- [Reporting issues](../projectDocs/issues/readme.md) +- [Issue triage and investigation](../projectDocs/issues/triage.md) +- [Testing](../projectDocs/testing/contributing.md) +- [Translating NVDA](https://github.com/nvaccess/nvda/wiki/Translating) +- [Code or documentation contributions](../projectDocs/dev/contributing.md) +- [Creating add-ons](../projectDocs/dev/addons.md) diff --git a/nvdaHelper/readme.md b/nvdaHelper/readme.md index dd7f8f670ad..b7121ccf3f5 100644 --- a/nvdaHelper/readme.md +++ b/nvdaHelper/readme.md @@ -99,6 +99,36 @@ You should still build on the command line to verify errors. - includes directories beginning with `/I` - Additional options like `/std:c++20` +### Compiling NVDAHelper with Debugging Options +Among other things, preparing the source tree builds the NVDAHelper libraries. +If trying to debug nvdaHelper, you can control various debugging options by building with the `nvdaHelperDebugFlags` and `nvdaHelperLogLevel` command line variables. + +The `nvdaHelperLogLevel` variable specifies the level of logging (0-59) you wish to see, lower is more verbose. The default is 15. + +The `nvdaHelperDebugFlags` variable takes one or more of the following flags: + +* debugCRT: the libraries will be linked against the debug C runtime and assertions will be enabled. (By default, the normal CRT is used and assertions are disabled.) +* RTC: runtime checks (stack corruption, uninitialized variables, etc.) will be enabled. (The default is no runtime checks.) +* analyze: runs MSVC code analysis on all nvdaHelper code, halting on any warning. (default is no analysis). + +The special keywords none and all can also be used in place of the individual flags. + +An example follows that enables debug CRT and runtime checks + +```cmd +scons source nvdaHelperDebugFlags=debugCRT,RTC +``` + +Symbol pdb files are always produced when building, regardless of the debug flags. +However, they are not included in the NVDA distribution. +Instead, `scons symbolsArchive` will package them as a separate archive. + +By default, builds also do not use any compiler optimizations. +Please see the `release` keyword argument for what compiler optimizations it will enable. + +### Building nvdaHelper developer documentation +[Refer to this section](../projectDocs/dev/buildingDevDocumentation.md#building-nvdahelper-developer-documentation) + ### Virtual Buffer Backends This code runs within the target applications process, it is responsible for building the virtual buffer. @@ -138,4 +168,4 @@ This code is responsible for interacting with the IA2 accessibility API, these c #### Build notes IDL/ACF files are input to MSRPCStubs to generate headers in `build/` - See `MSRPCStubs` in `*scons*` files. -- Note these set a prefix, making whole word searches for methods difficult. \ No newline at end of file +- Note these set a prefix, making whole word searches for methods difficult. diff --git a/projectDocs/community/readme.md b/projectDocs/community/readme.md new file mode 100644 index 00000000000..68f3d9625f9 --- /dev/null +++ b/projectDocs/community/readme.md @@ -0,0 +1,36 @@ +## Get support +Whether you are a beginner, an advanced user, a new or a long time developer; or if you represent an organization wishing to know more or to contribute to NVDA: you can get support through the included documentation as well as several communication channels dedicated to the NVDA screen reader. Here is an overview of the most important support sources. + +### Important links +* You can find information on user support on the [NV Access website](https://www.nvaccess.org/get-help/). +* [Reporting issues on GitHub](../issues/readme.md) +* [NVDA on GitHub](https://github.com/nvaccess/nvda) +* [Contributing to NVDA](../../.github/CONTRIBUTING.md). +This includes information on reporting issues, triaging issues, testing, translating, contributing code/documentation and creating add-ons. +* The NVDA repository [Wiki](https://github.com/nvaccess/nvda/wiki) contains more guides and documentation. +* [NVDA development snapshots](https://www.nvaccess.org/files/nvda/snapshots/): Automatically generated builds of the project in its current state of development +* [Translating NVDA](https://github.com/nvaccess/nvda/wiki/Translating): Information about how to translate NVDA into another language + +### Documentation +* [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html) +* [NVDA Developer Guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html) +* [Key Commands](https://www.nvaccess.org/files/nvda/documentation/keyCommands.html) +* [Changes in the latest release](https://www.nvaccess.org/files/nvda/documentation/changes.html) + +### Add-ons +* [The NVDA Add-on store](https://www.nvaccess.org/files/nvda/documentation/userGuide.html#AddonsManager) +* [Community add-ons website](https://addons.nvda-project.org/). +This website is considered legacy software, using the NVDA Add-on Store instead is encouraged. + +### Communication channels +#### NV Access +* See the [NV Access](https://www.nvaccess.org/contact-us/) website for our social media accounts and other contact information. +* [NVDA Add-on API Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-api) + +#### NVDA Community +* [NVDA Users Mailing List](https://nvda.groups.io/g/nvda) +* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel) +* [NVDA Translators list](https://groups.io/g/nvda-translations) +* [NVDA Add-ons Mailing List](https://groups.io/g/nvda-addons) +* [NVDA Community Gitter channel](https://gitter.im/nvaccess/NVDA) (Instant Messaging) +* [Other sources including groups and profiles on social media channels, language-specific websites and mailing lists etc.](https://github.com/nvaccess/nvda/wiki/Connect) diff --git a/projectDocs/dev/addons.md b/projectDocs/dev/addons.md new file mode 100644 index 00000000000..a6124cdfad0 --- /dev/null +++ b/projectDocs/dev/addons.md @@ -0,0 +1,32 @@ +### Important links +* [Changes in the latest release](https://www.nvaccess.org/files/nvda/documentation/changes.html) +* [NVDA Add-on API Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-api) +* [The NVDA Add-on Store](https://www.nvaccess.org/files/nvda/documentation/userGuide.html#AddonsManager) +* [Submitting to the NVDA Add-on Store](https://github.com/nvaccess/addon-datastore/blob/master/docs/submitters/submissionGuide.md) +* [Community add-ons website](https://addons.nvda-project.org/). +This website is considered legacy software, using the NVDA Add-on Store instead is encouraged. +* [NVDA add-ons community coordination and support center](https://github.com/nvdaaddons): all about NVDA's add-ons environment +* [NVDA add-ons community template](https://github.com/nvdaaddons/AddonTemplate): A repository for generating add-ons using a template +* The NVDA repository [Wiki](https://github.com/nvaccess/nvda/wiki) contains more guides and documentation. + +### Documentation +* [NVDA Developer Guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html) +* [Technical design overview](../design/technicalDesignOverview.md) +* [NVDA Add-on Development Community Guide](https://github.com/nvdaaddons/DevGuide/wiki/NVDA-Add-on-Development-Guide) +* [NVDA ControllerClient manual (NVDA API for external applications to directly speak or braille messages, etc.)](../../extras/controllerClient) + +### Communication channels +#### NV Access +* [GitHub discussions](https://github.com/nvaccess/nvda/discussions) +* [NVDA Add-on API Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-api) + +#### NVDA Community +* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel) +* [NVDA Add-ons Mailing List](https://groups.io/g/nvda-addons) +* [NVDA Community Gitter channel](https://gitter.im/nvaccess/NVDA) (Instant Messaging) +* [Other sources including groups and profiles on social media channels, language-specific websites and mailing lists etc.](https://github.com/nvaccess/nvda/wiki/Connect) + +## NVDA project links +* [NVDA on GitHub](https://github.com/nvaccess/nvda) +* [Reporting issues on GitHub](../issues/readme.md) +* [NVDA development snapshots](https://www.nvaccess.org/files/nvda/snapshots/): Automatically generated builds of the project in its current state of development diff --git a/projectDocs/dev/buildingDevDocumentation.md b/projectDocs/dev/buildingDevDocumentation.md new file mode 100644 index 00000000000..5119451bb98 --- /dev/null +++ b/projectDocs/dev/buildingDevDocumentation.md @@ -0,0 +1,30 @@ +Before building developer documentation, [create your developer environment](./createDevEnvironment.md). + +### Building developer documentation + +To generate the NVDA developer guide, type: + +```cmd +scons developerGuide +``` + +The developer guide will be placed in the `devDocs` folder in the output directory. + +To generate the HTML-based source code documentation, type: + +```cmd +scons devDocs +``` + +The documentation will be placed in the `NVDA` folder in the output directory. + +### Building nvdaHelper developer documentation + +To generate developer documentation for nvdaHelper (not included in the devDocs target): + +``` +scons devDocs_nvdaHelper +``` + +The documentation will be placed in the folder `\output\devDocs\nvdaHelper`. +This requires having Doxygen installed. diff --git a/projectDocs/dev/buildingNVDA.md b/projectDocs/dev/buildingNVDA.md new file mode 100644 index 00000000000..004715507e1 --- /dev/null +++ b/projectDocs/dev/buildingNVDA.md @@ -0,0 +1,90 @@ +Before building NVDA, [create your developer environment](./createDevEnvironment.md). + +## Preparing the Source Tree +Before you can run the NVDA source code, you must prepare the source tree. +You do this by opening a command prompt, changing to the root of the NVDA source distribution and typing: + +```cmd +scons source +``` + +You should do this again whenever the version of comtypes changes or language files are added or changed. +Note that if you want to access user documentation from the help menu while running the source version, you will also need to add `user_docs` to the command line like so: + +```cmd +scons source user_docs +``` + +While simply testing or committing changes, it may be faster usually just doing `scons source` as user documentation will change each time the revision number changes. + +## Running the Source Code +It is possible to run NVDA directly from source without having to build the full binary package and launcher. +To launch NVDA from source, using `cmd.exe`, execute `runnvda.bat` in the root of the repository. + +To view help on the arguments that NVDA will accept, use the `-h` or `--help` option. +These arguments are also documented in the [user guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html#CommandLineOptions). + +## Building NVDA +A binary build of NVDA can be run on a system without Python and all of NVDA's other dependencies installed (as we do for snapshots and releases). + +Binary archives and bundles can be created using scons from the root of the NVDA source distribution. To build any of the following, open a command prompt and change to that directory. + +To make a non-archived binary build (equivalent to an extracted portable archive), type: + +```cmd +scons dist +``` + +The build will be created in the dist directory. + +### Building the installer + +To create a launcher archive (one executable allowing for installation or portable dist generation), type: + +```cmd +scons launcher +``` + +The archive will be placed in the output directory. + +### Building developer documentation +Refer to [building developer documentation](./buildingDevDocumentation.md). + +### Generate debug symbols archive +To generate an archive of debug symbols for the various dll/exe binaries, type: + +```cmd +scons symbolsArchive +``` + +The archive will be placed in the output directory. + +### Generate translation template +To generate a gettext translation template (for translators), type: + +```cmd +scons pot +``` + +### Customising the build +Optionally, the build can be customised by providing variables on the command line. +This is useful when [creating a self signed build](./selfSignedBuild.md). + +* version: The version of this build. +* release: Whether this is a release version. + * This enables various C++ compiler optimizations such as /O2 and whole-program optimization. + * It also instructs Python to generate optimized byte code. +* publisher: The publisher of this build. +* certFile: The certificate file with which to sign executables. The certificate must be in pfx format and contain the private key. +* certPassword: The password for the private key in the signing certificate. If omitted, no password will be assumed. +* certTimestampServer: The URL of the timestamping server to use to timestamp authenticode signatures. If omitted, signatures will not be timestamped. +* outputDir: The directory where the final built archives and such will be placed. +* targetArchitectures: The target architectures that NVDA should support. Possible values are all, x86 and x86_64. This should generally be left as the default. + +For example, to build a launcher with a specific version, you might type: + +```cmd +scons launcher version=test1 +``` + +For more see the [sconstruct file](../../sconstruct). diff --git a/projectDocs/dev/contributing.md b/projectDocs/dev/contributing.md new file mode 100644 index 00000000000..49cf796e66a --- /dev/null +++ b/projectDocs/dev/contributing.md @@ -0,0 +1,62 @@ +## Code/Docs contributions + +If you are new to the project, or looking for some way to help take a look at: +- [label:"good first issue"](https://github.com/nvaccess/nvda/issues?q=label%3A%22good+first+issue%22) +- [label:component/documentation](https://github.com/nvaccess/nvda/issues?q=label%3Acomponent%2Fdocumentation) +- [label:closed/needs-new-author](https://github.com/nvaccess/nvda/issues?q=label%3Aclosed%2Fneeds-new-author) +- [label:Abandoned](https://github.com/nvaccess/nvda/issues?q=label%3AAbandoned) + +### Guidelines: +- 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. +- It is recommended to wait for acceptance of your proposal before you start coding. + - A `triaged` label is an indicator that an issue is ready for a fix. + - Please understand that we very likely will not accept changes that are not discussed first. + - Consider starting a [GitHub discussion](https://github.com/nvaccess/nvda/discussions) or [mailing list topic](https://groups.io/g/nvda-devel/topics) to see if there is interest. +- A minor/trivial change which definitely wouldn't require design, user experience or implementation discussion, you can just create a pull request rather than using an issue first. + - e.g. a fix for a typo/obvious coding error or a simple synthesizer/braille display driver + - This should be fairly rare. +- If in doubt, use an issue first. Use this issue to discuss the alternatives you have considered in regards to implementation, design, and user experience. Then give people time to offer feedback. + + +### Overview of contribution process: +1. [Setup your development environment](./createDevEnvironment.md). +1. Ensure the issue you plan to fix is [triaged](../issues/triage.md) +1. Create a branch for the contribution. + - Pull requests should be based on the latest commit in the official master branch. + This helps reduce the chance of merge conflicts. + - If you are adding a feature or changing something that will be noticeable to the user, you should update the User Guide accordingly. +1. [Build NVDA](./buildingNVDA.md) and run from source +1. [Manually test the change](../testing/readme.md) +1. [Run automated tests](../testing/automated.md) + - Run `rununittests` (`rununittests.bat`) before you open your Pull Request, and make sure all the unit tests pass. + - If possible for your PR, please consider creating a set of unit or system tests to test your changes. + - The lint check ensures your changes comply with our code style expectations. Use `runlint nvaccess/master` (`runlint.bat`) + - Run `scons checkPot` to ensure translatable strings have comments for the translators +1. [Create a Pull Request (PR)](./githubPullRequestTemplateExplanationAndExamples.md) + - When you think a contribution is ready, or you would like feedback, open a draft pull request. + When you would like a review, mark the PR as "ready for review". + - Please fill out the Pull Request template, including the checklist of considerations. + The checklist asks you to confirm that you have thought about each of the items, if any of the items are missing it is helpful to explain elsewhere in the PR why it has been left out. + - Automated checks will be run against your PR. + If these fail, please review them. + Sometimes system tests fail unexpectedly. + If you believe the failure is unrelated, feel free to ignore it unless it is raised by a reviewer. +1. Participate in the code review process + - This process requires core NVDA developers to understand the intent of the change, read the code changes, asking questions or suggesting changes. + Please participate in this process, answering questions, and discussing the changes. + - Being proactive will really help to speed up the process of code review. + - When the PR is approved it will be merged, and the change will be active in the next alpha build. + - If issues are raised with your PR, it may be marked as a draft. + Please mark it as ready for review when you have addressed the review comments. +1. Feedback from alpha users + - After a PR is merged, watch for feedback from alpha users / testers. + You may have to follow up to address bugs or missed use-cases. + +## Code Style +Please ensure you follow [our coding standards document](../projectDocs/dev/codingStandards.md). + +## Technical design +Please checkout our [technical design overview](../design/technicalDesignOverview.md). diff --git a/projectDocs/dev/createDevEnvironment.md b/projectDocs/dev/createDevEnvironment.md new file mode 100644 index 00000000000..1880fed7d49 --- /dev/null +++ b/projectDocs/dev/createDevEnvironment.md @@ -0,0 +1,99 @@ +## Getting the Source Code +The NVDA project uses the [git](https://www.git-scm.com/) version control system for its source code and documentation. + +The NVDA repository is located at https://github.com/nvaccess/nvda. + +If you plan on contributing to NVDA, you should [fork and clone](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository. + +Use the `--recursive` option when performing `git clone` to fetch the required git submodules we use. + +### Keeping the fork in sync +When you fork the repository, GitHub will create a copy of the master branch. +However, this branch will not be updated when the nvaccess master branch is updated. +To ensure your work is always based on the latest commit in the nvaccess master branch, it is recommended that your master branch be linked to the nvaccess master branch, rather than the master branch in your GitHub fork. +You can do this from the command line as follows: +```sh +# 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 +``` + +## Supported Operating Systems +Although NVDA can run on any Windows version starting from Windows 7 Service pack 1, building NVDA from source is currently limited to only Windows 10 and above. + +## Dependencies +The NVDA source depends on several other packages to run correctly. + +### Installed Dependencies +The following dependencies need to be installed on your system: + +* [Python](https://www.python.org/), version 3.7, 32 bit + * Use latest minor version if possible. +* Microsoft Visual Studio 2019 or 2022: + * To replicate the production build environment, use the [version of Visual Studio 2019 that AppVeyor is using](https://www.appveyor.com/docs/windows-images-software/#visual-studio-2019). + * When you do not use the Visual Studio IDE itself, you can download the [build tools](https://aka.ms/vs/16/release/vs_BuildTools.exe) + * When you are intending to use the Visual Studio IDE (not required for NVDA development), you can download [the community version](https://aka.ms/vs/16/release/vs_Community.exe), which is also used by appveyor + * The Professional and Enterprise versions are also supported + * Preview versions are *not* supported + * When installing Visual Studio 2019, you need to enable the following: + * In the list on the Workloads tab + * in the Windows grouping: + * Desktop development with C++ + * Then in the Installation details tree view, under Desktop for C++, Optional, ensure the following are selected: + * MSVC v142 - VS 2019 C++ x64/x86 build tools + * Windows 11 SDK (10.0.22000.0) + * C++ ATL for v142 build tools (x86 & x64) + * C++ Clang tools for Windows + * On the Individual components tab, ensure the following items are selected: + * MSVC v142 - VS 2019 C++ ARM64 build tools + * C++ ATL for v142 build tools (ARM64) + * If installing Visual Studio 2022: choose all the same above components as for 2019, but V143 variants, rather than V142. + +### Git Submodules +Some of the dependencies are contained in Git submodules. +If you didn't pass the `--recursive` option to git clone, you will need to run `git submodule update --init`. +Whenever a required submodule commit changes (e.g. after git pull), you will need to run `git submodule update`. +If you aren't sure, run `git submodule update` after every git pull, merge or checkout. + +For reference, the following run time dependencies are included in Git submodules: + +* [eSpeak NG](https://github.com/espeak-ng/espeak-ng), version 1.52-dev commit `ed9a7bcf` +* [Sonic](https://github.com/waywardgeek/sonic), commit 1d705135 +* [IAccessible2](https://wiki.linuxfoundation.org/accessibility/iaccessible2/start), commit cbc1f29631780 +* [liblouis](http://www.liblouis.io/), version 3.26.0 +* [Unicode Common Locale Data Repository (CLDR)](http://cldr.unicode.org/), version 42.0 +* NVDA images and sounds +* [Adobe Acrobat accessibility interface, version XI](https://download.macromedia.com/pub/developer/acrobat/AcrobatAccess.zip) +* [Microsoft Detours](https://github.com/microsoft/Detours), commit 45a76a3 +* brlapi Python bindings, version 0.8 or later, distributed with [BRLTTY for Windows](https://brltty.app/download.html), version 6.1 +* lilli.dll, version 2.1.0.0 +* [Python interface to FTDI driver/chip](http://fluidmotion.dyndns.org/zenphoto/index.php?p=news&title=Python-interface-to-FTDI-driver-chip) +* [Nullsoft Install System](https://nsis.sourceforge.io), version 3.08 +* Java Access Bridge 32 bit, from Zulu Community OpenJDK build 13.0.1+10Zulu (13.28.11) +* [Microsoft UI Automation Remote Operations Library, forked from @microsoft by @michaeldcurran](https://www.github.com/michaeldcurran/microsoft-ui-uiautomation/) + * Commit 224b22f3bf9e + * The fork specifically adds support for CallExtension / IsExtensionSupported to the high-level API, see pr microsoft/microsoft-ui-uiautomation#84. + +Additionally, the following build time dependencies are included in the miscDeps git submodule: + +* [txt2tags](https://txt2tags.org/), version 2.5 +* xgettext and msgfmt from [GNU gettext](https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/) + +The following dependencies aren't needed by most people, and are not included in Git submodules: +* To generate [developer documentation for nvdaHelper](#building-nvdahelper-developer-documentation): [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15: +* When you are using Visual Studio Code as your integrated development environment of preference, you can make use of our [prepopulated workspace configuration](https://github.com/nvaccess/vscode-nvda/) for [Visual Studio Code](https://code.visualstudio.com/). + While this VSCode project is not included as a submodule in the NVDA repository, you can easily check out the workspace configuration in your repository by executing the following from the root of the repository. + + ```sh + git clone https://github.com/nvaccess/vscode-nvda.git .vscode + ``` + +### Python dependencies +NVDA and its build system also depend on an extensive list of Python packages. They are all listed with their specific versions in the requirements.txt file in the root of this repository. However, the build system takes care of fetching these itself when needed. These packages will be installed into an isolated Python virtual environment within this repository, and will not affect your system-wide set of packages. diff --git a/projectDocs/dev/readme.md b/projectDocs/dev/readme.md new file mode 100644 index 00000000000..3a4d32e7836 --- /dev/null +++ b/projectDocs/dev/readme.md @@ -0,0 +1,24 @@ +### Important links +* [Refer to contributing.md](./contributing.md) for contributing code/documentation to NVDA. +* [Refer to addons.md](./addons.md) for key links for add-on development. +* [Reporting issues on GitHub](../issues/readme.md) +* [Contributing to NVDA](../../.github/CONTRIBUTING.md). +This includes information on reporting issues, triaging issues, testing, translating, contributing code/documentation and creating add-ons. +* The NVDA repository [Wiki](https://github.com/nvaccess/nvda/wiki) contains more guides and documentation. +* [NVDA development snapshots](https://www.nvaccess.org/files/nvda/snapshots/): Automatically generated builds of the project in its current state of development + +### Documentation +* [NVDA Developer Guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html) +* [Technical design overview](../design/technicalDesignOverview.md) +* [NVDA ControllerClient manual (NVDA API for external applications to directly speak or braille messages, etc.)](https://github.com/nvaccess/nvda/tree/master/extras/controllerClient) + +### Communication channels +#### NV Access +* [NVDA on GitHub](https://github.com/nvaccess/nvda) + * Report [NVDA issues and feature requests on GitHub](https://github.com/nvaccess/nvda/issues). + * Start a [GitHub discussion with the development community](https://github.com/nvaccess/nvda/discussions). +* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel) + +#### NVDA Community +* [NVDA Community Gitter channel](https://gitter.im/nvaccess/NVDA) (Instant Messaging) +* [Other sources including groups and profiles on social media channels, language-specific websites and mailing lists etc.](https://github.com/nvaccess/nvda/wiki/Connect) diff --git a/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md b/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md index 16c894775df..71cd0bd7a23 100644 --- a/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md +++ b/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md @@ -44,7 +44,7 @@ Most tools allow you to copy text out of them. the issue reads as expected. * If you have trouble following this template, or with the initial investigation that is required, please politely ask for assistance from the fantastic community of people on the - [NVDA users mailing list](https://github.com/nvaccess/nvda-community/wiki/Connect#international-users-mailing-list-english) + [NVDA users mailing list](https://github.com/nvaccess/nvda/wiki/Connect#international-users-mailing-list-english) ## Feature Request template diff --git a/projectDocs/issues/readme.md b/projectDocs/issues/readme.md new file mode 100644 index 00000000000..a546633d404 --- /dev/null +++ b/projectDocs/issues/readme.md @@ -0,0 +1,12 @@ +## Reporting issues or feature requests + +Issues can be [reported via GitHub](https://github.com/nvaccess/nvda/issues/new/choose). +Please read the [issue template guide](./githubIssueTemplateExplanationAndExamples.md) for help filling out the appropriate template. +For advanced reporters, consider reading our [issue triage guide](./triage.md) to ensure the issue can easily be worked on. +If you don't have a clear idea of the issue, and you are unable to fill out the template, open a [GitHub discussion instead](https://github.com/nvaccess/nvda/discussions). + +Do not report security issues via GitHub, instead follow our [security policy](../../security.md). + +If you are reporting an issue with an application or website, please consider reporting the issue to the authors of the application/website first. + +If you are a developer reporting an issue with your application/website, please include a minimal reproducible sample and details of the specification not being handled correctly. diff --git a/projectDocs/testing/automated.md b/projectDocs/testing/automated.md new file mode 100644 index 00000000000..5b171ad4150 --- /dev/null +++ b/projectDocs/testing/automated.md @@ -0,0 +1,52 @@ +## Running Automated Tests +If you make a change to the NVDA code, you should run NVDA's automated tests. +These tests help to ensure that code changes do not unintentionally break functionality that was previously working. + +To run the tests (unit tests, translatable string checks), first change directory to the root of the NVDA source distribution as above. +Then, run: + +```cmd +scons tests +``` + +### Unit tests +To run only specific unit tests, specify them using the `unitTests` variable on the command line. +The tests should be provided as a comma-separated list. +Each test should be specified as a Python module, class or method relative to the `tests\unit` directory. +For example, to run only methods in the `TestMove` and `TestSelection` classes in the file `tests\unit\test_cursorManager.py` file, run this command: + +```cmd +scons tests unitTests=test_cursorManager.TestMove,test_cursorManager.TestSelection +``` + +### Translatable string checks +To run only the translatable string checks (which check that all translatable strings have translator comments), run: + +```cmd +scons checkPot +``` + +### Linting your changes +In order to ensure your changes comply with NVDA's coding style you can run the Flake8 linter locally. +Some developers have found certain linting error messages misleading, these are clarified in `tests/lint/readme.md`. +runlint.bat will use Flake8 to inspect only the differences between your working directory and the specified `base` branch. +If you create a Pull Request, the `base` branch you use here should be the same as the target you would use for a Pull Request. In most cases it will be `origin/master`. +```cmd +runlint origin/master +``` + +To be warned about linting errors faster, you may wish to integrate Flake8 with other development tools you are using. +For more details, see `tests/lint/readme.md` + +### Unit Tests +Unit tests can be run with the `rununittests.bat` script. +Internally this script uses the Nose Python test framework to execute the tests. +Any arguments given to `rununittests.bat` are forwarded onto Nose. +Please refer to Nose's own documentation on how to filter tests etc. + +### System Tests +System tests can be run with the `runsystemtests.bat --include ` script. +To run all tests standard tests for developers use `runsystemtests.bat --include NVDA`. +Internally this script uses the Robot test framework to execute the tests. +Any arguments given to `runsystemtests.bat` are forwarded onto Robot. +For more details (including filtering and exclusion of tests) see `tests/system/readme.md`. diff --git a/projectDocs/testing/contributing.md b/projectDocs/testing/contributing.md new file mode 100644 index 00000000000..61ad4f38130 --- /dev/null +++ b/projectDocs/testing/contributing.md @@ -0,0 +1,31 @@ + +## Manual testing + +Testing alpha / beta / and release candidates help to ensure the quality of the NVDA project. +You can find the latest alpha snapshots [here](https://www.nvaccess.org/files/nvda/snapshots/). + +User / community testing is particularly important for languages other than English. + +NVDA includes [manual test plans](../../tests/manual/README.md) to guide testers in smoke testing features of NVDA. + +There are several approaches you may take for testing: +- Unfocused usage: Just use NVDA as you normally would, and try to complete everyday tasks. +- Recent change focused testing: By following the changes that are being made to NVDA and purposefully testing these changes and looking for edge-cases. +- Regression testing: Testing older features and behavior to look for unintended regressions in behavior that don't seem related to recent changes. +- Pull request testing. +Testing pull requests can be done + 1. Go to the pull request page. + 1. Navigate to the linked "Details of continuous integration", this is towards the end of the PR, as part of the checks and approval status. + 1. Go to the "Artifacts" tab + 1. Download the NVDA installer, named something like `output\nvda_snapshot_pr15335-28962,a2970e3f.exe` + 1. The pull request should contain some information on how to test this change. +- Confirming bugs. +By following the [issue triage process](../issues/triage.md) you can help confirm bugs and debug issues. + +Forming a group can help you to get good coverage, brainstorm on what should be tested, and perhaps learn new ways to use NVDA. + +## Automated testing + +NVDA performs automated testing as part of CI/CD. +This includes linting checks, unit tests and system tests. +Refer to our [automated testing](./automated.md) document. diff --git a/projectDocs/testing/readme.md b/projectDocs/testing/readme.md new file mode 100644 index 00000000000..674e93588c0 --- /dev/null +++ b/projectDocs/testing/readme.md @@ -0,0 +1,17 @@ +### Important links +* [How to contribute to NVDA by testing](./contributing.md) +* [Reporting issues on GitHub](../issues/readme.md) +* [Triaging issues on GitHub](../issues/triage.md) +* The NVDA repository [Wiki](https://github.com/nvaccess/nvda/wiki) contains more guides and documentation. +* [NVDA development snapshots](https://www.nvaccess.org/files/nvda/snapshots/): Automatically generated builds of the project in its current state of development + +### Documentation +* [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html) +* [Changes in the latest release](https://www.nvaccess.org/files/nvda/documentation/changes.html) +* [Manual test plans](../../tests/manual/README.md) +* [Automated tests for developers](./automated.md) + +### Community communication channels +* [NVDA Users Mailing List](https://nvda.groups.io/g/nvda) +* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel) +* [Other sources including groups and profiles on social media channels, language-specific websites and mailing lists etc.](https://github.com/nvaccess/nvda/wiki/Connect) diff --git a/readme.md b/readme.md index 03373f77ea8..69e3915b438 100644 --- a/readme.md +++ b/readme.md @@ -8,315 +8,16 @@ Please note: the NVDA project has a [Citizen and Contributor Code of Conduct](CO The NVDA project is guided by a [product vision statement and set of principles](./projectDocs/product_vision.md). The vision and principles should be always considered when planning features and prioritizing work. - -## Get support -Whether you are a beginner, an advanced user, a new or a long time developer; or if you represent an organization wishing to know more or to contribute to NVDA: you can get support through the included documentation as well as several communication channels dedicated to the NVDA screen reader. Here is an overview of the most important support sources. - -### Documentation -* [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html) -* [NVDA Developer Guide](https://www.nvaccess.org/files/nvda/documentation/developerGuide.html) -* [NVDA Add-ons Development Internals](https://github.com/nvdaaddons/DevGuide/wiki) -* [NVDA ControllerClient manual (NVDA API for external applications to directly speak or braille messages, etc.)](https://github.com/nvaccess/nvda/tree/master/extras/controllerClient) -* Further documentation is available in the NVDA repository's [Wiki](https://github.com/nvaccess/nvda/wiki), and in the [Community Wiki](https://github.com/nvaccess/nvda-community/wiki) - -### Communication channels -* [NVDA Users Mailing List](https://nvda.groups.io/g/nvda) -* [NVDA Developers Mailing List](https://groups.io/g/nvda-devel) -* [NVDA Add-ons Mailing List](https://groups.io/g/nvda-addons) -* [NVDA Add-on API Mailing List](https://groups.google.com/a/nvaccess.org/g/nvda-api) -* [Instant Messaging channel for NVDA Support](https://gitter.im/nvaccess/NVDA) -* [Other sources including groups and profiles on social media channels, language-specific websites and mailing lists etc.](https://github.com/nvaccess/nvda-community/wiki/Connect) - -You can also get direct support from NV Access. See the [NV Access](http://www.nvaccess.org/) website for more details. - -## Other Key Project Links -* [NVDA on GitHub](https://github.com/nvaccess/nvda) -* [NVDA issues on GitHub](https://github.com/nvaccess/nvda/issues): Bug reports, feature requests, etc. -* [NVDA development snapshots](https://www.nvaccess.org/files/nvda/snapshots/): Automatically generated builds of the project in its current state of development -* [NVDA add-ons](https://addons.nvda-project.org/): Get add-ons to enhance NVDA -* [NVDA Add-ons coordination and support center](https://github.com/nvdaaddons): all about NVDA's addons environment -* [NVDA Add-ons Template](https://github.com/nvdaaddons/AddonTemplate): A repository for generating the Add-ons template -* [Translating NVDA](https://github.com/nvaccess/nvda/wiki/Translating): Information about how to translate NVDA into another language -* [Contributing to NVDA](./.github/CONTRIBUTING.md): Suggestions on how to contribute to the NVDA project, including issue triage, development and documentation. -* [NVDA commits email list](https://lists.sourceforge.net/lists/listinfo/nvda-commits): Notifications for all commits to the Git repository -* [Old email archives](http://nabble.nvda-project.org/Development-f1.html): contain discussions about NVDA development - -## Getting the Source Code -The NVDA project uses the [Git](https://www.git-scm.com/) version control system for its source code and documentation. - -The NVDA Git repository is located at https://github.com/nvaccess/nvda.git. You can clone it with the following command, which will place files in a directory named `nvda`: - -``` -git clone --recursive https://github.com/nvaccess/nvda.git -``` - -The `--recursive` option is needed to retrieve various Git submodules we use. - -## Supported Operating Systems -Although NVDA can run on any Windows version starting from Windows 7 Service pack 1, building NVDA from source is currently limited to only Windows 10 and above. - -## Dependencies -The NVDA source depends on several other packages to run correctly. - -### Installed Dependencies -The following dependencies need to be installed on your system: - -* [Python](https://www.python.org/), version 3.7, 32 bit - * Use latest minor version if possible. -* Microsoft Visual Studio 2019 or 2022: - * To replicate the production build environment, use the [version of Visual Studio 2019 that AppVeyor is using](https://www.appveyor.com/docs/windows-images-software/#visual-studio-2019). - * When you do not use the Visual Studio IDE itself, you can download the [build tools](https://aka.ms/vs/16/release/vs_BuildTools.exe) - * When you are intending to use the Visual Studio IDE (not required for NVDA development), you can download [the community version](https://aka.ms/vs/16/release/vs_Community.exe), which is also used by appveyor - * The Professional and Enterprise versions are also supported - * Preview versions are *not* supported - * When installing Visual Studio 2019, you need to enable the following: - * In the list on the Workloads tab - * in the Windows grouping: - * Desktop development with C++ - * Then in the Installation details tree view, under Desktop for C++, Optional, ensure the following are selected: - * MSVC v142 - VS 2019 C++ x64/x86 build tools - * Windows 11 SDK (10.0.22000.0) - * C++ ATL for v142 build tools (x86 & x64) - * C++ Clang tools for Windows - * On the Individual components tab, ensure the following items are selected: - * MSVC v142 - VS 2019 C++ ARM64 build tools - * C++ ATL for v142 build tools (ARM64) - * If installing Visual Studio 2022: choose all the same above components as for 2019, but V143 variants, rather than V142. - -### Git Submodules -Some of the dependencies are contained in Git submodules. -If you didn't pass the `--recursive` option to git clone, you will need to run `git submodule update --init`. -Whenever a required submodule commit changes (e.g. after git pull), you will need to run `git submodule update`. -If you aren't sure, run `git submodule update` after every git pull, merge or checkout. - -For reference, the following run time dependencies are included in Git submodules: - -* [eSpeak NG](https://github.com/espeak-ng/espeak-ng), version 1.52-dev commit `ed9a7bcf` -* [Sonic](https://github.com/waywardgeek/sonic), commit 1d705135 -* [IAccessible2](https://wiki.linuxfoundation.org/accessibility/iaccessible2/start), commit cbc1f29631780 -* [liblouis](http://www.liblouis.io/), version 3.26.0 -* [Unicode Common Locale Data Repository (CLDR)](http://cldr.unicode.org/), version 42.0 -* NVDA images and sounds -* [Adobe Acrobat accessibility interface, version XI](https://download.macromedia.com/pub/developer/acrobat/AcrobatAccess.zip) -* [Microsoft Detours](https://github.com/microsoft/Detours), commit 45a76a3 -* brlapi Python bindings, version 0.8 or later, distributed with [BRLTTY for Windows](https://brltty.app/download.html), version 6.1 -* lilli.dll, version 2.1.0.0 -* [Python interface to FTDI driver/chip](http://fluidmotion.dyndns.org/zenphoto/index.php?p=news&title=Python-interface-to-FTDI-driver-chip) -* [Nullsoft Install System](https://nsis.sourceforge.io), version 3.08 -* Java Access Bridge 32 bit, from Zulu Community OpenJDK build 13.0.1+10Zulu (13.28.11) -* [Microsoft UI Automation Remote Operations Library, forked from @microsoft by @michaeldcurran](https://www.github.com/michaeldcurran/microsoft-ui-uiautomation/) - * Commit 224b22f3bf9e - * The fork specifically adds support for CallExtension / IsExtensionSupported to the high-level API, see pr microsoft/microsoft-ui-uiautomation#84. - -Additionally, the following build time dependencies are included in the miscDeps git submodule: - -* [txt2tags](https://txt2tags.org/), version 2.5 -* xgettext and msgfmt from [GNU gettext](https://sourceforge.net/projects/cppcms/files/boost_locale/gettext_for_windows/) - -The following dependencies aren't needed by most people, and are not included in Git submodules: -* To generate [developer documentation for nvdaHelper](#building-nvdahelper-developer-documentation): [Doxygen Windows installer](http://www.doxygen.nl/download.html), version 1.8.15: -* When you are using Visual Studio Code as your integrated development environment of preference, you can make use of our [prepopulated workspace configuration](https://github.com/nvaccess/vscode-nvda/) for [Visual Studio Code](https://code.visualstudio.com/). - While this VSCode project is not included as a submodule in the NVDA repository, you can easily check out the workspace configuration in your repository by executing the following from the root of the repository. - - ```git clone https://github.com/nvaccess/vscode-nvda.git .vscode``` -### Python dependencies -NVDA and its build system also depend on an extensive list of Python packages. They are all listed with their specific versions in the requirements.txt file in the root of this repository. However, the build system takes care of fetching these itself when needed. These packages will be installed into an isolated Python virtual environment within this repository, and will not affect your system-wide set of packages. +NVDA is available under a modified GNU General Public License version 2. +Please refer to [our license](./copying.txt) for more information. -## Preparing the Source Tree -Before you can run the NVDA source code, you must prepare the source tree. -You do this by opening a command prompt, changing to the root of the NVDA source distribution and typing: - -``` -scons source -``` - -You should do this again whenever the version of comtypes changes or language files are added or changed. -Note that if you want to access user documentation from the help menu while running the source version, you will also need to add `user_docs` to the command line like so: - -``` -scons source user_docs -``` - -While simply testing or committing changes, it may be faster usually just doing `scons source` as user documentation will change each time the revision number changes. - -### Compiling NVDAHelper with Debugging Options -Among other things, preparing the source tree builds the NVDAHelper libraries. -If trying to debug nvdaHelper, you can control various debugging options by building with the `nvdaHelperDebugFlags` and `nvdaHelperLogLevel` command line variables. - -The `nvdaHelperLogLevel` variable specifies the level of logging (0-59) you wish to see, lower is more verbose. The default is 15. - -The `nvdaHelperDebugFlags` variable takes one or more of the following flags: - -* debugCRT: the libraries will be linked against the debug C runtime and assertions will be enabled. (By default, the normal CRT is used and assertions are disabled.) -* RTC: runtime checks (stack corruption, uninitialized variables, etc.) will be enabled. (The default is no runtime checks.) -* analyze: runs MSVC code analysis on all nvdaHelper code, halting on any warning. (default is no analysis). - -The special keywords none and all can also be used in place of the individual flags. - -An example follows that enables debug CRT and runtime checks - -``` -scons source nvdaHelperDebugFlags=debugCRT,RTC -``` - -Symbol pdb files are always produced when building, regardless of the debug flags. -However, they are not included in the NVDA distribution. -Instead, `scons symbolsArchive` will package them as a separate archive. - -By default, builds also do not use any compiler optimizations. -Please see the `release` keyword argument for what compiler optimizations it will enable. - -## Running the Source Code -It is possible to run NVDA directly from source without having to build the full binary package and launcher. -To launch NVDA from source, using `cmd.exe`, execute `runnvda.bat` in the root of the repository. - -To view help on the arguments that NVDA will accept, use the `-h` or `--help` option. -These arguments are also documented in the user guide. - -## Building NVDA -A binary build of NVDA can be run on a system without Python and all of NVDA's other dependencies installed (as we do for snapshots and releases). - -Binary archives and bundles can be created using scons from the root of the NVDA source distribution. To build any of the following, open a command prompt and change to that directory. - -To make a non-archived binary build (equivalent to an extracted portable archive), type: - -``` -scons dist -``` - -The build will be created in the dist directory. - -### Building the installer - -To create a launcher archive (one executable allowing for installation or portable dist generation), type: - -``` -scons launcher -``` - -The archive will be placed in the output directory. - -### Building the developer documentation - -To generate the NVDA developer guide, type: - -``` -scons developerGuide -``` - -The developer guide will be placed in the `devDocs` folder in the output directory. - -To generate the HTML-based source code documentation, type: - -``` -scons devDocs -``` - -The documentation will be placed in the `NVDA` folder in the output directory. - -#### Building nvdaHelper developer documentation - -To generate developer documentation for nvdaHelper (not included in the devDocs target): - -``` -scons devDocs_nvdaHelper -``` - -The documentation will be placed in the folder `\output\devDocs\nvdaHelper`. -This requires having Doxygen installed. - -### Generate debug symbols archive -To generate an archive of debug symbols for the various dll/exe binaries, type: - -``` -scons symbolsArchive -``` - -The archive will be placed in the output directory. - -### Generate translation template -To generate a gettext translation template (for translators), type: - -``` -scons pot -``` - -### Customising the build -Optionally, the build can be customised by providing variables on the command line: - -* version: The version of this build. -* release: Whether this is a release version. - * This enables various C++ compiler optimizations such as /O2 and whole-program optimization. - * It also instructs Python to generate optimized byte code. -* publisher: The publisher of this build. -* certFile: The certificate file with which to sign executables. The certificate must be in pfx format and contain the private key. -* certPassword: The password for the private key in the signing certificate. If omitted, no password will be assumed. -* certTimestampServer: The URL of the timestamping server to use to timestamp authenticode signatures. If omitted, signatures will not be timestamped. -* outputDir: The directory where the final built archives and such will be placed. -* targetArchitectures: The target architectures that NVDA should support. Possible values are all, x86 and x86_64. This should generally be left as the default. - -For example, to build a launcher with a specific version, you might type: - -``` -scons launcher version=test1 -``` - -For more see the `sconstruct` file. - -## Running Automated Tests -If you make a change to the NVDA code, you should run NVDA's automated tests. -These tests help to ensure that code changes do not unintentionally break functionality that was previously working. - -To run the tests (unit tests, translatable string checks), first change directory to the root of the NVDA source distribution as above. -Then, run: - -``` -scons tests -``` - -### Unit tests -To run only specific unit tests, specify them using the `unitTests` variable on the command line. -The tests should be provided as a comma-separated list. -Each test should be specified as a Python module, class or method relative to the `tests\unit` directory. -For example, to run only methods in the `TestMove` and `TestSelection` classes in the file `tests\unit\test_cursorManager.py` file, run this command: - -``` -scons tests unitTests=test_cursorManager.TestMove,test_cursorManager.TestSelection -``` - -### Translatable string checks -To run only the translatable string checks (which check that all translatable strings have translator comments), run: - -``` -scons checkPot -``` - -### Linting your changes -In order to ensure your changes comply with NVDA's coding style you can run the Flake8 linter locally. -Some developers have found certain linting error messages misleading, these are clarified in `tests/lint/readme.md`. -runlint.bat will use Flake8 to inspect only the differences between your working directory and the specified `base` branch. -If you create a Pull Request, the `base` branch you use here should be the same as the target you would use for a Pull Request. In most cases it will be `origin/master`. -``` -runlint origin/master -``` - -To be warned about linting errors faster, you may wish to integrate Flake8 with other development tools you are using. -For more details, see `tests/lint/readme.md` - -### Unit Tests -Unit tests can be run with the `rununittests.bat` script. -Internally this script uses the Nose Python test framework to execute the tests. -Any arguments given to rununittests.bat are forwarded onto Nose. -Please refer to Nose's own documentation on how to filter tests etc. - -### System Tests -System tests can be run with the `runsystemtests.bat --include ` script. -To run all tests standard tests for developers use `runsystemtests.bat --include NVDA`. -Internally this script uses the Robot test framework to execute the tests. -Any arguments given to runsystemtests.bat are forwarded onto Robot. -For more details (including filtering and exclusion of tests) see `tests/system/readme.md`. +## NVDA Community +* [Support and information for NVDA users](https://www.nvaccess.org/get-help/) +* [Report an issue or feature request](./projectDocs/issues/readme.md) +* [Getting add-ons](https://www.nvaccess.org/files/nvda/documentation/userGuide.html#AddonsManager) +* [More important links and community information](./projectDocs/community/readme.md) ## Contributing to NVDA - -If you would like to contribute code or documentation to NVDA, you can read more information in our [contributing guide](./.github/CONTRIBUTING.md). +If you would like to contribute to NVDA, you can read more information in our [contributing guide](./.github/CONTRIBUTING.md). +This includes information on reporting issues, triaging issues, testing, translating, contributing code/documentation and creating add-ons. diff --git a/user_docs/en/userGuide.t2t b/user_docs/en/userGuide.t2t index 25495d3c52a..7d99fa34ac4 100644 --- a/user_docs/en/userGuide.t2t +++ b/user_docs/en/userGuide.t2t @@ -263,7 +263,8 @@ Many settings screens have keystrokes to open them directly, such as ``NVDA+cont ++ Community ++[Community] -NVDA has a vibrant user community. There is a main [English language email list https://nvda.groups.io/g/nvda] and a page full of [local language groups https://github.com/nvaccess/nvda-community/wiki/Connect]. +NVDA has a vibrant user community. +There is a main [English language email list https://nvda.groups.io/g/nvda] and a page full of [local language groups https://github.com/nvaccess/nvda/wiki/Connect]. NV Access, makers of NVDA, are active on [Twitter https://twitter.com/nvaccess] and [Facebook https://www.facebook.com/NVAccess]. NV Access also have a regular [In-Process blog https://www.nvaccess.org/category/in-process/]. @@ -289,8 +290,8 @@ Other modules, and the discounted [NVDA Productivity Bundle https://www.nvaccess NV Access also sells [telephone support https://www.nvaccess.org/product/nvda-telephone-support/], either in blocks, or as part of the [NVDA Productivity Bundle https://www.nvaccess.org/product/nvda-productivity-bundle/]. Telephone support includes local numbers in Australia and the USA. - -The [email user groups https://github.com/nvaccess/nvda-community/wiki/Connect] are a great source of community help, as are [certified NVDA experts https://certification.nvaccess.org/]. + +The [email user groups https://github.com/nvaccess/nvda/wiki/Connect] are a great source of community help, as are [certified NVDA experts https://certification.nvaccess.org/]. + More Setup Options +[MoreSetupOptions]