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) 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. diff --git a/docs/BEST_PRACTICES.md b/docs/BEST_PRACTICES.md index 454356b..fc65cb9 100644 --- a/docs/BEST_PRACTICES.md +++ b/docs/BEST_PRACTICES.md @@ -1,16 +1,14 @@ # 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`). -* 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 valve 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. +* 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. * 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 +17,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. diff --git a/pipeline-examples/parallel-from-grep/README.md b/pipeline-examples/parallel-from-grep/README.md index 86040f6..91d90a0 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 -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. -