From 566a6d00aeff42afb7fa2fda595b48e562a8e386 Mon Sep 17 00:00:00 2001
From: AlexVCaron <alex.valcourt.caron@usherbrooke.ca>
Date: Wed, 25 Sep 2024 04:19:49 +0000
Subject: [PATCH] add doc on how to define resource allocation and assign
 specialized runners

---
 docs/MODULE.md       | 49 +++++++++++++++++++++++++++++++++++++++++++-
 docs/SUBWORKFLOWS.md |  7 ++++++-
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/MODULE.md b/docs/MODULE.md
index 93fe53b..eea609b 100755
--- a/docs/MODULE.md
+++ b/docs/MODULE.md
@@ -295,7 +295,7 @@ Make sure there is no more comments generated by the `nf-core` template, and you
 The `nextflow.config` file does not exist by default, so you will have to create it if needed. This is not mandatory, except if you have defined optional parameters with `task.ext` and want to alter their values for some test cases. Refer to [this section](#defining-optional-input-parameters) to
 see how to scope those parameters to specific tests using `selectors`.
 
-## Generate tests snapshots
+### Generate tests snapshots
 
 > [!WARNING]
 > Verify you are located at the root of `nf-neuro` (not inside modules) before
@@ -315,6 +315,53 @@ smoothly, look at the snapshot file produced at `tests/main.nf.test.snap` in you
 directory and validate that ALL outputs produced by test cases are caught. Their `md5sum` is
 critical to ensure future executions of your test produce valid outputs.
 
+### Request for more test resources
+
+Test runners are tailored to restrain their resources usage to specifically what is asked for by
+Nextflow through the configuration files. For `nf-neuro` tests, you can find this configuration in
+`tests/config/nextflow.config`. If any of your tests ask for more, you need to define it correctly.
+
+> [!NOTE]
+> The container detects out-of-bound resource consumption automatically, tests will fail if they
+> haven't been assigned them sufficiently. It's a good way to catch them.
+
+First, resource requirements need to be defined in the `nextflow.config` file(s) of your test
+cases. Add the `process.cpu` and `process.memory` and set their requirements as needed :
+
+```
+process.memory = '9G'
+process.cpus = 6
+```
+
+or
+
+```
+process {
+  memory = '10G'
+  cpus = 6
+}
+```
+
+To allow test runners on your PR to run with sufficient resources, you'll need to specify to which
+class of runners to assign to. To do so, edit `.github/workflows/run_checks_suite.yml`. Find the
+`matrix` definition for the `nf-test` job (currently around `line 133`) and add the following
+request for a runner in the `include` section :
+
+```
+- runner: <name-of-the-runner-class>
+  path: modules/nf-neuro/<category>/<tool>
+```
+
+Available runner classes that superseed `default` :
+
+| Runner Class                   | Resources                               |
+| ------------------------------ | --------------------------------------- |
+| (default)                      | <ul><li>4 CPU</li><li>4Gb RAM</li></ul> |
+| scilus-nf-neuro-bigmem-runners | <ul><li>16Gb RAM</li></ul>              |
+
+> [!IMPORTANT]
+> Specialized runners are limited !!! They are allocated for hungry processes, such as **AI/ML** models and **large dataset studies**, don't abuse them. _The more they are requested for, the longer PR take to merge_, so don't ask for them for nothing, meaning be smart in designing your modules ! **PRs deemed not needing them will be automatically closed.**
+
 ## Lint your code
 
 Before submitting to _nf-neuro_, once you've commit and push everything, the code need to be correctly linted, else the checks won't pass. This is done using `prettier` and `editorconfig-checker` on your new module, through the _nf-core_ command line :
diff --git a/docs/SUBWORKFLOWS.md b/docs/SUBWORKFLOWS.md
index 9f1c2cb..94abb35 100644
--- a/docs/SUBWORKFLOWS.md
+++ b/docs/SUBWORKFLOWS.md
@@ -142,7 +142,12 @@ don't need to specify them all. Provide at least 3 relevant `keywords` and list
 
 ### Create test cases
 
-Adding tests to your subworkflow is nearly identical as creating tests for a module. For detailed instructions, please see [here](./MODULE.md#create-test-cases).
+Adding tests to your subworkflow is near identical to modules. For detailed instructions, please see [here](./MODULE.md#create-test-cases).
+
+> [!IMPORTANT]
+> Take attention to the `wording` ! As the section refers to `modules` and `process`, carefully
+> replace them with `subworkflow`, since both concepts boil down to this single descriptor in this
+> specific case.
 
 ## Lint your code