From 1db6cae4e34c77c42fd598f5a018a343841cccbb Mon Sep 17 00:00:00 2001 From: Harvey Date: Wed, 4 Apr 2018 22:18:21 -0400 Subject: [PATCH 1/5] Fix link & wording updates * Repo for Jenkins Pipeline Pluging was renamed, so just update the link * Update some sentence structure for clarity --- docs/BEST_PRACTICES.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md index 61d78f4..52ccdd1 100644 --- a/docs/BEST_PRACTICES.md +++ b/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. From d589ff49c49b1eba820823007ca2f5090cf7529b Mon Sep 17 00:00:00 2001 From: Harvey Date: Wed, 4 Apr 2018 22:18:32 -0400 Subject: [PATCH 2/5] Fix typo --- pipeline-examples/parallel-from-grep/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pipeline-examples/parallel-from-grep/README.md b/pipeline-examples/parallel-from-grep/README.md index 86040f6..6e2572f 100644 --- a/pipeline-examples/parallel-from-grep/README.md +++ b/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. - From 207f43aa0f6cf9ee73222bd057f8593db4774420 Mon Sep 17 00:00:00 2001 From: Harvey Date: Wed, 4 Apr 2018 22:18:55 -0400 Subject: [PATCH 3/5] Update section README It read as though it was an independent repo, so keep it consistent as with the others. --- declarative-examples/README.md | 23 +++-------------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/declarative-examples/README.md b/declarative-examples/README.md index d1e920a..864ccc2 100644 --- a/declarative-examples/README.md +++ b/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. From 70c4da49bf76ad37222c958ebd6cd56c2a5ec1d5 Mon Sep 17 00:00:00 2001 From: Harvey Date: Wed, 4 Apr 2018 22:20:06 -0400 Subject: [PATCH 4/5] Update links * Add declarative-examples to the layout list * Link the folders in the layout list * Fabric8 deprecated a repo; update link --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 531365c..5c5f5e6 100644 --- a/README.md +++ b/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) From 028996b3acffd8472b6102ef745f19208bd987a7 Mon Sep 17 00:00:00 2001 From: Harvey Date: Sun, 8 Apr 2018 20:36:43 -0400 Subject: [PATCH 5/5] Clarify code with backticks --- pipeline-examples/parallel-from-grep/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pipeline-examples/parallel-from-grep/README.md b/pipeline-examples/parallel-from-grep/README.md index 6e2572f..91d90a0 100644 --- a/pipeline-examples/parallel-from-grep/README.md +++ b/pipeline-examples/parallel-from-grep/README.md @@ -14,9 +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" -loops - i.e., "for (String s: strings)" - and instead have to use old -school counter-based for loops. +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.