Add CI/CD to the addon

.github/workflows/pr-checks.yml

@@ -0,0 +1,49 @@
+name: PR Checks
+
+on:
+    pull_request:
+        branches: [main, master]
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pull-requests: write
+
+jobs:
+    validate:
+        uses: ./.github/workflows/validate.yml
+        with:
+            upload_artifacts: true
+
+    comment_packaged_artifact:
+        runs-on: ubuntu-latest
+        needs: [validate]
+        if: github.event_name == 'pull_request'
+        steps:
+            - name: Comment packaged artifact link on PR
+              uses: actions/github-script@v7
+              env:
+                  ARTIFACT_URL: ${{ needs.validate.outputs.artifact_url }}
+              with:
+                  script: |
+                      const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+                      const commitSha = context.payload.pull_request?.head?.sha || context.sha;
+                      const shortSha = commitSha.slice(0, 7);
+                      const artifactLine = process.env.ARTIFACT_URL
+                          ? `- Artifact: ${process.env.ARTIFACT_URL}`
+                          : '- Artifact: not available (check the run page below)';
+
+                      const body = [
+                          '### Packaged add-on artifact',
+                          `- Commit: ${shortSha} (${commitSha})`,
+                          artifactLine,
+                          `- Run: ${runUrl}`,
+                      ].join('\n');
+
+                      const issue_number = context.payload.pull_request.number;
+                      await github.rest.issues.createComment({
+                          owner: context.repo.owner,
+                          repo: context.repo.repo,
+                          issue_number,
+                          body,
+                      });

.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release Add-on
+
+on:
+    push:
+        tags:
+            - "**"
+    workflow_dispatch:
+
+jobs:
+    validate:
+        uses: ./.github/workflows/validate.yml
+        with:
+            upload_artifacts: false
+
+    release_addon:
+        if: startsWith(github.ref, 'refs/tags/')
+        needs: [validate]
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout code
+              uses:
+                  actions/checkout@v4
+
+                  # The next step is used to fix a small issue here to obtain the current tag message,
+                  # which will be used as the release body. For more details:
+                  # https://github.com/actions/checkout/issues/290
+            - name: Make sure we have the correct tag information
+              run: git fetch --tags --force
+
+            - name: Obtain tag message
+              uses: ericcornelissen/git-tag-annotation-action@v2
+              id: tag-data
+
+            - name: Check differences to master branch
+              id: differences-to-master
+              run: |
+                  git fetch origin master --depth=1
+                  if git diff origin/master --exit-code; then
+                    echo "changes_exist=false" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "changes_exist=true" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Abort if tag is not applied on top of master
+              if: steps.differences-to-master.outputs.changes_exist == 'true'
+              uses: actions/github-script@v7
+              with:
+                  script: |
+                      core.setFailed('Releases can be generated only from commit on head of master branch')
+
+            - name: Install system dependencies
+              run: sudo apt install gettext
+
+            - name: Install Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.13"
+
+            - name: Install Python dependencies
+              run: |
+                  pip install scons
+                  pip install markdown
+
+            - name: Generate addon
+              run: |
+                  rm -f *.nvda-addon || true
+                  scons
+
+            - name: Release
+              uses: softprops/action-gh-release@v1
+              with:
+                  files: "*.nvda-addon"
+                  body: "${{ steps.tag-data.outputs.git-tag-annotation }}"
+                  fail_on_unmatched_files: true
+                  generate_release_notes: false

.github/workflows/validate.yml

