Merge branch 'main' into fix-devcontainer

src/data/nav.yaml

@@ -52,18 +52,18 @@
             - title: Debugging a test locally
               path: /docs/cli-command-reference/cli-runs-local-debug
             - title: Viewing test results locally
-              path: /docs/cli-command-reference/viewing-test-results-cli
-            - title: Exploring Galasa SimBank online
-              path: /docs/cli-command-reference/simbank-cli
-            - title: Exploring Galasa SimBank offline
-              path: /docs/cli-command-reference/simbank-cli-offline
+              path: /docs/cli-command-reference/viewing-test-results-cli 
+        - title: Exploring Galasa SimBank 
+          path: /docs/running-simbank-tests/exploring-simbank-tests
+          items:
+            - title: Running Galasa SimBank online
+              path: /docs/running-simbank-tests/simbank-cli
+            - title: Running Galasa SimBank offline
+              path: /docs/running-simbank-tests/simbank-cli-offline
             - title: Running the SimBank tests online
-              path: /docs/cli-command-reference/running-simbank-tests-cli
+              path: /docs/running-simbank-tests/running-simbank-tests-cli
             - title: Running the SimBank tests offline
-              path: /docs/cli-command-reference/running-simbank-tests-cli-offline   
-        - title: Exploring the supplied SimBank tests
-          path: /docs/exploring-simbank-tests
-          items:
+              path: /docs/running-simbank-tests/running-simbank-tests-cli-offline  
             - title: The SimBank IVT
               path: /docs/running-simbank-tests/simbank-IVT
             - title: BasicAccountCreditTest

src/markdown-pages/docs/cli-command-reference/cli-prereqs.md

@@ -6,13 +6,39 @@ title: "CLI prerequisites online"
 
 The following section explains more about the software prerequisites that you need so that you are ready to install Galasa from the Galasa CLI repository in GitHub.
 
-## Prerequisites
 
-| Software |  Description  |
+### Java JDK 
+
+Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation.
+
+
+### Maven 
+
+You must install either Maven or Gradle in order to build Galasa projects, which are hierarchical file structures that provide the ability to store and run Galasa tests.  
+
+### Gradle
+
+You must install either Maven or Gradle in order to build Galasa projects, which are hierarchical file structures that provide the ability to store and run Galasa tests. 
+
+The following table shows the current compatibility between Gradle and Galasa versions: 
+
+
+| Gradle release |  Compatible Galasa version  |
 | :---- | :-------- | 
-| Java JDK  | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation.|
-| Maven or Gradle  | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.9.x. Remember to add Gradle to your Path. You can check by running `echo $PATH` on Mac or Unix, or `echo %PATH%` on Windows (PowerShell). |
-| 3270 emulator | Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to [explore Galasa Simbank online](../cli-command-reference/simbank-cli), a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.| 
+| 6.8.x  | All |
+| 6.9.x  | All |
+| 7.x.x | All | 
+| 8.x.x | 0.36.0 or later |
+
+
+If you are upgrading to Gradle version 8 from an earlier version, see the `Upgrading tests to compile using Gradle version 8` section in the [Upgrading](../upgrading) documentation to understand the changes you need to make to create Galasa projects and build and compile Galasa test code. 
+
+Remember to add Gradle to your PATH. You can check by running `echo $PATH` on Mac or Unix, or `echo %PATH%` on Windows (PowerShell).
+
+
+### 3270 emulator 
+
+Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to [run Galasa Simbank online](../running-simbank-tests/simbank-cli), a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.
 
 
 ## Next steps

src/markdown-pages/docs/cli-command-reference/runs-local-debug.md

@@ -125,4 +125,4 @@ galasactl runs submit local --debug
 
 Read the [Viewing test results locally](viewing-test-results-cli) documentation to learn how to view the output of your test runs in your local environment. 
 
