Merge branch 'main' of https://github.com/jenkinsci/templating-engine…

…-plugin
jenkinsci · Oct 18, 2023 · d93ac56 · d93ac56
2 parents f73cae4 + f26dded
commit d93ac56
Show file tree

Hide file tree

Showing 73 changed files with 2,631 additions and 226 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -11,7 +11,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-java@v1
         with:
-          java-version: 8
+          java-version: 11
       - uses: eskatos/gradle-command-action@v1
         with:
           arguments: --no-daemon spotlessCheck
@@ -22,7 +22,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-java@v1
         with:
-          java-version: 8
+          java-version: 11
       - uses: eskatos/gradle-command-action@v1
         with:
           arguments: --no-daemon codenarc
@@ -58,7 +58,7 @@ jobs:
     - uses: actions/checkout@v2
     - uses: actions/setup-java@v1
       with:
-        java-version: 8
+        java-version: 11
     - uses: eskatos/gradle-command-action@v1
       with:
         arguments: --no-daemon test jacocoTestReport
@@ -74,7 +74,7 @@ jobs:
     - uses: actions/checkout@v2
     - uses: actions/setup-java@v1
       with:
-        java-version: 8
+        java-version: 11
     - uses: eskatos/gradle-command-action@v1
       with:
         arguments: --no-daemon jpi

diff --git a/Justfile b/Justfile
@@ -47,13 +47,13 @@ docs: buildDocsImage
 serve: buildDocsImage
   docker run --rm -p 8000:8000 -v $(pwd):/docs {{docsImage}} serve -a 0.0.0.0:8000
 
-lint-docs: lint-prose lint-markdown
+lint-docs: lint-markdown lint-prose 
 
 # use Vale to lint the prose of the documentation
-lint-prose:
-  docker run -v $(pwd):/app -w /app jdkato/vale:v2.18.0 docs
+lint-prose docsToLint="docs":
+  docker run -v $(pwd):/app -w /app jdkato/vale:v2.18.0 {{docsToLint}}
 
-# use markdownlit to lint the docs
+# use markdownlint to lint the docs
 lint-markdown: 
   docker run -v $(pwd):/app -w /app davidanson/markdownlint-cli2:0.4.0
 

diff --git a/README.md b/README.md
@@ -31,14 +31,15 @@
 
   </td>
   </tr>
