Merge remote-tracking branch 'origin/master' into githubForms

.github/CONTRIBUTING.md

@@ -1,4 +1,91 @@
-The NVDA project is open to contributions, thank you for your interest!
+# 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
 
-Please first [read our guide to contributing](https://github.com/nvaccess/nvda/wiki/Contributing) on the NVDA
-GitHub Wiki.
+## 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.
+
+
+### 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
+   ```
+
+#### 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)

.github/ISSUE_TEMPLATE.md

@@ -1,41 +1,7 @@
-You have arrived at a default issue template (bug report).
-It is preferable to [choose the type of issue](https://github.com/nvaccess/nvda/issues/new/choose) to submit.
+You have arrived at the blank issue template from submitting issues.
+It is preferable to [choose a type of issue](https://github.com/nvaccess/nvda/issues/new/choose) to submit.
+Your issue may be closed if you do not follow one of the following issue templates.
 Hint: Swap to the preview tab to be able to click the links.
 Direct links to the templates:
 - [Bug report](https://github.com/nvaccess/nvda/issues/new?template=bug_report.md)
 - [Feature request](https://github.com/nvaccess/nvda/issues/new?template=feature_request.md)
-
-<!--
-Please thoroughly read NVDA's wiki article on how to fill in this template, including how to provide the required files.
-Issues may be closed if the required information is not present.
-https://github.com/nvaccess/nvda/blob/master/devDocs/githubIssueTemplateExplanationAndExamples.md
-Please also note that the NVDA project has a Citizen and Contributor Code of Conduct which can be found at https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md. NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project. This includes creating or commenting on issues and pull requests. 
-
-Each of the questions and sections below start with multiple hash symbols (#). Place your answers and information on the blank line below each question.
--->
-
-### Steps to reproduce:
-
-### Actual behavior:
-
-### Expected behavior:
-
-### System configuration
-#### NVDA installed/portable/running from source:
-
-#### NVDA version:
-
-#### Windows version:
-
-#### Name and version of other software in use when reproducing the issue:
-
-#### Other information about your system:
-
-### Other questions
-#### Does the issue still occur after restarting your computer?
-
-#### Have you tried any other versions of NVDA? If so, please report their behaviors.
-
-#### If add-ons are disabled, is your problem still occurring?
-
-#### Does the issue still occur after you run the COM Registration Fixing Tool in NVDA's tools menu?

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -7,7 +7,7 @@ body:
     attributes:
       value: |
         ### Attention!
-        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/devDocs/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
+        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
         Issues may be closed if the required information is not present.
         Please also note that the NVDA project has a [Citizen and Contributor Code of Conduct](https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md).
         NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project.

.github/ISSUE_TEMPLATE/custom_issue.yml

@@ -8,7 +8,7 @@ body:
         It is expected that almost every issue on this project is either a feature request or bug report.
         Please only select this format in exceptional circumstances, otherwise it will be closed.
         Alternatively, consider a [GitHub discussion](https://github.com/nvaccess/nvda/discussions).
-        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/devDocs/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
+        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
         Issues may be closed if the required information is not present.
         Please also note that the NVDA project has a [Citizen and Contributor Code of Conduct](https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md).
         NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -7,7 +7,7 @@ body:
     attributes:
       value: |
         ### Attention!
-        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/devDocs/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
+        Please read [our guide](https://github.com/nvaccess/nvda/blob/master/projectDocs/issues/githubIssueTemplateExplanationAndExamples.md) on how to fill in this template, including how to provide the required files.
         Issues may be closed if the required information is not present.
         Please also note that the NVDA project has a [Citizen and Contributor Code of Conduct](https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md).
         NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,10 +1,10 @@
 <!-- Please read and fill in the following template, for an explanation of the sections see:
-https://github.com/nvaccess/nvda/blob/master/devDocs/githubPullRequestTemplateExplanationAndExamples.md
+https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/githubPullRequestTemplateExplanationAndExamples.md
 Please also note that the NVDA project has a Citizen and Contributor Code of Conduct which can be found at https://github.com/nvaccess/nvda/blob/master/CODE_OF_CONDUCT.md. NV Access expects that all contributors and other community members read and abide by the rules set out in this document while participating or contributing to this project. This includes creating or commenting on issues and pull requests. 
 
 Please initially open PRs as a draft.
 When you would like a review, mark the PR as "ready for review". 
-See https://github.com/nvaccess/nvda/wiki/Contributing.
+See https://github.com/nvaccess/nvda/blob/master/.github/CONTRIBUTING.md.
 -->
 
 ### Link to issue number:
@@ -35,7 +35,7 @@ Where items are missing (eg unit / system tests), please explain in the PR.
 To check an item `- [ ]` becomes `- [x]`, note spacing.
 You can also check the checkboxes after the PR is created.
 A detailed explanation of this checklist is available here:
-https://github.com/nvaccess/nvda/blob/master/devDocs/githubPullRequestTemplateExplanationAndExamples.md#code-review-checklist
+https://github.com/nvaccess/nvda/blob/master/projectDocs/dev/githubPullRequestTemplateExplanationAndExamples.md#code-review-checklist
 -->
 
 - [ ] Pull Request description:

CODE_OF_CONDUCT.md

@@ -25,17 +25,18 @@ The following behaviours are expected and requested of all community members:
 
 ## 4. Unacceptable Behaviour
 The following behaviours are considered harassment and are unacceptable within our community:
-* Violence, threats of violence or violent language directed against another person.
+* Violence, threats of violence, inciting violence, glorifying violence, or violent language directed against another person.
 * Sexist, racist, homophobic, transphobic, ableist or otherwise discriminatory jokes and language.
 * Posting or displaying sexually explicit or violent material.
 * Posting or threatening to post other people's personally identifying information ("doxing").
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Personal insults, particularly those related to gender, sexual orientation, race, religion, or disability.
 * Inappropriate photography or recording.
-* Unwelcome sexual attention. This includes sexualized comments or jokes, inappropriate touching, groping, and unwelcomed sexual advances.
+* Unwelcome sexual attention. This includes sexualized comments or jokes, inappropriate touching, groping, and unwelcome sexual advances.
 * Deliberate intimidation, stalking or following (online or in person).
 * Advocating for, or encouraging, any of the above behaviour.
 * Sustained disruption of community events, including talks and presentations.
+* Religious or political proselytising.
 
 ## 5. Consequences of Unacceptable Behaviour
 Unacceptable behaviour from any community member, including sponsors and those with decision-making authority, will not be tolerated.
@@ -61,4 +62,6 @@ [email protected]
 The Citizen and Contributor Code of Conduct is distributed by NV Access Limited. 
 Portions of text were derived from the GitHub sample Citizen and Contributor Code of Conduct, which is distributed under a Creative Commons Attribution-ShareAlike license.
 
-Revision1.0 adopted by NV Access Limited on 2020-09-23
+Revision history:
+- Revision 1.0 adopted by NV Access Limited on 2020-09-23
+- Revision 1.1 adopted by NV Access Limited on 2023-08-09

nvdaHelper/local/wasapi.cpp

@@ -413,7 +413,10 @@ UINT64 WasapiPlayer::getPlayPos() {
 	UINT64 pos;
 	HRESULT hr = clock->GetPosition(&pos, nullptr);
 	if (FAILED(hr)) {
-		return 0;
+		// If we get an error, playback has probably been interrupted; e.g. because
+		// the device disconnected. Treat this as if playback has finished so we
+		// don't wait forever and so that we fire any pending callbacks.
+		return sentMs;
 	}
 	return pos * 1000 / clockFreq;
 }

nvdaHelper/remote/WinWord/Constants.h

@@ -1,7 +1,7 @@
 /*
 This file is a part of the NVDA project.
 URL: http://www.nvda-project.org/
-Copyright 2016 NVDA contributers.
+Copyright 2016-2023 NVDA contributors.
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License version 2.0, as published by
     the Free Software Foundation.
@@ -186,10 +186,12 @@ constexpr int wdMaximumNumberOfColumns = 18;
 constexpr int wdHorizontalPositionRelativeToPage = 5;
 
 // WdParagraphAlignment Enumeration
+// (see https://docs.microsoft.com/en-us/office/vba/api/word.wdparagraphalignment)
 constexpr int wdAlignParagraphLeft = 0;
 constexpr int wdAlignParagraphCenter = 1;
 constexpr int wdAlignParagraphRight = 2;
 constexpr int wdAlignParagraphJustify = 3;
+constexpr int wdAlignParagraphDistribute = 4;
 
 // WdLanguageID Enumeration
 constexpr int wdLanguageNone = 0;  //&H0

nvdaHelper/remote/winword.cpp

@@ -1,7 +1,7 @@
 /*
 This file is a part of the NVDA project.
 URL: http://www.nvda-project.org/
-Copyright 2006-2010 NVDA contributers.
+Copyright 2006-2023 NVDA contributors.
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU General Public License version 2.0, as published by
     the Free Software Foundation.
@@ -561,7 +561,10 @@ void generateXMLAttribsForFormatting(IDispatch* pDispatchRange, int startOffset,
 						formatAttribsStream<<L"text-align=\"right\" ";
 						break;
 						case wdAlignParagraphJustify:
-						formatAttribsStream<<L"text-align=\"justified\" ";
+						formatAttribsStream<<L"text-align=\"justify\" ";
+						break;
+						case wdAlignParagraphDistribute:
+						formatAttribsStream<<L"text-align=\"distribute\" ";
 						break;
 					}
 				}
@@ -1145,11 +1148,33 @@ void winword_getTextInRange_helper(HWND hwnd, winword_getTextInRange_args* args)
 		IDispatchPtr pDispatchParagraphs=NULL;
 	IDispatchPtr pDispatchParagraph=NULL;
 	IDispatchPtr pDispatchParagraphRange=NULL;
-	if(formatConfig&formatConfig_reportComments||initialFormatConfig&formatConfig_reportHeadings) {
-		if(_com_dispatch_raw_propget(pDispatchRange,wdDISPID_RANGE_PARAGRAPHS,VT_DISPATCH,&pDispatchParagraphs)==S_OK&&pDispatchParagraphs) {
-			if(_com_dispatch_raw_method(pDispatchParagraphs,wdDISPID_PARAGRAPHS_ITEM,DISPATCH_METHOD,VT_DISPATCH,&pDispatchParagraph,L"\x0003",1)==S_OK&&pDispatchParagraph) {
-				_com_dispatch_raw_propget(pDispatchParagraph,wdDISPID_PARAGRAPH_RANGE,VT_DISPATCH,&pDispatchParagraphRange);
-			}
+	if (
+		S_OK == _com_dispatch_raw_propget(
+			pDispatchRange,
+			wdDISPID_RANGE_PARAGRAPHS,
+			VT_DISPATCH,
+			&pDispatchParagraphs
+		)
+		&& pDispatchParagraphs
+	) {
+		if(
+			S_OK == _com_dispatch_raw_method(
+				pDispatchParagraphs,
+				wdDISPID_PARAGRAPHS_ITEM,
+				DISPATCH_METHOD,
+				VT_DISPATCH,
+				&pDispatchParagraph,
+				L"\x0003",
+				1
+			)
+			&& pDispatchParagraph
+		) {
+			_com_dispatch_raw_propget(
+				pDispatchParagraph,
+				wdDISPID_PARAGRAPH_RANGE,
+				VT_DISPATCH,
+				&pDispatchParagraphRange
+			);
 		}
 	}
 	vector<pair<long,long> > commentVector;

devDocs/.gitignore → projectDocs/.gitignore

@@ -1,3 +1,4 @@
 _build/
 *.rst
+!index.rst
 developerGuide.html

devDocs/startupShutdown.md → projectDocs/design/startupShutdown.md

@@ -33,7 +33,7 @@
 1. Windows shutting down (terminates unsafely) (uses `wx.EVT_END_SESSION`)
 
 ## Manual testing
-Check the [manual test guide](../tests/manual/startupShutdown.md).
+Check the [manual test guide](../../tests/manual/startupShutdown.md).
 
 ## Technical notes