Merge branch '13430-allow-storage-classes'

[arvados.git] / doc / admin / upgrading.html.textile.liquid

diff --git a/doc/admin/upgrading.html.textile.liquid b/doc/admin/upgrading.html.textile.liquid
index bf8833647f3998b76aafce2bcc8835d1cb8f1d63..7a330a9638a094caee14e4b159bc1caa70598572 100644 (file)
--- a/doc/admin/upgrading.html.textile.liquid
+++ b/doc/admin/upgrading.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: admin
-title: "Upgrading Arvados"
+title: "Upgrading Arvados and Release notes"
 ...
 
 {% comment %}
@@ -34,9 +34,9 @@ h3. 2018-04-05: v1.1.4 regression in arvados-cwl-runner for workflows that rely
 
 h4. Secondary files missing from toplevel workflow inputs
 
-If a workflow input does not declare "secondaryFiles" corresponding to the "secondaryFiles" of workflow steps which use the input, the workflow would inconsistently succeed or fail depending on whether the input values were specified as local files or referenced an existing collection (and whether the existing collection contained the secondary files or not).  To ensure consistent behavior, the workflow is now required to declare in the top level workflow inputs any secondaryFiles that are expected by workflow steps.
+If a workflow input does not declare @secondaryFiles@ corresponding to the @secondaryFiles@ of workflow steps which use the input, the workflow would inconsistently succeed or fail depending on whether the input values were specified as local files or referenced an existing collection (and whether the existing collection contained the secondary files or not).  To ensure consistent behavior, the workflow is now required to declare in the top level workflow inputs any secondaryFiles that are expected by workflow steps.
 
-As an example, the following workflow will fail because the @toplevel_input@ does not declare the secondaryFiles that will be expected by @step_input@:
+As an example, the following workflow will fail because the @toplevel_input@ does not declare the @secondaryFiles@ that are expected by @step_input@:
 
 <pre>
 class: Workflow
@@ -61,16 +61,30 @@ steps:
       baseCommand: echo
 </pre>
 
-To fix this, add the appropriate @secondaryFiles@ section to @toplevel_input@
+When run, this produces an error like this:
 
 <pre>
-class: Workflow
+cwltool ERROR: [step step1] Cannot make job: Missing required secondary file 'hello.txt.idx' from file object: {
+    "basename": "hello.txt",
+    "class": "File",
+    "location": "keep:ade9d0e032044bd7f58daaecc0d06bc6+51/hello.txt",
+    "size": 0,
+    "nameroot": "hello",
+    "nameext": ".txt",
+    "secondaryFiles": []
+}
+</pre>
+
+To fix this error, add the appropriate @secondaryFiles@ section to @toplevel_input@
+
+<notextile>
+<pre><code>class: Workflow
 cwlVersion: v1.0
 inputs:
-  toplevel_input:
+  <span class="userinput">toplevel_input:
     type: File
     secondaryFiles:
-      - .idx
+      - .idx</span>
 outputs: []
 steps:
   step1:
@@ -87,11 +101,12 @@ steps:
             - .idx
       outputs: []
       baseCommand: echo
-</pre>
+</code></pre>
+</notextile>
 
 h4. Secondary files on default file inputs
 
-Due to a bug in Arvados v1.1.4, @File@ inputs that have default values and also expect @secondaryFiles@ and will fail to upload default secondaryFiles.  As an example, the following case will fail:
+Due to a bug in Arvados v1.1.4, @File@ inputs that have default values and also expect @secondaryFiles@ and will fail to upload default @secondaryFiles@.  As an example, the following case will fail:
 
 <pre>
 class: CommandLineTool
@@ -107,24 +122,32 @@ outputs: []
 baseCommand: echo
 </pre>
 
-To fix this, manually upload the primary and secondary files to keep and explicitly declare @secondaryFiles@ on the default primary file:
+When run, this produces an error like this:
 
 <pre>
-class: CommandLineTool
+2018-05-03 10:58:47 cwltool ERROR: Unhandled error, try again with --debug for more information:
+  [Errno 2] File not found: u'hello.txt.idx'
+</pre>
+
+To fix this, manually upload the primary and secondary files to keep and explicitly declare @secondaryFiles@ on the default primary file:
+
+<notextile>
+<pre><code>class: CommandLineTool
 inputs:
   step_input:
     type: File
     secondaryFiles:
       - .idx
-    default:
+    <span class="userinput">default:
       class: File
       location: keep:4d8a70b1e63b2aad6984e40e338e2373+69/hello.txt
       secondaryFiles:
        - class: File
-         location: keep:4d8a70b1e63b2aad6984e40e338e2373+69/hello.txt.idx
+         location: keep:4d8a70b1e63b2aad6984e40e338e2373+69/hello.txt.idx</span>
 outputs: []
 baseCommand: echo
-</pre>
+</code></pre>
+</notextile>
 
 This bug will be fixed in an upcoming release of Arvados.