Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reproducible and portable workflows! #121

Open
wants to merge 6 commits into
base: gh-pages
Choose a base branch
from
Open

Reproducible and portable workflows! #121

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d09e5c1
Reproducible and portable workflows!
Oct 17, 2018
3600f2d
Add hard line breaks
Oct 18, 2018
57e9b35
Clarify language around images
Oct 18, 2018
c5f434a
Merge branch 'gh-pages' into kaushik-repro-port
mr-c Oct 19, 2018
78b384f
Merge branch 'gh-pages' into kaushik-repro-port
Oct 19, 2018
f01fa93
Merge branch 'gh-pages' into kaushik-repro-port
mr-c Aug 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions _extras/recommended-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence no verb :-)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am arguably a native speaker and I beg to differ. Not only is it a complete and grammatically correct sentence, but it does too have a verb.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps I was too harsh, my apologies. The point being, this is supposed to be a list of actions: things to do.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mr-c oh not at all! It did send me on a trip down memory lane to English language class. I vaguely recall that there can be sentences without verbs. I suspect it was "Yes." and "No."

I was entertained by https://english.stackexchange.com/questions/258/shortest-comprehensive-sentence-in-english

Ok, back to work. Many thanks for reviewing! I will address your comments


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Currently (2018) the best way approach this ideal is to package the exact software environment in an image
- Currently (2018) the best way approach this ideal is to package the exact software environment in software container

(such as a `Docker Image`) and specify the image via the `DockerPull` field. Use an image identifier that is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
(such as a `Docker Image`) and specify the image via the `DockerPull` field. Use an image identifier that is
(in the Docker container format) and specify the image via the `DockerPull` field. Use an image identifier that is

resilient to updates to the container.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

be specific; what does "image identifier that is resilient to updates to the container" mean? Show an example.

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
may silently change the behavior of the tool at each run.
may silently change the behavior of the tool in the future.```

- 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That should be a separate suggestion with its own check box and example.


☐ No `type: string` parameters for names of input or reference
files/directories; use `type: File` or `type: Directory` as appropriate.
Expand Down