+
 </table>
 
 ## Overview
 
 The Jenkins Templating Engine (JTE) is a plugin originally created by [Booz Allen Hamilton](https://www.boozallen.com/) enabling pipeline templating and governance.
 
 JTE brings the [Template Method Design Pattern](https://refactoring.guru/design-patterns/template-method) to Jenkins pipelines.
-Users can remove the Jenkinsfile from individual source code repositories in favor of a centralized, tool-agnostic [Pipeline Template](https://jenkinsci.github.io/templating-engine-plugin/2.5/concepts/pipeline-templates/). 
+Users can remove the Jenkinsfile from individual source code repositories in favor of a centralized, tool-agnostic [Pipeline Template](https://jenkinsci.github.io/templating-engine-plugin/2.5/concepts/pipeline-templates/).
 This template provides the structure of the pipeline.
 
 Pipeline functionality is provided by Library Steps.
@@ -78,4 +79,4 @@ Something not quite working right? Have a cool idea for how to make JTE better?
 
 No contribution is too small - all are appreciated!
 
-Check out the [Contributing Section](https://jenkinsci.github.io/templating-engine-plugin/2.5/contributing/fork-based/) of the documentation to understand how to get started.
+Check out the [Contributing Section](https://jenkinsci.github.io/templating-engine-plugin/2.5/contributing/fork-based/) of the documentation to understand how to get started.
diff --git a/build.gradle b/build.gradle
@@ -1,13 +1,13 @@
 plugins {
   id 'groovy'
-  id 'org.jenkins-ci.jpi' version '0.43.0'
+  id 'org.jenkins-ci.jpi' version '0.50.0-rc.3'
   id 'jacoco'
-  id "com.diffplug.gradle.spotless" version "3.29.0"
+  id "com.diffplug.spotless" version "6.20.0"
   id 'codenarc'
 }
 
 repositories {
-    jcenter()
+    mavenCentral()
     maven {
         url('https://repo.jenkins-ci.org/public/')
     }
@@ -18,12 +18,11 @@ version = '2.5.3'
 description = 'Allows users to create tool-agnostic, templated pipelines to be shared by multiple teams'
 
 jenkinsPlugin {
-    coreVersion = '2.263.1'
-    shortName = 'templating-engine'
-    displayName = 'Templating Engine'
-    url = 'https://github.com/jenkinsci/templating-engine-plugin'
-    disabledTestInjection = false
-    localizerOutputDir = "${project.buildDir}/generated-src/localizer"
+    jenkinsVersion.set('2.387.3')
+    pluginId.set('templating-engine')
+    humanReadableName.set('Templating Engine')
+    homePage.set(uri('https://github.com/jenkinsci/templating-engine-plugin'))
+    generateTests.set(true)
     configureRepositories = false
     configurePublishing = true
     developers {
@@ -42,26 +41,28 @@ jenkinsPlugin {
 
 dependencies {
     // plugin dependencies
-    implementation 'org.jenkins-ci.plugins.workflow:workflow-multibranch:2.20'
-    implementation 'org.jenkins-ci.plugins.workflow:workflow-api:2.28'
-    implementation 'org.jenkins-ci.plugins:branch-api:2.0.20'
-    implementation 'org.jenkins-ci.plugins:scm-api:2.2.7'
-    implementation 'org.jenkins-ci.plugins:junit:1.24'
-    implementation 'org.jenkins-ci.plugins:script-security:1.76'
-    implementation 'org.jenkinsci.plugins:pipeline-model-definition:1.8.4' // version declarative started supporting JTE
+    implementation platform('io.jenkins.tools.bom:bom-2.387.x:2278.v47b_4508e256a')
+    implementation 'org.jenkins-ci.plugins.workflow:workflow-multibranch'
+    implementation 'org.jenkins-ci.plugins.workflow:workflow-api'
+    implementation 'org.jenkins-ci.plugins:branch-api'
+    implementation 'org.jenkins-ci.plugins:scm-api'
+    implementation 'org.jenkins-ci.plugins:junit'
+    implementation 'org.jenkins-ci.plugins:script-security'
+    implementation 'org.jenkinsci.plugins:pipeline-model-definition'
     implementation 'org.jgrapht:jgrapht-core:1.4.0'
+    implementation 'org.jenkins-ci.modules:sshd'
 
     // unit test dependencies
     testImplementation 'junit:junit:4.12'
     testImplementation 'org.spockframework:spock-core:1.3-groovy-2.4'
     testImplementation 'net.bytebuddy:byte-buddy:1.10.7' // used by Spock
     testImplementation 'org.objenesis:objenesis:3.1'     // used by Spock
-    testImplementation(group: 'org.jenkins-ci.plugins', name: 'git', version:'3.9.3', classifier:'tests') {
+    testImplementation(group: 'org.jenkins-ci.plugins', name: 'git', classifier:'tests') {
         exclude(module: 'httpclient')
         exclude(module: 'annotation-indexer')
     }
 
-    testImplementation(group: "org.jenkins-ci.main", name: "jenkins-test-harness", version: "2.71")
+    testImplementation(group: "org.jenkins-ci.main", name: "jenkins-test-harness", version: "1837.vb_6efb_1790942")
 
     // test plugins
     testImplementation(group: "org.jenkins-ci.plugins.workflow", name: "workflow-support", classifier: "tests")
@@ -70,15 +71,15 @@ dependencies {
         exclude(module: 'httpclient')
         exclude(module: 'annotation-indexer')
     }
-    testImplementation 'org.jenkins-ci.plugins:token-macro:2.13'
-    testImplementation 'org.jenkins-ci.plugins:matrix-project:1.18'
+    testImplementation 'org.jenkins-ci.plugins:token-macro'
+    testImplementation 'org.jenkins-ci.plugins:matrix-project'
     testImplementation 'org.jenkins-ci.plugins.workflow:workflow-aggregator:2.6'
-    testImplementation 'org.jenkins-ci.plugins.workflow:workflow-step-api:2.19'
+    testImplementation 'org.jenkins-ci.plugins.workflow:workflow-step-api'
 }
 
 jacocoTestReport {
     reports {
-        html.enabled true
+        html.required.set(true)
     }
 }
 
@@ -133,7 +134,7 @@ groovydoc{
  */
 task javadocJar(type: Jar) {
     description "An archive of the JavaDocs for Maven Central"
-    classifier "javadoc"
+    archiveClassifier.set("javadoc")
     from groovydoc
 }
 

diff --git a/docs/concepts/library-development/library-source.md b/docs/concepts/library-development/library-source.md
@@ -25,4 +25,4 @@ The Plugin Library Source is used when libraries have been bundled into a separa
 This option will only be available in the Jenkins UI when a plugin has been installed that can serve as a library-providing plugin.
 
 !!! note "Learn More"
-    To learn more, check out [How to Package a Library Source as a Plugin](/how-to/library-development/package-libraries-as-plugin)
+    To learn more, check out [How to Package a Library Source as a Plugin](../../../how-to/library-development/package-libraries-as-plugin)
diff --git a/docs/concepts/pipeline-governance/pipeline-template-selection.md b/docs/concepts/pipeline-governance/pipeline-template-selection.md
@@ -13,17 +13,17 @@ Figure 1 visualizes this process in a flow chart.
 
 ### Ad Hoc Pipeline Jobs
 
-JTE treats ad hoc Pipeline Jobs a little differently than Pipeline Jobs that have been created by a MultiBranch Project.
+JTE treats ad hoc Pipeline Jobs a little differently than Pipeline Jobs that have been created by a Multibranch Project.
 
 For Pipeline Jobs, if a Pipeline Template has been configured, it will be used.
 If not, JTE will follow the flow described throughout the rest of this document.
 
 !!! note "Rationale"
     The rationale for using the configured template without falling back to the rest of the Pipeline Template Selection process is that if a user has permissions to create and configure their own Jenkins job, Pipeline Governance is already gone.
 
-### MultiBranch Project Pipeline Jobs
+### Multibranch Project Pipeline Jobs
 
-For MultiBranch Project Pipeline Jobs, if the source code repository has a `Jenkinsfile` at the root (or at any arbitrary path in the repository as configured by `scriptPath`) **and** `jte.allow_scm_jenkinsfile` is set to `True`, then the repository `Jenkinsfile` will be used as the Pipeline Template.
+For Multibranch Project Pipeline Jobs, if the source code repository has a `Jenkinsfile` at the root (or at any arbitrary path in the repository as configured by `scriptPath`) **and** `jte.allow_scm_jenkinsfile` is set to `True`, then the repository `Jenkinsfile` will be used as the Pipeline Template.
 
 !!! important "Disabling Repository Jenkinsfiles"
     It's important that when trying to enforce a certain set of Pipeline Templates are used that `jte.allow_scm_jenkinsfile` is set to `False`.

diff --git a/docs/how-to/library-development/package-libraries-as-plugin.md b/docs/how-to/library-development/package-libraries-as-plugin.md
@@ -1,6 +1,6 @@
 # Package a Library Source as a Plugin
 
-Users can package their Library Source as a stand-alone Jenkins Plugin. 
+Users can package their Library Source as a stand-alone Jenkins Plugin.
 
 This has a couple advantages:
 
@@ -26,4 +26,4 @@ The `hpi` file will be output to your projects build directory.
 from there, you can install the `hpi` file via the Jenkins UI.
 
 !!! note
-    To see an example Library Source, check out the [jte-library-scaffold](https://github.com/steven-terrana/jte-library-scaffold).
+    To see an example Library Source, check out the [jte-library-scaffold](https://github.com/steven-terrana/jte-library-scaffold).
diff --git a/docs/index.md b/docs/index.md
@@ -27,7 +27,7 @@ The Jenkins Templating Engine is a pipeline development framework for [Jenkins](
       </div>
     </div>
   </a>
-  <a href="./tutorials/overview/">
+  <a href="./tutorials/">
     <div class="card">
       <div class="card__content">
         <div class="card__title"><svg style="width:24px;height:24px" viewBox="0 0 24 24"><path fill="currentColor" d="M16.84,2.73C16.45,2.73 16.07,2.88 15.77,3.17L13.65,5.29L18.95,10.6L21.07,8.5C21.67,7.89 21.67,6.94 21.07,6.36L17.9,3.17C17.6,2.88 17.22,2.73 16.84,2.73M12.94,6L4.84,14.11L7.4,14.39L7.58,16.68L9.86,16.85L10.15,19.41L18.25,11.3M4.25,15.04L2.5,21.73L9.2,19.94L8.96,17.78L6.65,17.61L6.47,15.29" /></svg>Tutorials</div>

diff --git a/docs/styles/JTE/Substitutions.yml b/docs/styles/JTE/Substitutions.yml
@@ -42,6 +42,6 @@ swap:
   'governance tier' : Governance Tier
   'Governance tier' : Governance Tier
   'governance Tier' : Governance Tier
-  'pipeline run' : Pipeline Run
-  'Pipeline run' : Pipeline Run
-  'pipeline Run' : Pipeline Run
+  'pipeline runs?\b' : Pipeline Run
+  'Pipeline runs?\b' : Pipeline Run
+  'pipeline Runs?\b' : Pipeline Run
diff --git a/docs/styles/Microsoft/Contractions.yml b/docs/styles/Microsoft/Contractions.yml
@@ -18,13 +18,13 @@ swap:
   is not: isn't
   # it is: it's --> sometimes "it's" isn't grammatically correct
   should not: shouldn't
-  that is: that's
+  # that is: that's --> stilted, especially when replacing "i.e."
   they are: they're
   was not: wasn't
   we are: we're
-  we have: we've
+  # we have: we've --> "we've" sounds awkward in certain contexts
   were not: weren't
-  what is: what's
+  # what is: what's --> personal preference, "what's" sounds stilted
   when is: when's
   where is: where's
   will not: won't
diff --git a/docs/styles/Vocab/JTE/accept.txt b/docs/styles/Vocab/JTE/accept.txt
@@ -1,28 +1,35 @@
-[Jj]enkinsfiles?
-[Nn]amespaces?
-[Tt]emplat(e|es|ed|ing)\b
 [Aa]utowir(e|es|ed|ing)\b
-[Mm]etaprogramming
-[Ss]erializab(ility|le)\b
-[Gg]radle
-[Cc]lasspath
-[Pp]arameteriz(e|es|ed|ing)\b
-[Rr]eusability
-[Bb]ooleans?
-[Ii]nvocable
-[Ss]ubkeys?
+Ansible
+Artifactory
 [Bb]asename
-[Hh]oc
-[Kk]ubernetes
-[Dd]ev
-[Jj]enkins
+[Bb]ooleans?
+[Cc]lasspath
 [Cc]onfigs?
-[Ww]alkthroughs?
+[Dd]ev
 Divio
+Dockerfile
+[Ee]num
+[Gg]radle
+[gG]roovy
+[Hh]oc
+https
+[Ii]nvocable
+[Jj]enkins
+[Jj]enkinsfiles?
+[Kk]ubernetes
 [Mm]arkdownlint
 md
-[Ee]num
-truthy
-Artifactory
+[Mm]etaprogramming
+Multibranch
+[Nn]amespaces?
+[Pp]arameteriz(e|es|ed|ing)\b
+[Pp]repending
+[Rr]epo
 [rR]esumability
-[gG]roovy
+[Rr]eusability
+[Ss]erializab(ility|le)\b
+Splunk
+[Ss]ubkeys?
+[Tt]emplat(e|es|ed|ing)\b
+truthy
+[Ww]alkthroughs?
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -0,0 +1,14 @@
+# Overview
+
+Tutorials are learning oriented lessons to teach users about JTE.
+
+The best way to learn a technology is to use it. These Learning Labs have been designed to give you hands-on experience with the Jenkins Templating Engine.
+
+## Learning Labs Overview
+
+| Lab <img width=250/>                   | Description                                                                                     |
+|-----------------------------------------|-------------------------------------------------------------------------------------------------|
+| [Local Development](./local-development/index.md) | In this lab, we’ll be deploying a local Jenkins instance using Docker and installing the Jenkins Templating Engine. |
+| [JTE: The Basics](./jte-the-basics/index.md) | Explore the basic concepts of the Jenkins Templating Engine and different ways to use it. |
+| [JTE: Learn the Primitives](./jte-primitives/index.md) | Explore the different Pipeline Primitives JTE exposes, called primitives, to aid in pipeline template authoring. |
+| [JTE: Advanced Features](./jte-advanced-features/index.md) |  Level up your JTE skills by learning its advanced features like the default step implementation and how to leverage step lifecycle hooks. |
diff --git a/docs/tutorials/jte-advanced-features/1-prerequisites.md b/docs/tutorials/jte-advanced-features/1-prerequisites.md
@@ -0,0 +1,11 @@
+# Prerequisites
+
+## Jenkins Instance
+
+A Jenkins instance will be required for this lab. If you don't have one available to you, we would recommend going through [Local Development Learning Lab](../local-development/index.md) to deploy a local Jenkins instance through Docker.
+
+## JTE: Pipeline Primitives
+
+This lab is the third and final lab specifically dedicated to the Jenkins Templating Engine's functionality.
+
+Please be sure to have completed the [Pipeline Primitives Learning Lab](../jte-primitives/index.md) before attempting this one, as we will be picking up where that lab leaves off.