-Take a look at the [Exploring Galasa SimBank online](simbank-cli) or [Exploring Galasa SimBank offline](simbank-cli-offline)documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn the basic principles of Galasa's operation before you start connecting Galasa to your own mainframe application-under-test.
+Take a look at the [Exploring Galasa SimBank](../running-simbank-tests/exploring-simbank-tests) documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn Galasa's basic principles of operation before you start connecting Galasa to your own mainframe application-under-test.

src/markdown-pages/docs/cli-command-reference/runs-submit-local.md

@@ -72,14 +72,7 @@ where:
 - `--log` specifies that debugging information is directed somewhere, and the `-` means that it is sent to the console (stderr).
 - `--gherkin` specifies the path where the  CLI tool can find the Gherkin file containing the Gherkin tests. The path must be specified in a URL form, ending in a `.feature` extension. For example,`file:///Users/myuserid/gherkin/MyGherkinFile.feature` or `file:///C:/Users/myuserid/gherkin/MyGherkinFile.feature`.
 
-
-Examples of Galasa Managers in GitHub that have Gherkin support currently available are the <a href="https://github.com/galasa-dev/managers/tree/main/galasa-managers-parent/galasa-managers-core-parent/dev.galasa.core.manager/src/main/java/dev/galasa/core/manager/internal/gherkin" target="_blank">
-Core Manager</a>, and the <a href="https://github.com/galasa-dev/managers/tree/main/galasa-managers-parent/galasa-managers-zos-parent/dev.galasa.zos3270.manager/src/main/java/dev/galasa/zos3270/internal/gherkin" target="_blank">
-zos3270Terminal Manager</a>. For more information about these Managers, see the [Manager](../managers) documentation section. 
-
-
-
-For more information about Gherkin, see the <a href="https://cucumber.io/docs/guides/overview/" target="_blank">Cucumber website.</a>
+For more information about the Gherkin support currently available, see the <a href="https://github.com/galasa-dev/cli/blob/main/gherkin-docs.md" target="_blank">Galasa CLI Gherkin documentation</a>.
 
 ## Overriding the path to the default local Maven repository
 

src/markdown-pages/docs/cli-command-reference/viewing-test-results-cli.md

@@ -31,4 +31,4 @@ You can then view the terminal interactions from your test runs in the `images`
 
 ## Next steps
 
-Take a look at the [Exploring Galasa SimBank online](simbank-cli) or [Exploring Galasa SimBank offline](simbank-cli-offline)documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn Galasa's basic principles of operation before you start connecting Galasa to your own mainframe application-under-test.
+Take a look at the [Exploring Galasa SimBank](../running-simbank-tests/exploring-simbank-tests) documentation. Galasa SimBank is a component that is distributed with Galasa. SimBank simulates a mainframe application and is designed to help you to learn Galasa's basic principles of operation before you start connecting Galasa to your own mainframe application-under-test.

src/markdown-pages/docs/cli-command-reference/zipped-prerequisites.md

@@ -7,17 +7,44 @@ title: "CLI prerequisites offline"
 The following section explains more about the software prerequisites that you need to install so that you are ready to install the zipped distribution for Galasa for running offline.
 
 
-## Prerequisites
+### Java JDK 
 
+Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation.
 
