From acf1416232e44fb6b5e7e15493f4aa16bf80e22e Mon Sep 17 00:00:00 2001 From: Clay McLeod Date: Sat, 16 Nov 2024 11:35:46 -0600 Subject: [PATCH] docs: updates the `README.md` content This commit is the squashed product of the following commits: * docs: adds `README.md` header image * docs: updates `README.md` with new information, deduplicates content * revise: add @jdidion's suggestions * revise: one sentence per line Co-authored-by: John Didion --- .github/assets/readme-header.png | Bin 0 -> 44763 bytes README.md | 171 +++++++++---------------------- 2 files changed, 47 insertions(+), 124 deletions(-) create mode 100644 .github/assets/readme-header.png diff --git a/.github/assets/readme-header.png b/.github/assets/readme-header.png new file mode 100644 index 0000000000000000000000000000000000000000..e4b8f6d2a94eb91bcbf3aca368d7b710f5f572bc GIT binary patch literal 44763 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 UCU~hlL*DV1ff + + -The **Workflow Description Language (WDL)** is an open standard for describing data processing workflows with a human-readable and writeable syntax. -WDL makes it straightforward to define analysis tasks, connect them together in workflows, and parallelize their execution. -The language strives to be accessible and understandable to all manner of users, including programmers, analysts, and operators of a production system. -The language enables common patterns, such as scatter-gather and conditional execution, to be expressed simply. -WDL is designed for portability, and there are several [implementations](#execution-engines-and-platforms) to choose from that run in a variety of environments, including HPC systems and cloud platforms. +
-## Versioning +The **Workflow Description Language (WDL)** (pronounced as _/hwɪdl/_ or "whittle" with a 'd') is an open standard for describing data processing workflows using a human-readable/writeable syntax. +It introduces a domain-specific language that aims to provide simple but powerful facilities for (a) defining atomic units of computation (a `task`), (b) for connecting those atomic units together into a larger computation graph (a `workflow`), and (c) for effortlessly scaling the execution of these graphs in multiple environments. -WDL versioning follows [semantic versioning](https://semver.org) conventions. +Most fundamentally, WDL differentiates itself from other workflow languages by focusing on ease of implementation and accessibility to a wide range of users, including software engineers, domain experts (e.g., biologists), and operators of production computational systems. +Furthermore, idiomatic workflow execution patterns, such as conditional execution, dynamic resource allocation, and scatter-gather operations, are simply expressed. +Last, the language is driven and developed by a community of distributed volunteers as an open standard; +there is no single execution engine, and anyone can build tooling to contribute to the ecosystem. +Today, [several engines and platforms](#execution-engines-and-platforms) exist and cover most execution environments (all major HPCs, all major clouds, local execution). -The WDL *language* has a two-number version (e.g., `1.2`). -An increase in the minor (second) version number (e.g., `1.1` to `1.2`) indicates the addition of, or non-breaking changes to, the language or standard library functions. -An increase in the major (first) version number (e.g., `1.0` to `2.0`) indicates that breaking changes have been made. +## Getting Started -The WDL *specification* has a three-number version (e.g., `1.2.0`). -The specification version tracks the language version, but there may also be patch releases (indicated by a change to the patch, or third, version number) that include fixes for typos, additional examples, or non-breaking clarifications of ambiguous language. +If you're new to WDL, welcome 👋. We _highly_ recommend that you read the [getting started documentation][wdl-docs] to learn how to write tasks and workflows. -## Language Specifications - -The WDL specification contains all relevant information for users and developers, including those wanting to implement an execution engine. -This GitHub project uses the branch for the current version of the specification as its primary branch, so you will always see the current version of the specification so long as you visit this project's [root URL](https://github.com/openwdl/wdl). -Users are strongly encouraged to use the current version of the specification unless absolutely necessary. - -This branch is for version **1.2** of the [WDL language specification](https://github.com/openwdl/wdl/blob/wdl-1.2/SPEC.md). -All development of new *non-breaking* features should be done against this branch. - -Previous versions of the spec can be found here: - -- [1.1](https://github.com/openwdl/wdl/blob/wdl-1.1/SPEC.md) -- [1.0](https://github.com/openwdl/wdl/blob/main/versions/1.0/SPEC.md) - -There are a number of draft versions that correspond to initial efforts at creating WDL. -While these are functional specifications, they should not be considered feature complete, and they contain many bugs and irregularities. - -- [draft-3](https://github.com/openwdl/wdl/blob/main/versions/draft-3/SPEC.md) -- [draft-2](https://github.com/openwdl/wdl/blob/main/versions/draft-2/SPEC.md) -- [draft-1](https://github.com/openwdl/wdl/blob/main/versions/draft-1/SPEC.md) - -The next *major* version of the specification is [2.0](https://github.com/openwdl/wdl/blob/wdl-2.0/SPEC.md). -All development of new *breaking* features should be done against that branch. - -## Community and Support +### Join the community The WDL community depends on your involvement to thrive. You are encouraged to ask questions, help other users, and make contributions where you can. -Interactions occur primarily on [GitHub](https://github.com/openwdl/wdl) and [Slack](https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw). -The WDL community also has an official [blog](https://dev.to/openwdl) where announcements are made. - -### Asking a Question - -- Search in the [discussions](https://github.com/openwdl/wdl/discussions) to see if the question has been asked already; if not, start a new discussion. -- Join our [Slack](https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw) and ask in the `#support` channel. -- Search the [Bioinformatics Stack Exchange](https://bioinformatics.stackexchange.com/search?q=wdl) for previously answered questions, or ask a new question. -- Search the [Google Group](https://groups.google.com/a/openwdl.org/forum/#!forum/community) for previously answered questions. This group is largely inactive, so you're encoraged to ask new questions in one of the above places instead. - -### Bugs and New Features - -- Search for an existing [issue](https://github.com/openwdl/wdl/issues). If your issue has not already been reported, create a new one. -- For feature reqeusts, you are encoraged to first start a discussion at one of the places listed above to get feedback from the community. -- If you'd like to provide a fix/implementation for an issue, please read about [contributing](#contributing) before submitting a [pull request](https://github.com/openwdl/wdl/pulls). - -### Documentation +Interactions occur primarily on [GitHub][github-main] and [Slack][join-slack]. +The WDL community also has an official [website](https://openwdl.org/) and [blog](https://openwdl.org/blog/) that you can follow to stay up to date. -- [wdl-docs](https://docs.openwdl.org/en/stable/) -- [learn-wdl](https://github.com/openwdl/learn-wdl) -- [WDL Resources](https://support.terra.bio/hc/en-us/sections/360007274612-WDL-Resources) provided by Terra (a product of the Broad Institute) +* **If you have questions about using WDL,** search in the [discussions](https://github.com/openwdl/wdl/discussions) to see if the question has been asked already; if not, feel free to start a new discussion. You can also join the `#support` channel on [Slack][join-slack] to ask more transient questions. +* **If you are a user of an execution engine and encounter a bug or want to request a feature,** you are encouraged to file an issue on the relevant execution engine's repository. Please do not file these types of questions/requests on this repository. +* **If you are an implementor and need clarification on the specification or want to request a feature to be added to the WDL language,** please file an issue on the WDL specification's [GitHub issues][github-issues] page. +- **If you'd like to contribute to the WDL specification,** please read the [contributing](#contributing) section before submitting a pull request. -## Published Workflows +## Specification -The following are collections of open-source WDL workflows. -The WDL task or workflow you need may already be available in one of these repositories, or you may find a similar workflow and customize it to your needs. - -- [Dockstore](https://dockstore.org/search?entryType=workflows&descriptorType=WDL&searchMode=files) -- [BioWDL](https://github.com/biowdl) -- [Broad Institute WARP](https://broadinstitute.github.io/warp/docs/get-started/) -- [GATK Workflows](https://github.com/gatk-workflows/) -- [ENCODE](https://www.encodeproject.org/pipelines/) -- [Terra](https://app.terra.bio) (requires registration) - -## Software and Tools - -### Execution Engines and Platforms - -WDL does not have an official implementation. -Third parties are relied upon to provide installable software or hosted platforms that interpret and execute WDL workflows and tasks. -Although WDL does not yet have an official compliance program or certification process, implementers are expected to design their tools according to the specification so as to maximize the portability of workflows across implementations. -Nonetheless, implementers may provide additional optional features specific. -Please see the documentation associated with each tool/platform for information on available execution options and support. - -| Implementation | Requires Installation | Local Execution | HPC | Cloud | -| ------------------------------------------------------------------------------ | --------------------- | --------------- | ----- | --------------------- | -| [AWS HealthOmics](https://docs.aws.amazon.com/omics/latest/dev/workflows.html) | No | No | No | AWS | -| [Cromwell](https://github.com/broadinstitute/cromwell) * | Yes | Yes | Many | AWS Batch, Azure, GCP | -| [dxCompiler](https://github.com/dnanexus/dxCompiler) | Yes | No | No | DNAnexus | -| [MiniWDL](https://github.com/chanzuckerberg/miniwdl) | Yes | Yes | SLURM | AWS Batch | -| [Terra](https://terra.bio/) | No | No | No | Azure, GCP | - -\* Also see [WDL Runner](https://github.com/broadinstitute/wdl-runner), a script for launch WDL workflows on GCP using Cromwell - -### Grammars, Parsers, and Language Support - -- The WDL [parsers repository](https://github.com/openwdl/wdl-parsers/) provides grammar definitions in various formats and generated parsers for various languages. -- [MiniWDL](https://github.com/chanzuckerberg/miniwdl) provides python bindings for WDL as well as commandline tools for validation, linting, and generating workflow input templates. -- [WOMTool](https://cromwell.readthedocs.io/en/stable/WOMtool/) is a standalone Java tool for WDL parsing, validating, linting, and diagramming. -- [wdlTools](https://github.com/dnanexus/wdlTools) - provides 1) a parser Java/Scala library, based on the [ANTLR4 grammars](https://github.com/openwdl/wdl-parsers) grammars, for WDL draft-2, 1.0, 1.1, and 2.0; and 2) command-line tools for sytanx checking, type-checking, linting, code formatting (including upgrading from older to newer WDL versions), generating documentation, and executing WDL tasks locally. -- [sprocket](https://github.com/stjude-rust-labs/sprocket) a package manager and linter for WDL files. - -### IDE Support - -| IDE | Tool | -| ------------------ | ------------------------------------------------------------------------------------------------ | -| Emacs | [poly-wdl](https://github.com/jmonlong/poly-wdl) | -| Emacs | [wdl-mode](https://github.com/zhanxw/wdl-mode) | -| JetBrains | [Winstanly](https://plugins.jetbrains.com/plugin/8154-winstanley-wdl) | -| Sublime | [WDL Syntax Highlighter](https://github.com/broadinstitute/wdl-sublime-syntax-highlighter) | -| Vim | [vim-wdl](https://github.com/broadinstitute/vim-wdl) | -| Visual Studio Code | [WDL Syntax Highlighter](https://marketplace.visualstudio.com/items?itemName=broadinstitute.wdl) | +The WDL specification contains all relevant information for users and developers, including those wanting to implement an execution engine. +This GitHub project uses the branch for the current version of the specification as its primary branch, so you will always see the current version of the specification so long as you visit this project's [root URL][github-main]. +Users are strongly encouraged to use the current version of the specification unless absolutely necessary. -### Documentation +* This branch is for version `1.2` of the specification ([link](https://github.com/openwdl/wdl/blob/wdl-1.2/SPEC.md)). All development of new *non-breaking* features should be done against this branch. +* The next major version of the specification is version `2.0` ([link](https://github.com/openwdl/wdl/blob/wdl-2.0/SPEC.md)). All development of new *breaking* features should be done against that branch. -- [wdl-aid](https://github.com/biowdl/wdl-aid) generates documentation for the inputs of WDL workflows, based on the parameter_meta information defined in the WDL file. -- [wdldoc](https://github.com/stjudecloud/wdldoc) +If desired, previous versions of the spec can be found on the [GitHub branches page][github-branches]. -### Testing +### Versioning -- [wdl-tests](https://github.com/openwdl/wdl-tests) is a collection of test cases for WDL implementations. A specification is provided for writing new tests that are compatible with automated testing frameworks. -- [Pytest-workflow](https://github.com/LUMC/pytest-workflow) is a implementation-agnostic workflow tester. It can be used with both Cromwell and MiniWDL. Uses pytest as the underlying test framework. Tests can be specified in either YAML format or python code. -- [Pytest-wdl](https://github.com/EliLillyCo/pytest-wdl) is a plugin for the pytest unit testing framework that enables testing of WDL tasks and workflows. Tests can be specified in either YAML format or python code. +All products of the WDL project, including the specification, follow [semantic versioning](https://semver.org). +That being said, the version of the WDL _language_ and the version of the WDL _specification_ are distinct: -### Packaging +* The WDL _language_ has a two-number version (e.g., `1.2`). An increase in the minor (second) version number (e.g., `1.1` to `1.2`) indicates the addition of, or non-breaking changes to, the language or standard library functions. An increase in the major (first) version number (e.g., `1.0` to `2.0`) indicates that breaking changes have been made. -- [miniwdl zip](https://miniwdl.readthedocs.io/en/latest/zip.html) generates a ZIP file including a given WDL source code file and any other WDL files it imports. The ZIP file can be supplied directly to miniwdl run, which can extract it automatically. -- [wdl-packager](https://github.com/biowdl/wdl-packager) packages a workflow and all of its imports into a zip file. The zip can be used as an imports zip package for cromwell. The utility can add non-WDL files (such as the license) to the zip package and provides options to package the zip in a binary reproducible way. +* The WDL _specification_ has a three-number version (e.g., `1.2.0`). The specification version tracks the language version, but there may also be patch releases (indicated by a change to the patch, or third, version number) that include fixes for typos, additional examples, or non-breaking clarifications of ambiguous language. -## Contributing +### Contributing WDL only advances through community contributions. While participating in discussions and submitting issues are great ways to be involved, help is also needed to implement changes to the specification. For more information on how you can contribute, please read the [Contributing](CONTRIBUTING.md) guide. -### RFC Process +### Governance + +The WDL specification is entirely community driven; +however, it is overseen by a [Governance committee](GOVERNANCE.md). +If you are interested in being involved in WDL governance, please join the [Slack][join-slack] and post a message in the `#general` channel. + +### License -Submitted [pull requests](https://github.com/openwdl/wdl/pulls) are subject to the [RFC Process](RFC.md). -Please review and familiarize yourself with the process if you would like to see changes submitted to the specification. +The WDL specification is made available to you under the permissive [BSD 3-Clause License](./LICENSE). -## Governance +© 2024 The OpenWDL Developers -The WDL specification is entirely community driven; however, it is overseen by a [Governance committee](GOVERNANCE.md). -If you are interested in being involved in WDL governance, please join the [Slack](https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw) and post a message in the `#general` channel. +[github-main]: https://github.com/openwdl/wdl +[github-branches]: https://github.com/openwdl/wdl/branches +[github-issues]: https://github.com/openwdl/wdl/issues +[join-slack]: https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw +[wdl-docs]: https://docs.openwdl.org/en/stable