README Content Updates

README.md

@@ -4,12 +4,13 @@ This repository is a home for snippets, tips and tricks and examples of scriptin
 
 # Layout
 
-The repository is broken up into four directories currently:
+The repository is broken up into the following directories:
 
-* *pipeline-examples* - for general Pipeline examples.
-* *global-library-examples* - for examples of how to write and use the global library on a Jenkins master.
-* *jenkinsfile-examples* - for examples of using `Jenkinsfile`s checked into repositories.
-* *docs* - for documentation, guides and other non-code content.
+* [pipeline-examples](pipeline-examples) - for general Pipeline examples.
+* [declarative-examples](declarative-examples) - for examples using the Jenkins declarative pipeline syntax.
+* [global-library-examples](global-library-examples) - for examples of how to write and use the global library on a Jenkins master.
+* [jenkinsfile-examples](jenkinsfile-examples) - for examples of using `Jenkinsfile`s checked into repositories.
+* [docs](docs) - for documentation, guides and other non-code content.
 
 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.
 
@@ -24,5 +25,5 @@ We want them!
 # External resources
 
 * [Pipeline scripts collection of the Docker team](https://github.com/docker/jenkins-pipeline-scripts)
-* [Pipeline scripts collection of the Fabric8 team](https://github.com/fabric8io/jenkins-pipeline-library)
+* [Pipeline scripts collection of the Fabric8 team](https://github.com/fabric8io/fabric8-pipeline-library)
 * [Pipeline scripts collection of the Funkwerk](https://github.com/funkwerk/jenkins-workflow)

declarative-examples/README.md

@@ -5,24 +5,7 @@ This folder is a home for snippets, tips and tricks and examples for writing Dec
 
 # Layout
 
-The repository is broken up into two directories currently:
+The folder is broken up into the following sub-folders:
 
-* *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.
-
-
-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
-
-All contributions are under the MIT license, like Jenkins itself.
-
-# Pull requests
-
-We want them!
-
-# External resources
-
-* [Pipeline scripts collection of the Docker team](https://github.com/docker/jenkins-pipeline-scripts)
-* [Pipeline scripts collection of the Fabric8 team](https://github.com/fabric8io/jenkins-pipeline-library)
-* [Pipeline scripts collection of the Funkwerk](https://github.com/funkwerk/jenkins-workflow)
+* [simple-examples](simple-examples) - simple pipelines with one or two stages that illustrate or test a single part of Declarative Pipeline
+* [jenkinsfile-examples](jenkinsfile-examples) - for examples of using `Jenkinsfile`s checked into repositories.

docs/BEST_PRACTICES.md

@@ -1,16 +1,17 @@
 # Introduction
-This is a collection of tips, advice, gotchas and other best practices for using the [Jenkins Pipeline plugin](https://github.com/jenkinsci/workflow-plugin/blob/master/README.md). Contributions and comments are happily accepted.
+This is a collection of tips, advice, gotchas and other best practices for using the [Jenkins Pipeline plugin](https://github.com/jenkinsci/pipeline-plugin). Contributions and comments are happily accepted.
 
 # General tips and advice
 * Do everything that makes sense there within `stage`s. This will make your builds easier to visualize, debug, etc.
 * Do all real work that involves running a shell script, building, etc, within `node` blocks, so that it actually happens on a real executor, rather than a flyweight executor on the master node.
 * Get your flows from source control - `Jenkinsfile`s, loading libraries, global [CPS](https://en.wikipedia.org/wiki/Continuation-passing_style) library, you name it - but if you pull the main flow from SCM (i.e., Multibranch with `Jenkinsfile`s or `Pipeline from SCM`), be aware that you may need to whitelist a lot of method calls in the script security plugin. By getting your flows from source control, you benefit from `Jenkinsfile` versioning and also testing and merging against your CD Pipeline definition.
-* `input` shouldn’t be done within a `node` block. For `input` step is recommended to use `timeout` in order to avoid waiting for an infinite amount of time, and also control structures (`try/catch/finally`).
+* `input` shouldn’t be done within a `node` block.
+* For an `input` step, it is recommended to use `timeout` in order to avoid waiting for an infinite amount of time, and also the use of control structures (`try/catch/finally`).
 * As Pipeline usage is adopted for multiple projects and teams in an organization, common patterns should be stored in [Shared Libraries](https://jenkins.io/doc/book/pipeline/shared-libraries/). It is also an escape value for allowing out-of-sandbox execution in a safe context.
-* When writing functions, use unique names in your pipeline script and avoid using built-in/pre-defined items (such as "build", "stage", etc).  Using pre-defined methods may result in runtime issues, such as generating a `sandbox.RejectedAccessException` error when using build job DSL. 
+* When writing functions, use unique names in your pipeline script and avoid using built-in/pre-defined items (such as "build", "stage", etc).  Using pre-defined methods may result in runtime issues, such as generating a `sandbox.RejectedAccessException` error when using build job DSL.
 * Make use of the available [Pipeline Development Tools](https://jenkins.io/doc/book/pipeline/development/#pipeline-development-tools) for debugging your Pipeline as code.
 * Use [Multibranch Pipeline](https://jenkins.io/doc/book/pipeline/multibranch/) for project collaboration, new features (developed in separate branches) are validated before merging them to the master branch. Besides, it comes with automating features out-of-the-box (webhooks).
- 
+
 # Parallelism
 * Within `parallel` blocks, use `node` blocks to make sure you farm out to real nodes for your parallelized work.
 * Nested `parallel` blocks can lead to swamping your available executors, as each execution of the first `parallel` block calls multiple executions of the second `parallel` block, and so on. In general, think carefully about your parallelism and your available executors when using `parallel`.
@@ -19,7 +20,7 @@ This is a collection of tips, advice, gotchas and other best practices for using
 
 # `Jenkinsfile`s and Multibranch
 * Use `checkout scm` to automatically checkout current revision of branch
-* Use `$env.BRANCH_NAME` variable if you have logical difference in your flow between branches, i.e. to distinguish different behavior for production-ready branches versus sandbox or pull request branches.
+* Use `$env.BRANCH_NAME` variable if you have logical differences in your flow between branches, i.e. to distinguish different behavior for production-ready branches versus sandbox or pull request branches.
 * For `Jenkinsfile`s, make sure to put `#!/usr/bin/env groovy` at the top of the file so that IDEs, GitHub diffs, etc properly detect the language and do syntax highlighting for you.
  * But note that this doesn't mean you can run "groovy Jenkinsfile" or "./Jenkinsfile" - Pipeline doesn't run standalone! This is just a trick to help in your IDE, etc.
 

pipeline-examples/parallel-from-grep/README.md

@@ -5,7 +5,7 @@ triggering all of them in parallel.
 
 # Caveats
 
-* Calling other jobs is not the most idiomatic way to use the Worflow DSL, 
+* Calling other jobs is not the most idiomatic way to use the Workflow DSL,
 however, the chance of re-using existing jobs is always welcome under certain
 circumstances.
 
@@ -14,10 +14,9 @@ circumstances.
 it's not really possible to use Groovy closures or syntax that depends
 on closures, so you can't do the Groovy standard of using
 .collectEntries on a list and generating the steps as values for the
-resulting entries. You also can't use the standard Java syntax for For
+resulting entries. You also can't use the standard Java syntax for "for"
 loops - i.e., "for (String s: strings)" - and instead have to use old
 school counter-based for loops.
 * There is no need for the generation of the step itself to be in a
 separate method. I've opted to do so here to show how to return a step
 closure from a method.
-