docs: exactMatch variable

docs/additional_notes.md

@@ -32,3 +32,113 @@ If default labels are removed:
 | 'custom5' | Linux | no match |
 | 'custom5' | [ self-hosted, Linux ] | no match |
 | 'custom5' | [ custom5, self-hosted, Linux ] | no match |
+
+# Exact Match
+
+The multi-runner module has a setting `exactMatch` which affects how the matcherConfig functions.  
+
+The module will decide the runner for the workflow job based on the match in the labels defined in the workflow job and runner configuration. The runner configuration allows the match to be exact or non-exact match. We recommend to use only exact matches. For exact match, all the labels defined in the workflow should be present in the runner configuration matchers and for non-exact match, some of the labels in the workflow, when present in runner configuration, shall be enough for the runner configuration to be used for the job. First the exact matchers are applied, next the non exact ones.
+
+Let's review examples of `exactMatch`.
+
+Scenario 1:
+
+Typical use case. Set `exactMatch` to true.
+
+```
+matcherConfig:
+  exactMatch: true
+  labelMatchers:
+    - [self-hosted, linux, x64, ubuntu-latest]
+    - [self-hosted, linux, x64, ubuntu-2204]
+    ...
+runner_config:
+  runner_extra_labels: "ubuntu-latest,ubuntu-2204"
+    ...
+```
+
+GitHub Actions workflow:
+
+```
+runs-on: [self-hosted, linux, x64, ubuntu-latest]
+```
+
+Runners will launch, and the job will run successfully. 
+
+Scenario 2:
+
+Set `exactMatch` to true. What happens if there are fewer label on the workflow than in the matcher?
+
+```
+matcherConfig:
+  exactMatch: false
+  labelMatchers:
+    - [self-hosted, linux, x64, ubuntu-latest]
+    - [self-hosted, linux, x64, ubuntu-2204]
+    ...
+runner_config:
+  runner_extra_labels: "ubuntu-latest,ubuntu-2204"
+    ...
+```
+
+GitHub Actions workflow:
+
+```
+runs-on: [self-hosted, linux]
+```
+
+Runners will launch, and the job will run successfully. 
+
+Note: This may be a surprising result since "self-hosted, linux" does not look like what you would ordinarily think of as an 'exact match' of "self-hosted, linux, x64, ubuntu-latest".  
+
+A problem with this configuration is the "self-hosted, linux" jobs might consume runners that were really intended for "self-hosted, linux, x64, ubuntu-latest" jobs, leaving those jobs without runners. For this reason, it's not recommended.
+
+Scenario 3:
+
+Set `exactMatch` to true. What happens if there are more label on the workflow than in the matcher?  
+
+```
+matcherConfig:
+  exactMatch: true
+  labelMatchers:
+    - [self-hosted, linux, x64]
+    ...
+runner_config:
+  runner_extra_labels: ""
+    ...
+```
+
+GitHub Actions workflow:
+
+```
+runs-on: [self-hosted, linux, x64, ubuntu-latest]
+```
+
+`exactMatch` will prevent runners from launching. At least this is a correct outcome in the sense that GitHub would not provision jobs on runners with too few labels.  
+
+Scenario 4:
+
+The same as 1, except set `exactMatch: false`.   
+
+All labels will happen to match (anyway). Runners will launch and the job will run successfully.   
+If you are planning to have exact matches it would be clearer to switch this to `exactMatch: true`.  
+
+Scenario 5:
+
+The same as 2, except set `exactMatch: false`.  
+
+The same results and warnings as Scenario 2. Labels will happen to match (anyway). The jobs will run successfully, but might use runners that should be reserved for other jobs.  
+
+Scenario 6:
+
+The same as 3, except set `exactMatch: false`.
+
+Runners will launch. However, GitHub would not provision jobs on those runners with too few labels. This case should definitely be avoided (having runners launch, which GitHub will be unable to use).   
+
+A problem with `exactMatch: false` is that one of the main situations it enables is Scenario 6, which precisely should not happen. 
+
+--- 
+
+In summary, all the examples with `exactMatch: false` are not recommended.  
+
+Mainly, only Scenario 1 includes an unambiguous, correct configuration.