doc/developer-documentation: add docs for enabling new tests

Add developer documentation for enabling new tests.

Signed-off-by: Jeny Sadadia <[email protected]>

Author: Jeny Sadadia

doc/developer-documentation.md

@@ -1,6 +1,6 @@
 ---
 title: "Developer Documentation"
-date: 2024-05-22
+date: 2024-06-18
 description: "KernelCI Pipeline developer manual"
 weight: 4
 ---
@@ -50,3 +50,72 @@ build_configs:
 
 That's it! The tree is enabled now.
 All the jobs defined under `jobs` section of [config file](https://github.com/kernelci/kernelci-pipeline/blob/main/config/pipeline.yaml) would run on the newly added tree until specified otherwise.
+
+
+## Enabling a new test
+
+KernelCI currently runs several test suites. This manual is intended
+to provide documentation for developers on how to enable new tests.
+
+
+### Job definition
+The pipeline [configuration](https://github.com/kernelci/kernelci-pipeline/blob/main/config/pipeline.yaml) file has `jobs` section for defining various build and test jobs. The currently enabled tests are `kver`, `baseline`, `kunit`, `kselftest`, and `sleep` tests.
+`ChromeOS` specific job definitions are located in [config/jobs-chromeos.yaml](https://github.com/kernelci/kernelci-pipeline/blob/main/config/jobs-chromeos.yaml) file.
+
+To enable a new test, an entry needs to be added as follows:
+
+```yaml
+jobs:
+  <job-name>:
+    template: <job-template>
+    kind: <kind of job, either 'kbuild', 'job' or 'test'>
+    image: <docker-image-name>
+    params: <parameters such as arch, compiler, defconfig>
+    rules: <job-rules>
+    kcidb_test_suite: <kcidb-mapping>
+```
+
+Here is the description of each field:
+- A `jinja2` template should be added to [`config/runtime`](https://github.com/kernelci/kernelci-pipeline/tree/main/config/runtime) directory.
+The template will be used to generate test definition.
+- `kind` field denotes type of the job. It should be `kbuild` for build jobs, `job` for a test suite, and simply `test` for a single test case.
+- `image` field specifies the Docker image used for building and running the test.
+- `params` includes parameters used for building the kernel (for `kbuild` job) or running the test, such as architecture, compiler, defconfig option, job timeout, etc.
+- `rules` will define job rules. If the test should be scheduled for specific kernel tree, branch, or version, these rules can be defined in this section.
+- `kcidb_test_suite` is a field used to map KernelCI test suite name with
+KCIDB test. Build jobs (with `kind: kbuild`) do not require this field.
+
+Please have a look at [config/pipeline.yaml](https://github.com/kernelci/kernelci-pipeline/blob/main/config/pipeline.yaml) and [config/jobs-chromeos.yaml](https://github.com/kernelci/kernelci-pipeline/blob/main/config/jobs-chromeos.yaml) files to check currently added job definitions for reference.
+
+
+### Schedule the job
+
+We also need a `scheduler` entry for the newly added job to specify pre-conditions for scheduling and define runtime and platforms for job submissions.
+
+For example,
+```yaml
+scheduler:
+    - job: <job-name>
+      event: <API-pubsub-event>
+      runtime:
+        type: <runtime-type>
+        name: <runtime-name>
+      platforms:
+        - <device-type>
+```
+
+Here is the description of each field:
+- `job` field specifies the job name, which must match the name used in the jobs section
+- `event` specifies the API PubSub event triggering the test scheduling.
+For example, if the test requires a build job such as `kbuild-gcc-10-arm64`
+to be successfully completed, specify the event as follows:
+```
+event:
+    channel: node
+    name: kbuild-gcc-10-arm64
+    result: pass
+```
+- Choose a `runtime` for scheduling and running the job. Currently supported runtimes are shell, docker, lava, and kubernetes. Select a runtime type from `runtimes` section. Please note that `name` property is required for `lava` and `k8s` runtimes to specify which lab/k8s context should run the test as number of LAVA labs such as BayLibre, Collabora, Qualcomm and k8s contexts have been enabled in KernelCI.
+- `platforms` will include a list of device types on which the test should run. It should match entries defined in `platforms` section such as `qemu-x86`, `bcm2711-rpi-4-b`, and so on.
+
+That's pretty much it. After following the above steps, run your pipeline instance and you are good to go with your newly added test!