Readme and development documentation/policy: spell out (and enforce system requirements to development and testing, not just for usage

[josephsl]

Hi,

The following stems from an exchange on PR #16557:

Introduction

Over the years, NVDA's system requirements have changed to keep in pace with Windows support lifecycle, Python's operating system support policy (PEP 11), and the need to use newer technologies to support NVDA features. For example, NVDA 2017.4 required Windows 7 Service Pack 1 or later, and 2024.1 updated minimum Windows version to 8.1.

While the system requirements are documented in the user guide and the development environment documentation, it is not enforced when testing or submitting pull requests. For example, while reviewing #16557, NV Access staff and I learned that the pull request writer is using Windows 7, a Windows release no longer supported by Microsoft in any form or shape and no longer supported by NVDA as of 2024.1. The pull request was possible via compilation and library inclusion tests as follows:

1. A library to support JAB on 32-bit systems is missing or not included with NVDA.
2. When the library was updated/included, the pull request writer included the library in their local NVDA installation (including building from source).
3. The build was compiled on Appveyor and NV Access has asked for community testing.

Further, it was learned that the pull request writer is using unacceptable hardware setup, specifically a dying hard disk drive, making the local testing process slow and thus relying on the GitHub web interface.

Proposal

As part of project documentation edits or during SCons dependency update, enforce minimum system requirement for local builds, testing, and pull requests. At a minimum, the project readme should include a statement on system requirements for users and contributors. For an example, see the dev environment documentation (part of project docs/development documentation).

There are numerous benefits to this proposal. Posting a system requirements statement up front (project readme) makes what is known more visible - instead of digging through the user guide and project documentation, what it takes to run, test, and contribute to the project is displayed more prominently. Second, system requirements statements can be checked across documentation to improve accuracy and send a more unified message across audiences. Third, featuring system requirements as part of readme aids in search engine results - when people search for NVDA system requirements, having the statement up front (readme) makes the result more discoverable.

There are drawbacks as well. First, system requirements statements must be in sync across documentation whenever the requirements change. Second, NVDA project must justify choices made such as supporting Windows 8.1 when it is no longer supported by Microsoft (Python releases and operating systems support, for example).

Discussion points

Why not create a feature request issue to discuss documentation changes?

System requirements have an impact on not only documentation, but across the project such as editing source code and requirements.txt, features added or dropped, and asking developers to change their development environment and assumptions.

Why tie this to SCons update?

NVDA includes "sconstruct" file to be used by SCons when building the screen reader from source. While the sconstruct file checks for 32-bit versus 64-bit Python runtime, it uses a less efficient way to check for Python versions (spelling out exactly which Python versions are supported instead of using scons.python_version function). More importantly, NVDA's sconstruct does NOT check for operating system releases, making it possible to build NVDA on Windows releases supported by whichever Visual Studio (full IDE or build tools) the person is running. Therefore, wile updating sCons, it would be helpful to also take a look at sconstruct/sconscript files.

People will discover workarounds such as seeing inclusion of files in library.zip

Even though people may find workarounds such as testing for existence of files inside library.zip, newer NVDA releases will upgrade to newer Python and/or use DLL's coming from newer Windows SDK releases, making this approach increasingly unusable.

Why focus on readme.md?

One of the project discovery mechanisms is opening the project GitHub URL directly (in this case, github.com/nvaccess/nvda). Unless configured otherwise, when people visit the project GitHub page, they will see readme.md contents. As argued above, this is one of the most visible aspects of the project - in addition to NV Access homepage, developers, users, researchers, and search engines will cite readme contents for various purposes. The fact that NVDA's readme does not specify system requirements forces people to look elsewhere such as the user guide and development environment documentation.

Can't you just direct people to look at the development environment notes in the readme?

Yes. However, this takes away the opportunity to verify that system requirements is indeed what the documentation claims.

What should we do about ongoing pull requests?

There are at least three ways to proceed:

1. Lenient: exempt current pull requests from system requirements statement.
2. Remind: remind pull request writers to test their PR's on supported systems.
3. Resubmit: for pull requests developed and tested on unsupported systems, close them with a comment asking people to resubmit after testing their work on supported systems.

While community feedback will be important, the decision is ultimately NV Access's.

When should the community enforce system requirements on pull requests?

Sooner the better. I propose 2024.4 with full enforcement coming in 2025.1 API review/action cycle.

Thanks.

[seanbudd]

We intentionally migrated the information needed to make a code contribution from the readme to here. This document is linked from the readme.

The README was incredibly cluttered with dev environment information, and dev environment info isn't useful for many contributors.
As such, we decided to keep the README as a nexus for the different ways to contribute.