diff --git a/_extras/recommended-practices.md b/_extras/recommended-practices.md index 5324bdff..8890b539 100644 --- a/_extras/recommended-practices.md +++ b/_extras/recommended-practices.md @@ -4,10 +4,24 @@ title: "Recommended Practices" permalink: /rec-practices/ --- -Below are a set of recommended good practices to keep in mind when writing a -Common Workflow Language description for a tool or workflow. These guidelines -are presented for consideration on a scale of usefulness: more is better, not -all are required. +Below are a set of recommended good practices to keep in mind when writing a Common Workflow Language +description for a tool or workflow. These guidelines are presented for consideration on a scale of +usefulness: more is better, not all are required. + +☐ Reproducibility and Portability are essential goals of scientific workflow developers. + +Ideally a workflow developer would be able to rigidly specify the software and hardware +environment a tool should run in to ensure portability and reproducibility. + +- Currently (2018) the best way approach this ideal is to package the exact software environment in an image +(such as a `Docker Image`) and specify the image via the `DockerPull` field. Use an image identifier that is +resilient to updates to the container. +- If this is not possible, carefully specifying software tools and dependencies using `SoftwareRequirement` +is the next best resort. Be aware that changes in the tool repositories the tools are being pulled from +may silently change the behavior of the tool at each run. +- Not specifying a docker image or software requirements will result in a non-reproducible, + non-portable workflow! +- Do specify CPU and memory requirements where required ☐ No `type: string` parameters for names of input or reference files/directories; use `type: File` or `type: Directory` as appropriate.