@@ -0,0 +1,60 @@
+name: Validate Add-on
+
+on:
+    workflow_call:
+        inputs:
+            upload_artifacts:
+                description: Upload build artifacts for this validation run
+                required: false
+                type: boolean
+                default: false
+        outputs:
+            artifact_url:
+                description: URL for the uploaded artifact (when upload_artifacts is true)
+                value: ${{ jobs.build_and_check.outputs.artifact_url }}
+    workflow_dispatch:
+
+jobs:
+    build_and_check:
+        runs-on: ubuntu-latest
+        env:
+            ARTIFACT_RETENTION_DAYS: 7
+        outputs:
+            artifact_url: ${{ steps.upload_build_artifacts.outputs.artifact-url }}
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Install system dependencies
+              run: sudo apt install gettext
+
+            - name: Install Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.13"
+
+            - name: Install Python dependencies
+              run: |
+                  pip install pre-commit
+                  pip install scons
+                  pip install markdown
+
+            - name: Code checks
+              run: pre-commit run --all-files
+
+            - name: Build addon and pot
+              run: |
+                  rm -f *.nvda-addon *.pot || true
+                  scons
+                  scons pot
+
+            - name: Upload build artifacts
+              id: upload_build_artifacts
+              if: ${{ inputs.upload_artifacts }}
+              uses: actions/upload-artifact@v4
+              with:
+                  name: packaged_addon
+                  retention-days: ${{ env.ARTIFACT_RETENTION_DAYS }}
+                  path: |
+                      ./*.nvda-addon
+                      ./*.pot

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-yaml
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        args: [--config=flake8.ini]

.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"ms-python.python",
+		"ms-python.vscode-pylance",
+		"redhat.vscode-yaml",
+		"ms-python.flake8"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": []
+}

.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+    "editor.accessibilitySupport": "on",
+    "flake8.args": [
+        "--config=${workspaceFolder}/flake8.ini"
+    ],
+    "flake8.importStrategy": "fromEnvironment",
+    "python.autoComplete.extraPaths": [
+        "../nvda/source",
+        "../nvda/miscDeps/python"
+    ],
+    "files.insertFinalNewline": true,
+    "files.trimFinalNewlines": true,
+    "editor.insertSpaces": false,
+    "python.analysis.stubPath": "${workspaceFolder}/.vscode/typings",
+    "python.analysis.extraPaths": [
+        "../nvda/source",
+        "../nvda/miscDeps/python"
+    ],
+    "python.defaultInterpreterPath": "${workspaceFolder}/../nvda/.venv/scripts/python.exe"
+}

.vscode/typings/__builtins__.pyi

@@ -0,0 +1,6 @@
+def _(msg: str) -> str:
+	...
+
+
+def pgettext(context: str, message: str) -> str:
+	...

addon/doc/en/contributing.md

@@ -2,13 +2,53 @@
 
 ## building the addon
 
+### Local environment
+
+Although not mandatory, we suggest you perform the following:
+
+1. Clone NVDA in a folder at the same level as this project.
+For example, if this project is cloned at c:\projects\snippetsForNVDA, NVDA should be cloned at c:\projects\nvda.
+Perform a clone with the --recursive flag. If NVDA is already cloned, make sure it is up to date, fetching and then synchronizing the master branch with the NVDA upstream master branch.  
+Perform a git submodule update --init command to make sure git submodules are correctly synchronized.
+2. Perform a git checkout in the release-2024.1 tag in the NVDA project. You don't need to build NVDA, just having the source code at the release branch is enough.
+3. Install visual studio code, if it is not installed. Although you can use other environments, the optimal setup requires visual studio code.
+4. Open the snippetsForNVDA folder in VS Code. From command line, perform the "code ." command, or use the file / open folder menus on visual studio code itself and select the folder where this project is cloned.
+5. Use ctrl + shift + x to access the extensions widget in Visual studio code. Tab umtil the recomended section and install the recomended extensions.
+6. Restart visual studio code.
+7. Now, whenever you are navigating through code, pressing f12 in a NVDA object should take you to its source in NVDA project.
+
+### Dependencies
+
 You will need:
 
-* python 3.6 or above.
+* python 3.13.
 * pip must be configured
 * scons (pip install scons)
 * markdown (pip install markdown)
-* msgfmt utility. The easiest way of getting it is by installing git bash and choosing to include bash tools at command prompt
+* gettext, which provides the `msgfmt` and `xgettext` utilities. `msgfmt` compiles the translation files on every build, and `xgettext` is used by `scons pot` to generate the translation template. On Windows, install a modern build from [gettext-iconv-windows](https://github.com/mlocati/gettext-iconv-windows/releases) (or use `scoop install gettext` / `choco install gettext`), and make sure its `bin` directory comes before any other gettext on your PATH. Do not use the GnuWin32 gettext package: it is frozen at version 0.14.4 (2005) and is too old for this build (`scons pot` fails on the unsupported `--package-name` option).
+
+#### Pre-commit
+
+It is strongly recomended that you install pre-commit.
+
+* pip imstall pre-commit
+* pre-commit install
+
+This will imstall pre-commit and configure its hooks, so that whenever you perform a commit several checks will apply.  
+Should any of them fail, the commit will not be allowed.
+This helps to ensure your commits have quality. You can bypass the check, however be aware that a pull request check will also apply these same checks and merge will be disabled should any of them fail, even if someone approves the pull request.
+
+You can trigger the pre-commit checks at any time without performing a commit by issuing "pre-commit run --all-files".
+
+#### Flake8
+
+One of the pre-commit hooks is flake8, a python linter which, ammong other things, help to make sure the project has a consistent formating and that good practices are in place.
+
+Visual Studio code recomended extensions include flake8, so that you can be warned while editing code when something needs to be fixed.
+
+The visual studio code extension and the pre-commit flake8 hooks use the same configuration.
+
+### building
 
 Once you have everything installed, issuing scons at the root of the project should build the addon and generate docs.