Clarify the required use of Python 3.9

Author: rvermeulen

docs/development_handbook.md

@@ -38,6 +38,7 @@
 | 0.29.0 | 2023-10-11 | Remco Vermeulen | Update release process. |
 | 0.29.1 | 2023-10-11 | Remco Vermeulen | Address Markdown linter problems. |
 | 0.30.0 | 2023-11-14 | Remco Vermeulen | Clarify release steps in case of a hotfix release. |
+| 0.31.0 | 2024-02-23 | Remco Vermeulen | Clarify the required use of Python version 3.9 |
 
 ## Scope of work
 
@@ -163,6 +164,7 @@ These files will be ready for query implementation.
 
 #### Step 0: Prepare the Python environment
 
+The tooling standardizes on Python 3.9 and requires the use of version 3.9 to run all tooling.
 The `scripts` directory contains the pip package specification file `requirements.txt` that contains the dependencies our generation scripts rely upon.
 
 The dependencies can be installed as follows:
@@ -171,12 +173,12 @@ The dependencies can be installed as follows:
 pip3.9 install -r scripts/requirements.txt
 ```
 
-It is advisable to use a Python virtual environment which needs to be created and activated before installing the dependencies. This can be done as follows:
+It is advisable to use a Python 3.9 virtual environment which needs to be created and activated before installing the dependencies. This can be done as follows:
 
 ```bash
 python3.9 -mvenv scripts/.venv
 . scripts/.venv/bin/activate
-pip install -r scripts/requirements.txt
+pip3.9 install -r scripts/requirements.txt
 ```
 
 #### Step 1: Generate rule package description file
@@ -265,7 +267,7 @@ The `generate_package_description.py` script provides a "best-effort" approach t
     - `performance` - if the query identifies an issue which has a negative impact on the performance of the code.
     - `concurrency` - if the query identifies a concurrency issue.
   - Validate the rule package description file using the `validate-rule-package.py` script that validates the rule package descriptions against the schema `rule-package.schema.json` located in the `schemas` directory.
-    - `python3 scripts/validate-rule-package.py <rule_package_name>`
+    - `python3.9 scripts/validate-rule-package.py <rule_package_name>`
 
 #### Step 3
 
@@ -350,7 +352,7 @@ All public predicates, classes, modules and files should be documented with QLDo
 
 ### Installing QL dependencies
 
-All of our query and library packs depend on the standard CodeQL library for C++, `codeql/cpp-all`. This dependency is specified in the `qlpack.yml` file for each of our packs. Before compiling, running, or testing any of our queries or libraries, you must download the proper dependencies by running `python3 scripts/install-packs.py`. This will download the appropriate version of the standard library from the public package registry, installing it in a cache in your `~/.codeql` directory. When compiling queries or running tests, the QL compiler will pick up the appropriate dependencies from this cache without any need to specify an additional library search path on the command line.
+All of our query and library packs depend on the standard CodeQL library for C++, `codeql/cpp-all`. This dependency is specified in the `qlpack.yml` file for each of our packs. Before compiling, running, or testing any of our queries or libraries, you must download the proper dependencies by running `python3.9 scripts/install-packs.py`. This will download the appropriate version of the standard library from the public package registry, installing it in a cache in your `~/.codeql` directory. When compiling queries or running tests, the QL compiler will pick up the appropriate dependencies from this cache without any need to specify an additional library search path on the command line.
 
 Because the downloaded packs are cached, it is only necessary to run `install-packs.py` once each time we upgrade to a new standard library version. It does not hurt to run it more often; if all necessary packs are already in the download cache, then it will complete quickly without trying to download anything.
 

docs/user_manual.md

@@ -22,7 +22,8 @@
 | 0.14.0  | 2022-11-03 | Remco Vermeulen | Add guideline recategorization plan.                                                                                    |
 | 0.15.0  | 2023-05-24 | Mauro Baluda    | Clarify AUTOSAR C++ supported versions.                                                                                 |
 | 0.16.0  | 2023-07-03 | Luke Cartey     | Remove reference to LGTM, update the name of the query pack                                                             |
-| 0.17.0  | 2023-08-16 | Luke Cartey     | Update list of supported compiler configurations.                                                             |
+| 0.17.0  | 2023-08-16 | Luke Cartey     | Update list of supported compiler configurations.                                                                       |
+| 0.18.0  | 2024-02-23 | Remco Vermeulen | Clarify the required use of Python version 3.9                                                                          |
 
 ## Release information
 
@@ -220,8 +221,8 @@ In addition to producing a results file, an analysis report can be produced that
 
 To run this script, the CodeQL CLI part of a supported CodeQL Bundle and Python interpreter version 3.9 must be available on the system path.
 
-```
-python3 scripts/reports/analysis_report.py path/to/<output_database_name> <name-of-results-file>.sarif <output_directory>
+```bash
+python3.9 scripts/reports/analysis_report.py path/to/<output_database_name> <name-of-results-file>.sarif <output_directory>
 ```
 
 This will produce a directory (`<output_directory>`) containing the following report files in markdown format:
@@ -325,6 +326,7 @@ The example describes three ways of scoping a deviation:
 
 The activation of the deviation mechanism requires an extra step in the database creation process.
 This extra step is the invocation of the Python script `path/to/codeql-coding-standards/scripts/configuration/process_coding_standards_config.py` that is part of the coding standards code scanning pack.
+To run this script, a Python interpreter version 3.9 must be available on the system path.
 The script should be invoked as follows:
 
 ```bash
@@ -333,7 +335,7 @@ codeql database create --language cpp --command 'python3 path/to/codeql-coding-s
 
 The `process_coding_standards_config.py` has a dependency on the package `pyyaml` that can be installed using the provided PIP package manifest by running the following command:
 
-`pip install -r path/to/codeql-coding-standards/scripts/configuration/requirements.txt`
+`pip3 install -r path/to/codeql-coding-standards/scripts/configuration/requirements.txt`
 
 ##### Deviation permit
 
@@ -424,7 +426,7 @@ add the tag `external/<standard>/original-obligation/<category` to each query im
 The script should be invoked as follows:
 
 ```bash
-python3 path/to/codeql-coding-standards/scripts/guideline_recategorization/recategorize.py coding_standards_config_file <sarif_in> <sarif_out>
+python3.9 path/to/codeql-coding-standards/scripts/guideline_recategorization/recategorize.py coding_standards_config_file <sarif_in> <sarif_out>
 ```
 
 The `recategorize.py` scripts has a dependencies on the following Python packages that can be installed with the command `pip install -r path/to/codeql-coding-standards/scripts/guideline_recategorization/requirements.txt`: