Merge 7d5ddb2 into 071247b

seanbudd · web-flow · commit 41fa92999405 · 2025-06-25T18:00:16.000+10:00
diff --git a/.github/workflows/testAndPublish.yml b/.github/workflows/testAndPublish.yml
@@ -25,19 +25,13 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  START_BUILD_NUMBER: 50000
+  START_BUILD_NUMBER: ${{ vars.BUILD_NUMBER_OFFSET || 0 }}
   pullRequestNumber: ${{ github.event_name == 'pull_request' && github.event.number || 0 }}
-  scons_publisher: NV Access
+  scons_publisher: ${{ vars.PUBLISHER_NAME || github.repository_owner }}
   # Don't send telemetry to Microsoft when using MSVC tooling, avoiding an unnecessary PowerShell script invocation.
   VSCMD_SKIP_SENDTELEMETRY: 1
   # Cache details about available MSVC tooling for subsequent SCons invocations to the provided file.
   SCONS_CACHE_MSVC_CONFIG: ".scons_msvc_cache.json"
-  # Comment out any of the feature_* variables to disable the respective build feature.
-  # They are checked for existence of content, not specific value.
-  feature_uploadSymbolsToMozilla: configured
-  feature_crowdinSync: configured
-  feature_signing: configured
-  # feature_buildAppx: configured
 
 jobs:
   buildNVDA:
@@ -163,17 +157,17 @@ jobs:
     if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/beta' }}
     steps:
     - name: Checkout cached build
-      if: ${{ env.feature_crowdinSync }}
+      if: ${{ vars.CROWDIN_PROJECT_ID }}
       uses: actions/cache/restore@v4
       with:
         path: ${{ github.workspace }}
         key: ${{ github.ref }}-${{ github.run_id }}
         fail-on-cache-miss: true
     - name: Install the latest version of uv
-      if: ${{ env.feature_crowdinSync }}
+      if: ${{ vars.CROWDIN_PROJECT_ID }}
       uses: astral-sh/setup-uv@v6
     - name: Upload translations to Crowdin
-      if: ${{ env.feature_crowdinSync }}
+      if: ${{ vars.CROWDIN_PROJECT_ID }}
       env:
         crowdinProjectID: ${{ vars.CROWDIN_PROJECT_ID }}
         crowdinAuthToken: ${{ secrets.CROWDIN_AUTH_TOKEN }}
@@ -197,7 +191,7 @@ jobs:
     - name: Set scons args
       run: ci/scripts/setSconsArgs.ps1
       env:
-        apiSigningToken: ${{ (github.event_name == 'push' && env.feature_signing) && secrets.API_SIGNING_TOKEN || '' }}
+        apiSigningToken: ${{ github.event_name == 'push' && secrets.API_SIGNING_TOKEN }}
     - name: Create launcher
       shell: cmd
       run: |
@@ -309,15 +303,15 @@ jobs:
         name: Symbols
         path: output/symbols.zip
     - name: Install the latest version of uv
-      if: ${{ github.event_name == 'push' && env.feature_uploadSymbolsToMozilla }}
+      if: ${{ github.event_name == 'push' && vars.feature_uploadSymbolsToMozilla }}
       uses: astral-sh/setup-uv@v6
     - name: Upload symbols to Mozilla
-      if: ${{ github.event_name == 'push' && env.feature_uploadSymbolsToMozilla }}
+      if: ${{ github.event_name == 'push' && vars.feature_uploadSymbolsToMozilla }}
       continue-on-error: true
       # TODO: this script should be moved to ci/scripts
       run: uv run --with requests --directory appveyor mozillaSyms.py
       env:
-        mozillaSymsAuthToken: ${{ secrets.MOZILLA_SYMS_AUTH_TOKEN }}
+        mozillaSymsAuthToken: ${{ secrets.MOZILLA_SYMS_TOKEN }}
     - name: Warn on failure
       if: ${{ failure() }}
       shell: bash
diff --git a/ci/README.md b/ci/README.md
@@ -1,43 +1,143 @@
 # Continuous Integration with GitHub Actions
 
