From dbcdbd6c957b021790261ebd28fe6f66c8d5301e Mon Sep 17 00:00:00 2001 From: Jesse Glick Date: Sat, 30 Jan 2021 14:18:08 -0500 Subject: [PATCH] Various text edits for docs --- README.md | 18 +++++++------- src/main/resources/index.jelly | 2 +- .../Base64FileParameterDefinition/help.html | 24 ++++++++++++++++--- .../help-allowNoFile.html | 3 ++- .../FileParameterWrapper/help.html | 6 ++--- .../StashedFileParameterDefinition/help.html | 16 +++++++------ 6 files changed, 45 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 5c9d8a4..25358f9 100644 --- a/README.md +++ b/README.md @@ -12,25 +12,25 @@ Offers alternative types of file parameter that are compatible with Pipeline and See [JENKINS-27413](https://issues.jenkins-ci.org/browse/JENKINS-27413) and [JENKINS-29289](https://issues.jenkins-ci.org/browse/JENKINS-29289) for background. -## Usage in declarative pipeline +## Usage in Declarative Pipeline -You can now declare file parameters as is in declarative pipeline: +You can now declare and use file parameters via Declarative Pipeline syntax: ```groovy pipeline { agent any parameters { - base64File(name: 'FILE') - stashedFile(name: 'FILE-STASH') + base64File(name: 'small') + stashedFile(name: 'large') } stages { stage('Example') { steps { - withFileParameter(name:'FILE', allowNoFile: true) { - sh 'cat $FILE' + withFileParameter(name: 'small') { + sh 'cat $small' } - unstash 'FILE-STASH' - echo(/loaded '${readFile('FILE-STASH')}'/) + unstash 'large' + sh 'cat large' } } } @@ -84,7 +84,7 @@ pipeline { - [ ] design - [ ] manual test - [ ] automated test -- [ ] tests using Declarative syntax +- [X] tests using Declarative syntax - [ ] tests using `build-token-root` ## Getting started diff --git a/src/main/resources/index.jelly b/src/main/resources/index.jelly index 35f37a7..f3416ce 100644 --- a/src/main/resources/index.jelly +++ b/src/main/resources/index.jelly @@ -1,4 +1,4 @@
- TODO + Provides an alternative set of file parameters that work with Pipeline, unlike the type built into Jenkins core.
diff --git a/src/main/resources/io/jenkins/plugins/file_parameters/Base64FileParameterDefinition/help.html b/src/main/resources/io/jenkins/plugins/file_parameters/Base64FileParameterDefinition/help.html index 6dfe84a..823f65c 100644 --- a/src/main/resources/io/jenkins/plugins/file_parameters/Base64FileParameterDefinition/help.html +++ b/src/main/resources/io/jenkins/plugins/file_parameters/Base64FileParameterDefinition/help.html @@ -1,3 +1,21 @@ -
-

File parameter compatible with Pipeline, must be used with small files

-
+

+ Simple file parameter compatible with Pipeline. + Transmits file contents as an environment variable in Base64 encoding, + so it is best used with fairly small files. + Example usage from Declarative Pipeline: +

+
+pipeline {
+  agent any
+  parameters {
+    base64File(name: 'FILE')
+  }
+  stages {
+    stage('Example') {
+      steps {
+        sh 'echo $FILE | base64 -d > config.yaml'
+      }
+    }
+  }
+}
+
diff --git a/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help-allowNoFile.html b/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help-allowNoFile.html index 9070737..b3f8654 100644 --- a/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help-allowNoFile.html +++ b/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help-allowNoFile.html @@ -1,3 +1,4 @@
- Per default, there will be an error if there is no parameter. You can avoid failure by allowing no file. + By default, an error will be thrown if there is no file uploaded to the build. + With this option, the build will proceed, and the environment variable will simply not be defined.
diff --git a/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help.html b/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help.html index d574c5b..435e20c 100644 --- a/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help.html +++ b/src/main/resources/io/jenkins/plugins/file_parameters/FileParameterWrapper/help.html @@ -23,8 +23,8 @@
- Per default, there will be an error if there is no parameter for the build but you can ignore this error using the - parameter attribute allowNoFile. In this case your pipeline must take into account the file doesn't exists + By default, there will be an error if there is no parameter for the build but you can ignore this error using the + parameter attribute allowNoFile. In this case your Pipeline must take into account the possibility that the file does not exist: 
 pipeline {
   agent any
@@ -35,7 +35,7 @@
     stage('Example') {
       steps {
         withFileParameter(name:'THEFILE', allowNoFile: true) {
-          echo(/loaded '${readFile(THEFILE)}' from $THEFILE/)
+          sh 'if [ -f "$THEFILE" ]; then cat $THEFILE; fi'
         }
       }
     }
diff --git a/src/main/resources/io/jenkins/plugins/file_parameters/StashedFileParameterDefinition/help.html b/src/main/resources/io/jenkins/plugins/file_parameters/StashedFileParameterDefinition/help.html
index 2230c07..5c9f84b 100644
--- a/src/main/resources/io/jenkins/plugins/file_parameters/StashedFileParameterDefinition/help.html
+++ b/src/main/resources/io/jenkins/plugins/file_parameters/StashedFileParameterDefinition/help.html
@@ -1,19 +1,21 @@
-

-  
File parameter compatible with Pipeline but this one stash the file and must be used to handle bug files, how to use it in a declarative pipeline:

-  
+

+    File parameter compatible with Pipeline but using the stash system, better suited to large files.
+    The file will be saved to a stash named like the parameter containing one entry, also named like the parameter.
+    Example usage from Declarative Pipeline:
+

+
 pipeline {
   agent any
   parameters {
-    stashedFile(name: 'FILE-STASH')
+    stashedFile(name: 'assets.zip')
   }
   stages {
     stage('Example') {
       steps {
-        unstash "FILE-STASH"
-        sh 'cat FILE-STASH'
+        unstash 'assets.zip'
+        sh 'unzip assets.zip'
       }
     }
   }
 }
  

-