From 32c93486abf3b5b40afddc981b8a9fd0fc8ce17e Mon Sep 17 00:00:00 2001
From: Robrecht Cannoodt <rcannood@gmail.com>
Date: Mon, 15 Jul 2024 15:40:49 +0200
Subject: [PATCH] Update CONTRIBUTING.md

---
 CONTRIBUTING.md | 66 +++++++++++++++++++++++++++++--------------------
 1 file changed, 39 insertions(+), 27 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7393bc7e..a9716791 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -65,22 +65,21 @@ runners:
 Fill in the relevant metadata fields in the config. Here is an example of the metadata of an existing component.
 
 ```yaml
-functionality:
-  name: arriba
-  description: Detect gene fusions from RNA-Seq data
-  keywords: [Gene fusion, RNA-Seq]
-  links:
-    homepage: https://arriba.readthedocs.io/en/latest/
-    documentation: https://arriba.readthedocs.io/en/latest/
-    repository: https://github.com/suhrig/arriba
-    issue_tracker: https://github.com/suhrig/arriba/issues
-  references:
-    doi: 10.1101/gr.257246.119
-    bibtex: |
-      @article{
-        ... a bibtex entry in case the doi is not available ...
-      }
-  license: MIT
+name: arriba
+description: Detect gene fusions from RNA-Seq data
+keywords: [Gene fusion, RNA-Seq]
+links:
+  homepage: https://arriba.readthedocs.io/en/latest/
+  documentation: https://arriba.readthedocs.io/en/latest/
+  repository: https://github.com/suhrig/arriba
+  issue_tracker: https://github.com/suhrig/arriba/issues
+references:
+  doi: 10.1101/gr.257246.119
+  bibtex: |
+    @article{
+      ... a bibtex entry in case the doi is not available ...
+    }
+license: MIT
 ```
 
 ### Step 4: Find a suitable container
@@ -162,7 +161,7 @@ argument_groups:
       type: file
       description: |
         File in SAM/BAM/CRAM format with main alignments as generated by STAR
-        (Aligned.out.sam). Arriba extracts candidate reads from this file.
+        (`Aligned.out.sam`). Arriba extracts candidate reads from this file.
       required: true
       example: Aligned.out.bam
 ```
@@ -175,7 +174,7 @@ Several notes:
 
 * Input arguments can have `multiple: true` to allow the user to specify multiple files.
 
-
+* The description should be formatted in markdown.
 
 ### Step 8: Add arguments for the output files
 
@@ -220,7 +219,7 @@ argument_groups:
 
 Note: 
 
-* Preferably, these outputs should not be directores but files. For example, if a tool outputs a directory `foo/` containing files `foo/bar.txt` and `foo/baz.txt`, there should be two output arguments `--bar` and `--baz` (as opposed to one output argument which outputs the whole `foo/` directory).
+* Preferably, these outputs should not be directories but files. For example, if a tool outputs a directory `foo/` containing files `foo/bar.txt` and `foo/baz.txt`, there should be two output arguments `--bar` and `--baz` (as opposed to one output argument which outputs the whole `foo/` directory).
 
 ### Step 9: Add arguments for the other arguments
 
@@ -230,6 +229,8 @@ Finally, add all other arguments to the config file. There are a few exceptions:
 
 * Arguments related to printing the information such as printing the version (`-v`, `--version`) or printing the help (`-h`, `--help`) should not be added to the config file.
 
+* If the help lists defaults, do not add them as defaults but to the description. Example: `description: <Explanation of parameter>. Default: 10.`
+
 
 ### Step 10: Add a Docker engine
 
@@ -304,6 +305,14 @@ arriba \
   $([ "$par_fill_gaps" = "true" ] && echo "-I")
 ```
 
+Notes:
+
+* If your arguments can contain special variables (e.g. `$`), you can use quoting (need to find a documentation page for this) to make sure you can use the string as input. Example: `-x ${par_bam@Q}`.
+
+* Optional arguments can be passed to the command conditionally using Bash [parameter expansion](https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html). For example: `${par_known_fusions:+-k ${par_known_fusions@Q}}`
+
+* If your tool allows for multiple inputs using a separator other than `;` (which is the default Viash multiple separator), you can substitute these values with a command like: `par_disable_filters=$(echo $par_disable_filters | tr ';' ',')`.
+
 
 ### Step 12: Create test script
 
@@ -311,13 +320,11 @@ arriba \
 If the unit test requires test resources, these should be provided in the `test_resources` section of the component. 
 
 ```yaml
-functionality:
-  # ...
-  test_resources:
-    - type: bash_script
-      path: test.sh
-    - type: file
-      path: test_data
+test_resources:
+  - type: bash_script
+    path: test.sh
+  - type: file
+    path: test_data
 ```
 
 Create a test script at `src/xxx/test.sh` that runs the component with the test data. This script should run the component (available with `$meta_executable`) with the test data and check if the output is as expected. The script should exit with a non-zero exit code if the output is not as expected. For example:
@@ -366,7 +373,7 @@ echo ">> Check if output is empty"
 [ ! -s "fusions_discarded.tsv" ] && echo "Output file fusions_discarded.tsv is empty" && exit 1
 ```
 
-### Step 12: Create a `/var/software_versions.txt` file
+### Step 13: Create a `/var/software_versions.txt` file
 
 For the sake of transparency and reproducibility, we require that the versions of the software used in the component are documented.
 
@@ -378,6 +385,11 @@ engines:
     image: quay.io/biocontainers/xxx:0.1.0--py_0
     setup:
       - type: docker
+        # note: /var/software_versions.txt should contain:
+        #   arriba: "2.4.0"
         run: |
           echo "xxx: \"0.1.0\"" > /var/software_versions.txt
 ```
+
+
+## Differences