Merge pull request #465 from rtyler/pipeline-chapter-250

Update and add onto the Pipeline Handbook chapter

STYLEGUIDE.adoc

@@ -10,9 +10,25 @@ CAUTION: This document is still a work in progress.
 * Master
 * Node
 * Pipeline
+* Executor
 
 Mixing of these terms is incorrect
 
+NOTE: When referring to a Jenkins Pipeline via short-hand ("Pipeline"), it
+should always be title-cased. When referring to a conceptual pipeline
+("continuous delivery pipeline"), it it should always be lower-cased.
+
+
+When needing to refer to the collection of executors and/or nodes it is best to
+refer to them collectively as "the Jenkins environment", for example:
+
+____
+[..] they will now execute in parallel assuming the requisite capacity exists
+in the Jenkins environment.
+____
+
+As opposed to "the Jenkins cluster", "agent pool" or any other phrase to
+describe the collective set of resources provided by Jenkins.
 
 == Syntax/Formatting
 
@@ -110,6 +126,15 @@ By default, all of these use the class name as label, but that can be customized
 javadoc:hudson.scm.SCM#all()[a list of all known SCM implementations]
 ----
 
+== Handbook Style Guide
+
+* For consecutive sections that are related to or build on each other, there
+  should be a reasonable "intro" or preamble at the beginning of one section
+  and a reasonable "outtro" at the end, to provide continuity between the
+  documents
+
+
+
 == Assorted comments
 
 * Prefer "for example" over "e.g." which can be more clear to non-native english

content/_layouts/chapter.html.haml

@@ -34,20 +34,26 @@ layout: default
         %a.next.page-link{:href =>  File.join('..', next_chapter.key)}
           #{next_chapter.title} ⇒
 
+
+
     .section
       %h1
         = page.title
 
-      = content
       - if chapter.sections && chapter.sections.size > 0
-        %h2
-          Sub-sections
-
-        %ul
-          - chapter.sections.each do |section|
-            %li
-              %a{:href => section.key}
-                = section.title
+        #subsections
+          .toc
+            #toc-title
+              Chapter Sub-Sections
+            %ul
+              - chapter.sections.each do |section|
+                %li
+                  %a{:href => section.key}
+                    = section.title
+
+
+      = content
+
 
     .section_nav.pagination-links
       - if previous_chapter

content/css/jenkins.css