-| Software |  Description  |
+### Gradle
+
+Required to install the offline zipped distribution. You can also build Galasa projects using Gradle. (You can build projects using Maven if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests.
+
+The following table shows the current compatibility between Gradle and Galasa versions: 
+
+
+| Gradle release |  Compatible Galasa version  |
 | :---- | :-------- | 
-| Java JDK  | Required. Galasa tests and Managers are written in Java - you need to install a Java version 11 JDK or later to use it. _Note:_ We do not currently support Java 17 or later. After installing, you must set the `JAVA_HOME` environment variable to your Java JDK installation path and check it set successfully by running the command `echo $JAVA_HOME` on Mac or Unix, or `echo %JAVA_HOME%` on Windows (PowerShell). The returned result shows the path to your JDK installation. |
-| Gradle  | Required to install the zipped distribution. You can also build Galasa projects using Gradle. (You can build projects using Maven if you prefer). Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. All Galasa versions are compatible with Gradle releases 6.9.x.|
-| Maven  | You must install either Maven or Gradle in order to build Galasa projects. Galasa projects are hierarchical file structures that provide the ability to store and run Galasa tests. You do not explicitly need to install Maven because the Galasa plugin downloads and installs it silently during its own installation and configuration. |
-| Docker  | Required if using the Docker image. If you want to deploy the Docker image that is provided in the zip file, you will need to have Docker installed.  |
-| 3270 emulator | Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to [explore Galasa Simbank offline](simbank-cli-offline), a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.| 
+| 6.8.x  | All |
+| 6.9.x  | All |
+| 7.x.x | All | 
+| 8.x.x | 0.36.0 or later |
+
+
+If you are upgrading to Gradle version 8 from an earlier version, see the `Upgrading tests to compile using Gradle version 8` section in the [Upgrading](../upgrading) documentation to understand the changes you need to make to create Galasa projects and build and compile Galasa test code. 
+
+Remember to add Gradle to your PATH. You can check by running `echo $PATH` on Mac or Unix, or `echo %PATH%` on Windows (PowerShell).
+
+
+
+
+### Maven 
+
+You must install either Maven or Gradle in order to build Galasa projects, which are hierarchical file structures that provide the ability to store and run Galasa tests.  
+
+
+### Docker
+
+Required if using the Docker image. If you want to deploy the Docker image that is provided in the zip file, you will need to have Docker installed.
+
+### 3270 emulator 
 
+Optional. Although you do not need a 3270 emulator to run a Galasa test (even if it tests a 3270 application) you can use one to [run Galasa Simbank online](../running-simbank-tests/simbank-cli), a simulated version of an application that helps you get acquainted with Galasa before connecting to a real mainframe to run your own tests. There are many such emulators available but IBM's Personal Communications (PCOMM) is frequently used, as is IBM's Host on Demand software, which includes support for Windows, Linux and MacOS.
 
 
 ## Next steps

src/markdown-pages/docs/ecosystem/ecosystem-authentication.md

@@ -36,7 +36,7 @@ To log out of a Galasa Ecosystem using galasactl, you can use the `galasactl aut
 
 ### Listing personal access tokens
 
-You can retrieve a list of all active personal access tokens in the Ecosystem by using the `galasactl auth tokens get` command. This information is useful if you need to revoke or delete an access token, for example, if a user moves to a new role, or loses a laptop with their access token on it.
+You can retrieve a list of all active personal access tokens in the Ecosystem by using the `galasactl auth tokens get` command. This information is useful if you need to query active tokens with a view to revoking a particular token, for example, if a user moves to a new role, or loses a laptop with their access token on it.
 
 The token ID, creation date, username, and description information is returned, as shown in the following example:
 
@@ -49,5 +49,29 @@ tokenid         created(YYYY/MM/DD)  user                description
 Total:2
 ```
 
-The returned token list is sorted in creation date order, with the earliest creation date first. The description information matches the description that is provided by the user when creating a new access token from the Web UI.
+The returned token list is sorted in creation date order, with the earliest creation date first. The description information matches the description that is provided by the user when creating a new access token from the Galasa Web UI.
+
+
+### Revoking personal access tokens
+
+If a user moves to a new role, or loses a laptop with their personal access token on it, you can log into the Galasa Ecosystem and revoke their access token by using the `galasactl auth tokens delete` command. This ensures that the Ecosystem and systems-under-test remain secure.
+
+You can retrieve a list of available personal access tokens that have been created, along with their token IDs, by running the `galasactl auth tokens get` command, as described in the previous section. 
+
+
+Run the following command to revoke a personal access token with the token ID `myId`:
+
+```
+galasactl auth tokens delete --tokenid myId
+```
+
+*Note:* The `galasactl auth tokens delete` command revokes personal access tokens that a user creates through the Galasa Web UI. When a user runs a CLI command that talks to the Ecosystem, the CLI uses the personal access token to get a JSON Web Token (JWT). A JWT is a separate, temporary token that identifies a user and is used in galasactl commands to talk to the API server. JWTs cannot be revoked, but they do expire, so a user can continue to run CLI commands after revoking their personal access token until their JWT expires. You can remove the JWT that is stored on a user's machine instead of having to wait for the JWT to expire, by running the `galasactl auth logout` command on that machine.
+
+For more information about JWTs, see the `Configuring Dex` section in the [Installing an Ecosystem using Helm](ecosystem-installing-k8s) documentation.
+
+
+
+
+
+
 

src/markdown-pages/docs/ecosystem/ecosystem-installing-k8s.md

@@ -53,8 +53,8 @@ Complete the following steps to install a Galasa Ecosystem by using Helm:
         helm repo add galasa https://galasa-dev.github.io/helm
         ```
     - If the repository exists, run the ```helm repo update``` command to get the latest versions of the packages and then run ```helm search repo galasa``` to see the available charts.<br>
-    _Note:_ The Galasa Ecosystem Helm chart deploys three persistent volumes (PVs). If you need to provide a Kubernetes storage class for these PVs, download the  <a href=https://github.com/galasa-dev/helm/blob/ecosystem-0.35.0/charts/ecosystem/values.yaml target="_blank"> values.yaml</a> file and update the `storageClass` value in the file with the name of a valid storage class on your cluster. If you are deploying to minikube, you can optionally use the standard storage class that is created for you by minikube, but this is not required. 
-1. Download the <a href=https://github.com/galasa-dev/helm/blob/ecosystem-0.35.0/charts/ecosystem/values.yaml target="_blank"> values.yaml</a> file if you have not done so already, and edit the values of the following properties: 
+    _Note:_ The Galasa Ecosystem Helm chart deploys three persistent volumes (PVs). If you need to provide a Kubernetes storage class for these PVs, download the  <a href=https://github.com/galasa-dev/helm/blob/ecosystem-0.36.0/charts/ecosystem/values.yaml target="_blank"> values.yaml</a> file and update the `storageClass` value in the file with the name of a valid storage class on your cluster. If you are deploying to minikube, you can optionally use the standard storage class that is created for you by minikube, but this is not required. 
+1. Download the <a href=https://github.com/galasa-dev/helm/blob/ecosystem-0.36.0/charts/ecosystem/values.yaml target="_blank"> values.yaml</a> file if you have not done so already, and edit the values of the following properties: 
     - Set `galasaVersion` to the version of Galasa that you want to run. (See the [Releases](/releases) documentation for released versions). To ensure that each pod in the Ecosystem is running at the same level, do not use `latest` as the Galasa version.
     - Set `externalHostname` to the DNS hostname or IP address of the Kubernetes node that is used to access the Galasa Ecosystem services. If you are deploying to minikube, the cluster's IP address can be retrieved by running `minikube ip`.
 
@@ -225,22 +225,22 @@ You can then deploy your Galasa tests to a Maven repository and set up a test st
 ## Upgrading the Galasa Ecosystem
 
 
-Get the latest version of the Ecosystem chart and upgrade the Galasa Ecosystem to use the newer version of Galasa - for example version 0.35.0 - by running the following command:
+Get the latest version of the Ecosystem chart and upgrade the Galasa Ecosystem to use the newer version of Galasa - for example version 0.36.0 - by running the following command:
 
 On Mac or Unix:
 
 ```console
 helm repo update \
 helm upgrade <release-name> galasa/ecosystem --reuse-values \
---set galasaVersion=0.35.0 --wait
+--set galasaVersion=0.36.0 --wait
 ```
 
 On Windows (Powershell):
 
 ```console
 helm repo update `
 helm upgrade <release-name> galasa/ecosystem --reuse-values `
---set galasaVersion=0.35.0 --wait
+--set galasaVersion=0.36.0 --wait
 ```
 
 where:<br>