-[Documentation about GitHub Actions](https://docs.github.com/en/actions)
+## Background
+
+GitHub Actions builds the following types of NVDA installers through a CI/CD pipeline:
+
+* Pull Request builds: Generated from the pull requests.
+Pull requests initiated from `nvaccess/nvda` rather than a fork have extra permissions than standard PRs.
+* Snapshot builds: Generated from pushes to master/beta/rc or branch names prefixed with `try-`.
+These are signed and deployed to the NV Access server.
+* Tagged builds: Generated from pushes to tags prefixed with `release-`.
+Official beta, rc and stable releases.
+These are signed and deployed to the NV Access server.
 
 ## Builds
 
+### Build process
+
+The build process is non-linear.
+Some of these steps run concurrently.
+
+1. Prepare source code and cache:
+    1. Checkout NVDA repository with submodules.
+    1. Install dependencies (or use cache).
+    1. Set version and scons variables.
+    1. Build NVDA source.
+1. Build and test:
+    1. Run static tests
+    1. Build launcher
+    1. Install NVDA
+    1. Run systems tests
+1. Deploy (not fully active currently):
+    1. On tagged/snapshot builds, upload symbols to Mozilla
+    1. On beta branch builds, upload translation to Crowdin.
+    1. On snapshot builds, deploy to the server.
+    1. On release builds, publish the release in GitHub and deploy to the server.
+1. Clean up build cache.
+
+### Build behaviours
+
 Builds will fail if any command has a non-zero exit code.
 PowerShell scripts continue on non-terminating errors unless the file is prefixed with `$ErrorActionPreference = "Stop";`.
 
-### Build process
+## Setup requirements
 
-1. Checkout NVDA repository with submodules.
-1. Install dependencies (or use cache).
-1. Set version and scons variables.
-1. Prepare source code.
-1. Build launcher.
-1. Install NVDA.
-1. Prepare for tests.
-1. Run tests.
-1. Clean up build cache.
-1. Release NVDA if this is a tagged release.
+The repository hosting GitHub Actions must be configured correctly for different parts of the build process.
+
+### Publisher name
+
+Our releases are packaged with a publisher name.
+To customise this, set:
+
+* `PUBLISHER_NAME` as a variable.
+It currently defaults to the repository owner (e.g. `nvaccess`).
+
+### Build number offset
+
+To offset from our previous build system, we start the sequential build count at a higher number than 0.
+This means our first build will be numbered something like 100,001 not 1.
+
+To offset build numbers, set;
+
+* `BUILD_NUMBER_OFFSET` as a variable.
+It currently defaults to 0.
+
+### Crowdin
+
+NVDA translations are synced with Crowdin on the beta branch.
+
+To enable, set:
+
+* `CROWDIN_PROJECT_ID` as a variable.
+* `CROWDIN_AUTH_TOKEN` as a secret.
+
+### Code signing
+
+NV Access signs snapshot/tagged builds with SignPath.
+
+To enable, set:
+
+* `API_SIGNING_TOKEN` as a secret with your SignPath token.
+
+### Uploading symbols
+
+NVDA uploads its build symbols to Mozilla to help them with debugging on snapshot/tagged builds.
+
+To enable, set:
+
+* `MOZILLA_SYMS_TOKEN` as a secret.
+* `feature_uploadSymbolsToMozilla` as a variable with any non-empty string.
+
+Generating this requires direct co-ordination with Mozilla.
+
+### GitHub Environments
+
+GitHub Environments are used to protect deployments of snapshot/tagged builds.
+
+Create two GitHub Environments, one called `production`, the other `snapshot`.
+
+#### production
+
+Used for tagged releases of NVDA.
+It's recommended to enable deployment protection rules so that a human can confirm the deployment of a built tagged release staged for deployment.
+This is so any desired testing can get manually confirmed, and communications for the release can be prepared.
+
+Configuration:
+
+* Name: `production`
+* Enable required reviewers: this ensures a human must confirm deployment of a staged release
+* Under "Deployment branches and tags", create a tag rule: `release-*`
+
+#### snapshot
+
+Configuration:
+
+* Name: `snapshot`
+* Do not enable required reviewers: this is not needed for snapshots.
+* Under "Deployment branches and tags", create these branch rules:
+  * `master`
+  * `beta`
+  * `rc`
+  * `try-**`
+
+### Deployment webhook
+
+Create a GitHub webhook to subscribe to snapshot/tagged builds of NVDA, and use it to deploy to a server.
 
-## Testing
+Under events, only subscribe to the Deployments event.
 
-Before testing we:
+Ensure a secret is set and SSL is enabled.
 
-* Create directories to store results.
-* Install NVDA for system tests
+### VirusTotal scanning
 
-The tests we perform are:
+NV Access scans tagged builds with VirusTotal.
 
-* check translation comments
-* license checks
-* unit tests
-* system tests
-  * each test suite (i.e. .robot file) must be manually included by:
-    * adding a tag to `Force Tags` in the suite
-    * adding the tag to `systemTests.strategy.matrix.testSuite` in the [CI script](../.github/workflows/testAndPublish.yml)
+Set `VT_API_KEY` as a secret to perform tagged builds.
 
-## Artifacts
+### GitHub Discussions category
 
-* NVDA launcher.
-* Test results.
+This is only used when building tagged builds.
+GitHub Discussions created for stable releases must go into a "Releases" category.
+Discussions must be enabled in the repository.
+Create a new discussion category with an "Announcement" type, and a category name of "Releases".
diff --git a/ci/scripts/setSconsArgs.ps1 b/ci/scripts/setSconsArgs.ps1
@@ -1,5 +1,6 @@
 $ErrorActionPreference = "Stop";
 $sconsOutTargets = "launcher developerGuide changes userGuide keyCommands client moduleList"
+# AppX is currently unmaintained and not built by default.
 if ($env:GITHUB_EVENT_NAME -eq "push" -and $env:feature_buildAppx) {
 	$sconsOutTargets += " appx"
 }

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`$ErrorActionPreference = "Stop";`
`2`	`2`	`$sconsOutTargets = "launcher developerGuide changes userGuide keyCommands client moduleList"`
	`3`	`+# AppX is currently unmaintained and not built by default.`
`3`	`4`	`if ($env:GITHUB_EVENT_NAME -eq "push" -and $env:feature_buildAppx) {`
`4`	`5`	`$sconsOutTargets += " appx"`
`5`	`6`	`}`