Adding changes based on review from Daniel Beck.

Patrick Wolf · Patrick Wolf · commit ed426666e160 · 2017-08-16T12:03:51.000-07:00
diff --git a/declarative-examples/README.md b/declarative-examples/README.md
@@ -1,17 +1,17 @@
-# Declarartive Examples
+# Declarative Examples
 
 This folder is a home for snippets, tips and tricks and examples for writing Declarative Pipelines with the
 [Jenkins Pipeline plugin](https://github.com/jenkinsci/workflow-plugin/blob/master/README.md).
 
 # Layout
 
-The repository is broken up into four directories currently:
+The repository is broken up into two directories currently:
 
 * *simple-examples* - simple pipelines with one or two stages that illustrate or test a single part of Declarative Pipeline
 * *jenkinsfile-examples* - for examples of using `Jenkinsfile`s checked into repositories.
 
 
-Please put your script into its own directory under the appropriate directory above, with a README.md file included explaining what your script does or shows. Make sure your script is commented so that others can understand how it works, why it works, etc.
+When contributing new examples please put them into the appropriate directory above. Make sure your script is commented so that others can understand how it works, why it works, etc.
 
 # License
 
diff --git a/declarative-examples/jenkinsfile-examples/mavenDocker.groovy b/declarative-examples/jenkinsfile-examples/mavenDocker.groovy
@@ -1,6 +1,9 @@
 pipeline {
 
-  //Run everything on an agent that has docker daemon and git installed
+  /*
+   * Run everything on an existing agent configured with a label 'docker'.
+   * This agent will need docker, git and a jdk installed at a minimum.
+   */
   agent {
     node {
       label 'docker'
diff --git a/declarative-examples/simple-examples/credentialsMixedEnvironment.groovy b/declarative-examples/simple-examples/credentialsMixedEnvironment.groovy
@@ -2,10 +2,13 @@ pipeline {
   environment {
     // environment variables and credential retrieval can be interspersed
     SOME_VAR = "SOME VALUE"
+    // this assumes that "cred1" has been created on Jenkins Credentials
     CRED1 = credentials("cred1")
     INBETWEEN = "Something in between"
+    // this assumes that "cred2" has been created in Jenkins Credentials
     CRED2 = credentials("cred2")
-    OTHER_VAR = "OTHER VALUE"
+    // Env variables can refer to other variables as well
+    OTHER_VAR = "${SOME_VAR}"
   }
 
   agent any
diff --git a/declarative-examples/simple-examples/environmentNonLiteral.groovy b/declarative-examples/simple-examples/environmentNonLiteral.groovy
@@ -1,14 +1,17 @@
 pipeline {
   /*
    * The environment section is used for setting environment variables and will allow for
-   * expanding variable and other methods to set those values as long as the return type is a String
+   * expanding variable and other methods to set those values as long as the return type is a String.
+   * String escaping in Groovy can affect the behavior here. Please refer here for detailed explainations
+   * http://docs.groovy-lang.org/latest/html/documentation/#all-strings
+   * The 'readMavenPom()' method is provided by the Pipeline Utility Steps plugin
    */
   environment {
     FOO = "BAR"
     BUILD_NUM_ENV = currentBuild.getNumber()
     ANOTHER_ENV = "${currentBuild.getNumber()}"
     INHERITED_ENV = "\${BUILD_NUM_ENV} is inherited"
-    ACME_FUNC = returnAThing("banana")
+    ACME_FUNC = readMavenPom().getArtifactId()
   }
 
   agent any
@@ -17,10 +20,20 @@ pipeline {
     stage("Environment") {
       steps {
         sh 'echo "FOO is $FOO"'
+        // returns 'FOO is BAR'
+
         sh 'echo "BUILD_NUM_ENV is $BUILD_NUM_ENV"'
+        // returns 'BUILD_NUM_ENV is 4' depending on the build number
+
         sh 'echo "ANOTHER_ENV is $ANOTHER_ENV"'
+        // returns 'ANOTHER_ENV is 4' like the previous depending on the build number
+
         sh 'echo "INHERITED_ENV is $INHERITED_ENV"'
+        // returns 'INHERITED_ENV is ${BUILD_NUM_ENV} is inherited'
+        // The \ escapes the $ so the variable is not expanded but becomes a literal
+
         sh 'echo "ACME_FUNC is $ACME_FUNC"'
+        // returns 'ACME_FUNC is spring-petclinic' or the name of the artifact in the pom.xml
       }
     }
   }
diff --git a/declarative-examples/simple-examples/legacyMetaStepSyntax.groovy b/declarative-examples/simple-examples/legacyMetaStepSyntax.groovy
@@ -11,7 +11,10 @@ pipeline {
          * This syntax works fine in Declarative
          */
         step([$class: 'ArtifactArchiver', artifacts: 'msg.out', fingerprint: true])
-        sh('echo ONSLAVE=$ONSLAVE')
+
+        // Parenthesis are optional when a single parameter is used
+        sh('echo $PATH')
+        sh 'echo $PATH'
       }
     }
   }
diff --git a/declarative-examples/simple-examples/postConditionOrder.groovy b/declarative-examples/simple-examples/postConditionOrder.groovy
@@ -10,19 +10,30 @@ pipeline {
         }
     }
     post {
-    // these steps will run at the end of the pipeline based on the condition.
-    // The conditions run in this order regardless of their arrangement
+    /*
+     * These steps will run at the end of the pipeline based on the condition.
+     * Post conditions run in order regardless of their place in pipeline
+     * 1. always - always run
+     * 2. changed - run if something changed from last run
+     * 3. aborted, success, unstable or failure - depending on status
+     */
         always {
             echo "I AM ALWAYS first"
         }
         changed {
             echo "CHANGED is run second"
         }
+        aborted {
+          echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED are exclusive of each other"
+        }
         success {
-            echo "SUCCESS or FAILURE run third"
+            echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"
+        }
+        unstable {
+          echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"
         }
         failure {
-            echo "SUCCESS or FAILURE run third"
+            echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"
         }
     }
 }
diff --git a/declarative-examples/simple-examples/stepsAndWrappers.groovy b/declarative-examples/simple-examples/stepsAndWrappers.groovy
diff --git a/declarative-examples/simple-examples/toolsBuildPluginParentPOM.groovy b/declarative-examples/simple-examples/toolsBuildPluginParentPOM.groovy
@@ -1,5 +1,5 @@
 pipeline {
-  // use the 'tools' section to use specific tool versions already defined in Jenkins config and installed on Agent
+  // use the 'tools' section to use specific tool versions already defined in Jenkins config 
   tools {
     maven "apache-maven-3.1.0"
     jdk "default"
diff --git a/declarative-examples/simple-examples/toolsInStage.groovy b/declarative-examples/simple-examples/toolsInStage.groovy
@@ -1,8 +1,17 @@
 pipeline {
-  agent any
+  agent none
   stages {
     stage("foo") {
-      // Tools configured in Jenkins can be included at the Pipeline level or at the Stage Level.
+
+      agent any
+
+      /*
+       * Tools configured in Jenkins can be included at the Pipeline level or at the Stage Level.
+       * This allows you to use different tools on different agents.
+       * In this case the pipeline does not have a agent assigned, 'agent none', but
+       * the stage does have an agent, 'agent any'. If I use a different agent in a
+       * subsequent stage I can use a different version of the tool or different tools.
+       */
       tools {
         maven "apache-maven-3.0.1"
       }
diff --git a/declarative-examples/simple-examples/whenEnvFalse.groovy b/declarative-examples/simple-examples/whenEnvFalse.groovy
diff --git a/declarative-examples/simple-examples/whenEnvTrue.groovy b/declarative-examples/simple-examples/whenEnvTrue.groovy
diff --git a/declarative-examples/simple-examples/whenEnvVarCondition.groovy b/declarative-examples/simple-examples/whenEnvVarCondition.groovy
@@ -0,0 +1,25 @@
+pipeline {
+  agent any
+
+  environment {
+      // This returns 0 or 1 depending on whether build number is even or odd
+      FOO = "${currentBuild.getNumber() % 2}"
+  }
+
+  stages {
+    stage("Hello") {
+      steps {
+        echo "Hello"
+      }
+    }
+    stage("Evaluate FOO") {
+      when {
+        // stage won't be skipped as long as FOO == 0, build number is even
+        environment name: "FOO", value: "0"
+      }
+      steps {
+        echo "World"
+      }
+    }
+  }
+}
diff --git a/declarative-examples/simple-examples/whenExpressionSkip.groovy b/declarative-examples/simple-examples/whenExpressionSkip.groovy
@@ -8,15 +8,14 @@ pipeline {
     }
     stage("Always Skip") {
       when {
-        // skip this stage unless the "expression evaluates to 'true'
+        // skip this stage unless the expression evaluates to 'true'
         expression {
           echo "Should I run?"
           return false
         }
       }
       steps {
         echo "World"
-        echo "Heal it"
       }
     }
   }
diff --git a/declarative-examples/simple-examples/whenLaterStages.groovy b/declarative-examples/simple-examples/whenLaterStages.groovy
@@ -10,31 +10,18 @@ pipeline {
     stage("Two") {
       when {
         expression {
-          // "expression can be any Groovy expression"
-          echo "Should I run?"
+          // "expression" can be any Groovy expression
           return false
         }
       }
       steps {
         echo "World"
-        echo "Heal it"
       }
     }
     stage("Three") {
-      when {
-        expression {
-          echo "I always run"
-          return true
-        }
-      }
-      steps {
-        echo "I'm running anyway"
-      }
-    }
-    stage("Four") {
-      // This will show what a skipped stage looks like in Blue Ocean
+      // This will show what a skipped stage followed by an unskipped stage looks like in Blue Ocean
       steps {
-        echo "And I run last of all"
+        echo "Other World"
       }
     }
   }

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,10 @@ pipeline {`
`11`	`11`	`* This syntax works fine in Declarative`
`12`	`12`	`*/`
`13`	`13`	`step([$class: 'ArtifactArchiver', artifacts: 'msg.out', fingerprint: true])`
`14`		`- sh('echo ONSLAVE=$ONSLAVE')`
	`14`	`+`
	`15`	`+ // Parenthesis are optional when a single parameter is used`
	`16`	`+ sh('echo $PATH')`
	`17`	`+ sh 'echo $PATH'`
`15`	`18`	`}`
`16`	`19`	`}`
`17`	`20`	`}`
Original file line number	Diff line number	Diff line change
`@@ -10,19 +10,30 @@ pipeline {`
`10`	`10`	`}`
`11`	`11`	`}`
`12`	`12`	`post {`
`13`		`- // these steps will run at the end of the pipeline based on the condition.`
`14`		`- // The conditions run in this order regardless of their arrangement`
	`13`	`+ /*`
	`14`	`+ * These steps will run at the end of the pipeline based on the condition.`
	`15`	`+ * Post conditions run in order regardless of their place in pipeline`
	`16`	`+ * 1. always - always run`
	`17`	`+ * 2. changed - run if something changed from last run`
	`18`	`+ * 3. aborted, success, unstable or failure - depending on status`
	`19`	`+ */`
`15`	`20`	`always {`
`16`	`21`	`echo "I AM ALWAYS first"`
`17`	`22`	`}`
`18`	`23`	`changed {`
`19`	`24`	`echo "CHANGED is run second"`
`20`	`25`	`}`
	`26`	`+ aborted {`
	`27`	`+ echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED are exclusive of each other"`
	`28`	`+ }`
`21`	`29`	`success {`
`22`		`- echo "SUCCESS or FAILURE run third"`
	`30`	`+ echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"`
	`31`	`+ }`
	`32`	`+ unstable {`
	`33`	`+ echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"`
`23`	`34`	`}`
`24`	`35`	`failure {`
`25`		`- echo "SUCCESS or FAILURE run third"`
	`36`	`+ echo "SUCCESS, FAILURE, UNSTABLE, or ABORTED runs last"`
`26`	`37`	`}`
`27`	`38`	`}`
`28`	`39`	`}`