@@ -1345,8 +1345,10 @@ blockquote {
     background-color: #f9f9f9;
     border-left: 1px solid #c9c9c9;
     float: right;
+    width: 10rem;
     margin-left: 15px;
     padding: 10px;
+    clear: right;
 }
 
 .toc li li {

content/doc/book/book.yml

@@ -9,3 +9,4 @@ chapters:
   - operating
   - scaling
   - appendix
+  - glossary

content/doc/book/glossary/chapter.yml

@@ -0,0 +1,2 @@
+---
+sections:

content/doc/book/glossary/index.adoc

@@ -0,0 +1,19 @@
+---
+layout: chapter
+---
+:description:
+:author:
+:email: [email protected]
+:sectanchors:
+:toc: left
+:notitle:
+
+[glossary]
+= Glossary
+
+
+[glossary]
+
+Freestyle Job::
+    A Freestyle Job
+

content/doc/book/pipeline/chapter.yml

@@ -1,4 +1,6 @@
 ---
 sections:
-  - overview
+  - getting-started
   - jenkinsfile
+  - multibranch
+  - shared-libraries

content/doc/book/pipeline/getting-started.adoc

@@ -0,0 +1,231 @@
+---
+layout: section
+---
+:notitle:
+:description:
+:author:
+:email: [email protected]
+:sectanchors:
+:toc:
+:imagesdir: /doc/book/resources/pipeline
+:hide-uri-scheme:
+
+= Getting Started
+
+Jenkins Pipeline is a suite of plugins which supports implementing and
+integrating continuous delivery pipelines into Jenkins. Pipeline provides an
+extensible set of tools for modeling simple-to-complex delivery pipelines "as
+code" via the Pipeline DSL.
+footnoteref:[dsl,link:https://en.wikipedia.org/wiki/Domain-specific_language[Domain-Specific Language]]
+
+This section will introduce some of the key concepts to Jenkins Pipeline and
+help introduce the basics of defining and working with Pipelines inside of a
+running Jenkins instance.
+
+== Prerequisites
+
+To use Jenkins Pipeline, you will need:
+
+* Jenkins 2.x or later (older versions back to 1.642.3 may work but are not
+  recommended)
+* Pipeline plugin
+footnoteref:[pipeline, link:https://plugins.jenkins.io/workflow-aggregator[Pipeline plugin]]
+
+To learn how to install and manage plugins, consult <<../managing/plugins#, Managing Plugins>>.
+
+== Defining a Pipeline
+
+Pipeline Script is written in
+link:http://groovy-lang.org/[Groovy].
+The relevant bits of
+link:http://groovy-lang.org/semantics.html[Groovy syntax]
+will be introduced as necessary in this document, so while an understanding of
+Groovy is helpful, it is not required to use Pipeline Script.
+
+A basic Pipeline can be created in either of the following ways:
+
+* By entering a script directly in the Jenkins web UI.
+* By creating a `Jenkinsfile` which can be checked into a project's source
+  control repository.
+
+The syntax for defining a Pipeline with either approach is the same, but while
+Jenkins supports entering Pipeline Script directly into the web UI, it's
+generally considered best practice to define the Pipeline in a `Jenkinsfile`
+which Jenkins will then load directly from source control.
+footnoteref:[scm, https://en.wikipedia.org/wiki/Source_control_management]
+
+
+=== Defining a Pipeline in the Web UI
+
+To create a basic Pipeline in the Jenkins web UI, follow these steps:
+
+* Click *New Item* on Jenkins home page.
+
+image::new-item-selection.png["Click *New Item* on the Jenkins home page", role=center]
+
+* Enter a name for your Pipeline, select *Pipeline* and click *OK*.
+
+[CAUTION]
+====
+Jenkins uses the name of the Pipeline to create directories on disk. Pipeline
+names which include spaces may uncover bugs in scripts which do not expect
+paths to contain spaces.
+====
+
+image::new-item-creation.png["Enter a name, select *Pipeline*, and click *OK*", role=center]
+
+
+
+* In the *Script* text-area, enter a Pipeline script and click *Save*.
+
+image::hello-world-script.png["In the *Script* text-area, enter a Pipeline script and click Save", role=center]
+
+* Click *Build Now* to run the Pipeline.
+
+image::build-now.png["Click *Build Now* to run the Pipeline", role=center]
+
+
+* Click *#1* under "Build History" and then click *Console Output* to see the
+  full output from the Pipeline.
+
+image::hello-world-console-output.png["Click *Console Output* for the Pipeline", role=center]
+
+The example above shows a successful run of a basic Pipeline created in the Jenkins
+web UI, using two valuable steps.
+
+[pipeline]
+----
+// Script //
+node { // <1>
+    echo 'Hello World' // <2>
+}
+// Declarative not yet implemented //
+----
+<1> `node` allocates an executor and workspace in the Jenkins environment.
+<2> `echo` writes simple string in the Console Output.
+
+
+// Despite :sectanchors:, explicitly defining an anchor because it will be
+// referenced from other documents
+[[defining-a-pipeline-in-scm]]
+=== Defining a Pipeline in SCM
+
+Complex pipelines would be cumbersome to write and maintain if you could only do
+that in the text area provided by the Jenkins job configuration page.
+
+Accordingly, you also have the option of writing Pipeline scripts
+(Jenkinsfiles) with a text editor and then loading those scripts into Jenkins
+using the *Pipeline Script from SCM* option.
+
+Loading pipeline scripts using the `checkout scm` step leverages the
+idea of "Pipeline as code" and allows easy maintenance of Pipelines with source
+control and text-editors.
+
+To do this, select *Pipeline script from SCM* when defining the pipeline.
+
+With the *Pipeline script from SCM* option selected, you do not enter any Groovy
+code in the Jenkins UI; you just indicate by specifying a path where in source
+code you want to retrieve the pipeline from. When you update the designated
+repository, a new build is triggered, as long as your job is configured with an
+SCM polling trigger.
+
+[TIP]
+====
+The first line of a `Jenkinsfile` should be `#!groovy`
+footnoteref:[shebang, https://en.wikipedia.org/wiki/Shebang_(Unix)]
+which text editors, IDEs, GitHub, etc will use to syntax highlight the
+`Jenkinsfile` properly as Groovy code.
+====
+
+
+== Built-in Documentation
+
+Pipeline ships with built-in documentation features to make it
+easier to create Pipelines of varying complexities. This built-in documentation
+is automatically generated and updated based on the plugins installed in the
+Jenkins instance.
+
+The built-in documentation can be found globally at:
+link:http://localhost:8080[localhost:8080/pipeline-syntax/],
+assuming you have a Jenkins instance running on localhost port 8080. The same
+documentation is also linked as *Pipeline Syntax* in the side-bar for any
+configured Pipeline project.
+
+image::pipeline-syntax-sidebar.png[Pipeline Syntax in the side-bar, role=center]
+
+[[snippet-generator]]
+=== Snippet Generator
+
+The built-in "Snippet Generator" utility is helpful for creating bits of
+code for individual steps, discovering new steps provided by plugins, or
+experimenting with different parameters for a particular step.
+
+The Snippet Generator is dynamically populated with a list of the steps
+available to the Jenkins instance. The number of steps available is dependent
+on the plugins installed which explicitly expose steps for use in Pipeline.
+
+To generate a step snippet with the Snippet Generator:
+
+. Navigate to the Snippet Generator
+. Select the desired step in the *Sample Step* dropdown menu
+. Use the dynamically populated area below the *Sample Step* dropdown to configure the selected step.
+. Click *Generate Pipeline Script* to create a snippet of Pipeline which can be
+copied and pasted into a Pipeline.
+
+image::snippet-generator.png[Snippet Generator, role=center]
+
+To access additional information and/or documentation about the step selected,
+click on the help icon (blue question mark).
+
+=== Global Variable Reference
+
+In addition to the Snippet Generator, which only surfaces steps, Pipeline also
+provides a built-in "*Global Variable Reference*." Like the Snippet Generator,
+it is also dynamically populated by plugins. Unlike the Snippet Generator
+however, the Global Variable Reference only contains documentation for
+*variables*, provided by Pipeline or plugins, which are available for
+Pipelines.
+
+The variables provided by default in Pipeline are:
+
+env::
+
+Environment variables accessible from Pipeline Script, for example:
+`env.PATH` or `env.BUILD_ID`. Consult the built-in 
+link:http://localhost:8080/pipeline-syntax/globals#env[Global Variable Reference]
+for a complete, and up to date, list of environment variables
+available in Pipeline.
+
+params::
+
+Exposes all parameters defined for the Pipeline as a read-only
+link:http://groovy-lang.org/syntax.html#_maps[Map],
+for example: `params.MY_PARAM_NAME`.
+
+currentBuild::
+
+May be used to discover information about the currently executing Pipeline,
+with properties such as `currentBuild.result`, `currentBuild.displayName`,
+etc. Consult the built-in
+link:http://localhost:8080/pipeline-syntax/globals#currentBuild[Global Variable Reference]
+for a complete, and up to date, list of properties available on `currentBuild`.
+
+
+== Further Reading
+
+This section merely scratches the surface of what can be done with Jenkins
+Pipeline, but should provide enough of a foundation for you to start
+experimenting with a test Jenkins instance.
+
+In the next section, <<jenkinsfile#, The Jenkinsfile>>, more Pipeline steps
+will be discussed along with patterns for implementing successful, real-world,
+Jenkins Pipelines.
+
+
+=== Additional Resources
+
+* link:https://jenkins.io/doc/pipeline/steps[Pipeline Steps Reference],
+  encompassing all steps provided by plugins distributed in the Jenkins Update
+  Center.
+* link:https://jenkins.io/doc/pipeline/examples[Pipeline Examples], a
+  community-curated collection of copyable Pipeline examples.