Merge branch 'hotfix/1.11.6'

docs/conf.py

@@ -35,14 +35,17 @@
 #
 # needs_sphinx = '1.0'
 
+# https://github.com/sphinx-doc/sphinx/issues/7369 403 blocks by support.orcid.org
+user_agent = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36'
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['recommonmark', 'sphinxcontrib.discourse']
 
 linkcheck_anchors = False
 linkcheck_ignore = [
-    'http://localhost:8080/ga4gh/wes/v1',
+    'http://localhost:8080/ga4gh/wes/v1', 'https://support.orcid.org/hc/en-us/articles/360006894754-Edit-works',
     'http://dx.doi.org/10.12688/f1000research.10137.1', 'https://dockstore.org/api/',
     'https://dockstore.org:8443/', 'https://support.terra.bio/hc/en-us/sections/360007274612/',
     'https://docs.snyk.io/getting-started/getting-started-snyk-products/getting-started-snyk-open-source',

docs/getting-started/dockstore-workflows.rst

@@ -9,8 +9,6 @@ Tutorial Goals
 --------------
 
 
--  Learn the differences between tools and workflows across Descriptor
-   Languages
 -  Discover how to register a workflow on Dockstore
 -  Publish your workflow
 
@@ -29,32 +27,6 @@ registration to GitHub, Bitbucket or GitLab. It assumes that you already
 have a repository which contains a workflow and are now trying to register
 it in Dockstore.
 
-Comparison of Tools and Workflows Across Descriptor Languages
--------------------------------------------------------------
-
-When Dockstore was created, CWL was the first descriptor language we
-supported. It had a very clear distinction between a Tool and a
-Workflow. Descriptor languages like WDL and Nextflow are less clear
-about this distinction so we briefly describe our working definitions
-below:
-
-+------------------------+------------------------------------------+-----------------------------------------------+
-| Language               | Tool                                     | Workflow                                      |
-+========================+==========================================+===============================================+
-| CWL                    | - Class: CommandLineTool                 | - Class: Workflow                             |
-+------------------------+------------------------------------------+-----------------------------------------------+
-| WDL                    | - A single task with Docker image        | - >1 task                                     |
-|                        | - A workflow section that runs the task  | - A workflow section that connects the tasks  |
-|                        | - An associated Docker image             |                                               |
-+------------------------+------------------------------------------+-----------------------------------------------+
-| Nextflow               | - N/A                                    | - Any valid Nextflow workflow                 |
-+------------------------+------------------------------------------+-----------------------------------------------+
-| Galaxy                 | - N/A*                                   | - Any valid Galaxy workflow                   |
-+------------------------+------------------------------------------+-----------------------------------------------+
-
-\* There are tools that make up Galaxy workflows from the Galaxy toolbox or ToolShed.
-Dockstore does not support registration of these tools.
-
 Register Your Workflow in Dockstore
 -----------------------------------
 There are a variety of ways to get your workflows into Dockstore. Users can either

docs/getting-started/getting-started-with-galaxy.rst

@@ -4,20 +4,6 @@ Getting Started with Galaxy
 
 Dockstore supports Galaxy workflows and the :doc:`Launch with Galaxy <../../launch-with/galaxy-launch-with>` tutorial elaborates different ways to launch a Galaxy workflow. Please note that Galaxy workflows cannot be launched by the Dockstore CLI.
 
-Galaxy instances are offered by many institutions, free and otherwise. Each come with their own advantages and users can make a choice based on their own needs.
-
-Using Galaxy Servers
---------------------
-Institutions across the world maintain Galaxy instances that are often shared with the greater community for free, subsidized by grants, such as the `Use Galaxy Org <https://usegalaxy.org/>`__. These are great ways to learn and use Galaxy, and many offer valuable learning resources such as the `Galaxy Training Network <https://training.galaxyproject.org/>`__.
-
-Custom Galaxy in the Cloud with Terra, AnVIL, and BioData Catalyst
-------------------------------------------------------------------
-Galaxy is now integrated into the Terra cloud workspace. This provides Galaxy users the ability to readily create a custom environment that they can scale to their needs. Additionally, the Terra workspace is able to access a rich data corpus hosted in the cloud, including many controlled-access datasets, thus allowing users to securely conduct analyses with this data.
-
-Unlike WDL and CWL, Galaxy
-workflows in the near term are primarily created and modified
-from the Galaxy workflow editor (GUI), instead of a text editor.
-
 Tutorial Goals
 --------------
 
@@ -28,15 +14,31 @@ Tutorial Goals
 -  Push the workflow to GitHub
 -  Make a GitHub release
 
+About Galaxy
+------------
+
+Galaxy is a web-based platform for data analysis. Galaxy is open source and can be installed locally. Alternatively, many institutions offer access to managed Galaxy instances, free and otherwise. Different Galaxy instances come with their own advantages and users can make a choice based on their own needs.
+
+Using Existing Galaxy Servers
+-----------------------------
+
+Institutions across the world maintain Galaxy instances that are shared with the greater community and are a great way to learn and use Galaxy. Some of these instances are subsidized by grants and offered for free (such as the `Galaxy US <https://usegalaxy.org/>`__, `Galaxy EU <https://usegalaxy.eu/>`__, and `Galaxy AU <https://usegalaxy.org.au/>`__) and some are available for a fee (such as `Galaxy AnVIL <https://anvil.terra.bio/>`__ or `Galaxy Pro <https://researcher.galaxyworks.io/>`__). A lot of great learning resources are available on the the `Galaxy Training Network <https://training.galaxyproject.org/>`__, with help on specific questions available via `Galaxy Help <https://help.galaxyproject.org/>`__.
+
+Using Custom Galaxy in the Cloud with Terra, and AnVIL
+------------------------------------------------------------------------
+Galaxy is also integrated into the Terra cloud workspace. This provides users the ability to readily create a custom Galaxy environment scaled to their needs or with additional tools installed. Additionally, the Terra workspace is able to access a rich data corpus hosted in the cloud, including many controlled access datasets, thus allowing users to conduct analyses with this data in a compliance-based environment.
+
+Unlike WDL and CWL, Galaxy workflows in the near term are created and modified from the Galaxy workflow editor (GUI), instead of a text editor.
+
 Create a basic Galaxy workflow
 ------------------------------
 
-Create and run your workflow in Galaxy. Here  is a tutorial for `Creating, Editing, Importing Galaxy Workflows <https://training.galaxyproject.org/training-material/topics/galaxy-interface/tutorials/workflow-editor/tutorial.html>`__
+If you would like to create and run your own workflow in Galaxy, here  is a tutorial for `Creating, Editing, Importing Galaxy Workflows <https://training.galaxyproject.org/training-material/topics/galaxy-interface/tutorials/workflow-editor/tutorial.html>`__ from the Galaxy Training Network.
 
 Export the workflow to a file
 -----------------------------
 
-In Galaxy:
+Once you’ve created a workflow in Galaxy, you can export it. This is a required step to register the workflow with Dockstore.
 
 - Click on the Galaxy UI Workflow link at the top of the page.
 - Click on the workflow name to expose the drop down menu.
@@ -73,21 +75,19 @@ These steps are outlined `here. <https://docs.github.com/en/github/managing-file
 Releasing on GitHub
 -------------------
 
-Now that we've successfully created our workflow in Galaxy and tested it the
+Now that we've successfully created our workflow in Galaxy and uploaded it to GitHub, the
 workflow is ready to share with others. Making a release on GitHub will tag
 your GitHub repository with a version tag so you can always get back to
-this particular release. Follow the steps outlined `here <https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository>`__
-to create a release.
+this particular version of the workflow. Follow the steps outlined `here <https://docs.github.com/en/github/administering-a-repository/managing-releases-in-a-repository>`__ to create a release.
 
 Next Steps
 ----------
 
-Now that you have a git repository that includes a Galaxy workflow, and you
-have tested it and are satisfied that it works the next step is to
+Now that you have a git repository that includes a Galaxy workflow, the next step is to
 register it on Dockstore.
 
 If you haven't set up a Dockstore account follow the :doc:`next tutorial <register-on-dockstore/>` to create an
-account on Dockstore and link third party services, which includes GitHub.
+account on Dockstore and link to third party services, which includes GitHub.
 Otherwise follow the instructions for :doc:`workflow registration. <dockstore-workflows>`
 
 See Also

docs/getting-started/github-apps/migrating-workflows-to-github-apps.rst

@@ -3,7 +3,7 @@ Migrating Your Existing Workflows to Use GitHub Apps
 
 Dockstore 1.9.0 provides users with a way to keep their workflows automatically updated (instead of needing to manually refresh) by using GitHub apps.
 Here, we will go over how to migrate your existing Dockstore workflows to use GitHub apps.
-This tutorial assumes that you are are familiar with the  ``/.dockstore.yml`` file by having read our overview of :doc:`GitHub apps <github-apps>`. and the :ref:`Registration With GitHub Apps` section in our workflow registration document.
+This tutorial assumes that you are are familiar with the  ``/.dockstore.yml`` file by having read our overview of :doc:`GitHub apps <github-apps>` and the :ref:`Registration With GitHub Apps` section in our workflow registration document.
 
 GitHub App Installation
 -----------------------
@@ -109,8 +109,8 @@ You should see that the ``Workflow Information`` section looks a bit different.
 
 .. image:: /assets/images/docs/workflow-information-after-migration.png
 
-It now lists the mode as ``DOCKSTORE_YML`` instead of ``FULL`` and information about paths is no longer included.
-You are also no longer able to refresh or restub the workflow any more. Since you can't refresh the entire workflow anymore, **new** versions from GitHub (releases/branches) that you want to add to Dockstore must have a ``DOCKSTORE_YML``.
+It now lists the mode as ``Automatically synced via GitHub App`` instead of ``Full``, and information about paths is no longer included.
+You are also no longer able to refresh or restub the workflow any more. Since you can't refresh the entire workflow anymore, **new** versions from GitHub (releases/branches) that you want to add to Dockstore must have a .dockstore.yml file.
 However, you can still refresh already existing versions/branches on Dockstore that you haven't converted by going to the Versions tab, clicking Actions, and selecting Refresh Version.
 
 

docs/getting-started/intro-to-dockstore-tools-and-workflows.rst

@@ -0,0 +1,98 @@
+Introduction to Dockstore Tools and Workflows
+=============================================
+
+
+Comparison of Tools and Workflows
+---------------------------------
+
+When Dockstore was created, CWL was the first descriptor language we supported. CWL has a very clear distinction between a tool and a workflow.
+However, our definition for each does not completely align with the language's specification.
+Instead, Dockstore tools are more associated with creating/owning Docker images that are used in conjunction with a descriptor language, and
+Dockstore workflows are more closely tied to the descriptor files themselves. While other descriptor languages, like WDL and Nextflow,
+do not have separate concepts for tools and workflows, we still maintain a distinction between a tool and a workflow for WDL.
+
+
+
+
++------------------------+------------------------------------------+-------------------------------------------------+
+| Support                | Tool                                     | Workflow*                                       |
++========================+==========================================+=================================================+
+| CWL                    | - Class: CommandLineTool                 | - Class: Workflow                               |
++------------------------+------------------------------------------+-------------------------------------------------+
+| WDL                    | All must be true:                        | - >1 task                                       |
+|                        |   - A single task with Docker image      | - A workflow section that connects the tasks    |
+|                        |   - A workflow section that runs the task|                                                 |
+|                        |   - An associated Docker image           |                                                 |
++------------------------+------------------------------------------+-------------------------------------------------+
+| Nextflow               | - N/A                                    | - Any valid Nextflow workflow                   |
++------------------------+------------------------------------------+-------------------------------------------------+
+| Galaxy                 | - N/A**                                  | - Any valid Galaxy workflow                     |
++------------------------+------------------------------------------+-------------------------------------------------+
+| Versioning             | - Based off of image's tags              | - Based off of branches/tags from Git repository|
++------------------------+------------------------------------------+-------------------------------------------------+
+
+\* Keep in mind that although workflow descriptor files do not require a Docker container, you can still specify external Docker images
+within the descriptor files. In fact, a Docker image is required to run a workflow on Terra. Workflows registered on Dockstore that have a reference
+to a Docker image specified will still follow versioning from GitHub.
+
+\** There are tools that make up Galaxy workflows from the Galaxy toolbox or ToolShed.
+Dockstore does not support registration of these tools.
+
+
+
+Tools
+-----
+
+Dockstore tool registration is meant for users who have created or have access/permissions to a Docker image registered to one of our supported container registries, and have
+written tool descriptor files (in CWL/WDL) that use it. At a basic level, the Docker image describes the tool environment and the descriptor files describe how the tool is run.
+If you are unfamiliar with Docker or how to write descriptor files, check out the following tutorials:
+
+- :doc:`Docker <getting-started-with-docker>`
+- :doc:`CWL <getting-started-with-cwl>`
+- :doc:`WDL <getting-started-with-wdl>`
+
+Dockstore:
+
+- has varying levels of support for images registered on Quay.io, DockerHub, GitLab, Amazon ECR, GitHub Container Registry, and Seven Bridges
+- supports descriptor files hosted on GitHub, BitBucket, GitLab, or written on Dockstore
+- supports descriptor files written in CWL or WDL
+- offers three different tool registration paths
+
+The most convenient way to register your tool and manage it on Dockstore is to have your image registered on Quay.io, your descriptor files hosted on GitHub, and choose our quick registration path.
+This gives Docktore the ability to automatically recognize the image's tags on Quay, link them back to the appropriate version on GitHub, and create the existing versions for you on Dockstore once you hit "Refresh".
+If your image is registered on one of our other supported registries, you will have to register your tool manually. This means each version you want put on Dockstore must be added manually.
+To learn more about our different registration options, read the following tutorials:
+
+- :doc:`Tools <dockstore-tools>`
+- :doc:`Hosted Tools <hosted-tools-and-workflows>`
+
+.. note::
+  Dockstore tool versions are based on the image's tags, not the tags/branches from the git repository where the descriptor files are hosted.
+
+.. tip::
+  Terra does not support WDL tools. If you are writing a WDL with the intent of it being run in the Terra ecosystem, we recommend writing it as a workflow.
+
+
+Workflows
+---------
+
+Dockstore workflow registration is meant for users who have created or have access to descriptor files (in CWL, WDL, Galaxy, Nextflow). As mentioned above in the Tools section,
+CWL and Galaxy classify tools and workflows differently, so only descriptor files written in a manner that follows a language's respective specification for a workflow will be valid on Dockstore.
+
+Dockstore:
+
+- has varying levels of support for descriptor files registered on GitHub, BitBucket, and GitLab, or written on Dockstore
+- supports descriptor files written in CWL, WDL, Galaxy, and Nextflow
+- offers four different workflow registration paths
+
+The most convenient way to register your workflow is to push your descriptor files to a GitHub repository and choose our GitHub App installation registration path. Choosing this
+option allows Dockstore to automatically create and update versions on Dockstore every time a push is made or tag created. To learn more about this and our other registration options, read the following tutorials:
+
+- :doc:`GitHub Apps </getting-started/github-apps/github-apps-landing-page>`
+- :doc:`Workflows <dockstore-workflows>`
+- :doc:`Hosted Workflows <hosted-tools-and-workflows>`
+
+
+
+
+

docs/index.rst

@@ -26,6 +26,7 @@ going straight to the :doc:`End User Topics <end-user-topics/end-user-topics>` o
    :caption: Getting Started Guide
    :maxdepth: 1
 
+   getting-started/intro-to-dockstore-tools-and-workflows
    getting-started/getting-started
    getting-started/getting-started-with-docker
    getting-started/getting-started-with-cwl