From d046b12b12af3ffa4da08aa5355257451d600467 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Thu, 7 May 2020 16:38:01 -0600 Subject: [PATCH 1/4] Add snippet generator link to help page Users frequently comment in the feedback on the jenkins.io checkout page https://www.jenkins.io/doc/pipeline/steps/workflow-scm-step/ that they would like more examples. Many of those writing the comments may not be aware that the Pipeline Snippet Generator can provide help from within their Jenkins server for the specific plugins and plugin versions they are using. Hyperlink to the Pipeline Snippet Generator in hopes that users will see one of the hyperlinks and understand that they can use their own Jenkins server for better information about the Pipeline Syntax. --- .../workflow/steps/scm/GenericSCMStep/help.jelly | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly index 9ab7c4f..7aef7ee 100644 --- a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly +++ b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly @@ -2,11 +2,13 @@

- This is a special step that allows to run checkouts using any configuration + This is a special step that will checkout using the configuration options offered by any Pipeline-compatible SCM plugin. - To use a concrete SCM implementations, just install the corresponding plugin - and check if it is shown in the list below. - Then select the SCM to use from the dropdown list and configure it as needed. + Install the corresponding SCM plugin and select it from the list in the + Pipeline Snippet Generator. + The + Pipeline Snippet Generator + uses the installed SCM plugins of your Jenkins server to suggest pipeline snippets.

This step returns a Map of any variables the SCM plugin would set in a Freestyle job, so if your SCM is git, you can do: From 1eff4f1397a109d0df83b533842457d835e47543 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Thu, 7 May 2020 16:41:44 -0600 Subject: [PATCH 2/4] Use correct end tag for anchor --- .../plugins/workflow/steps/scm/GenericSCMStep/help.jelly | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly index 7aef7ee..8d8f78c 100644 --- a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly +++ b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly @@ -5,9 +5,9 @@ This is a special step that will checkout using the configuration options offered by any Pipeline-compatible SCM plugin. Install the corresponding SCM plugin and select it from the list in the - Pipeline Snippet Generator. + Pipeline Snippet Generator. The - Pipeline Snippet Generator + Pipeline Snippet Generator uses the installed SCM plugins of your Jenkins server to suggest pipeline snippets.

This step returns a Map of any variables the SCM plugin would From a9962927dc9d61fc70038f7301bd88219732f4c7 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Sat, 20 Feb 2021 09:17:54 -0700 Subject: [PATCH 3/4] Replace deprecated terminology --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3adf561..40ec136 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ The goals are the maximum possible compatibility with existing plugins, and grea A freestyle project has a single SCM configured in the UI that governs the one and only workspace for the build. A Pipeline can be configured similarly, but the SCM definition becomes a regular step in its script. -In the simplest case you would just do an SCM clone/update at the start of your script, as soon as you have allocated a slave with a workspace: +In the simplest case you would just do an SCM clone/update at the start of your script, as soon as you have allocated an agent with a workspace: ``` node { @@ -23,7 +23,7 @@ node { ``` Jenkins will clone the repository into the workspace and continue with your script. -(Subsequent builds will update rather than clone, if the same slave and workspace are available again.) +(Subsequent builds will update rather than clone, if the same agent and workspace are available again.) ### Multiple SCMs @@ -31,7 +31,7 @@ While freestyle projects can use the Multiple SCMs plugin to check out more than or specify multiple locations in SCM plugins that support that (notably the Git plugin), this support is quite limited. In a Pipeline you can check out multiple SCMs, of the same or different kinds, in the same or different workspaces, wherever and whenever you like. -For example, to check out and build several repositories in parallel, each on its own slave: +For example, to check out and build several repositories in parallel, each on its own agent: ``` parallel repos.collectEntries {repo -> [/* thread label */repo, { @@ -57,7 +57,7 @@ This means that you can run multiple SCMs, even from a dynamic list, and get a r If you configure the _Poll SCM_ trigger in the Pipeline’s UI configuration screen, then by default Jenkins will also poll for changes according to the selected _Schedule_, and schedule new builds automatically if changes are detected. (Note that this configuration is not part of the Pipeline script, because it affects activities that Jenkins runs outside of the Pipeline.) -Some SCMs allow polling with no workspace, which is ideal; others will try to lock the same slave and workspace previously used, to run polling on the slave. +Some SCMs allow polling with no workspace, which is ideal; others will try to lock the same agent and workspace previously used, to run polling on the agent. To avoid polling the server repeatedly, most SCM plugins allow remote commit triggers, such as the `/git/notifyCommit?url=…` HTTP endpoint in the case of the Git plugin. These also work with Pipelines, unless (as with freestyle projects) you checked _Ignore post-commit hooks_ in a _Poll SCM_ block. From 3180671bba7c8bcfba7e99d401b889b5cb54bdef Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Mon, 22 Feb 2021 14:52:03 -0700 Subject: [PATCH 4/4] Use the snippet-generator redirect Allows the description of the snippet generator to move on the jenkins.io site without requiring a change in the plugin source code. Depends on https://github.com/jenkins-infra/jenkins.io/pull/4133 --- README.md | 2 +- .../plugins/workflow/steps/scm/GenericSCMStep/help.jelly | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 40ec136..ff16a0a 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ The `checkout` step may be used to run any other SCM plugin, provided that it ha It could also be used to run an SCM for which there is a special integration that lacks support for an exotic feature. The step takes an `scm` parameter which is a map containing at least a `$class` parameter giving the full or simple class name of the desired `SCM` implementation, and the standard `poll` and `changelog` parameters. -It also takes any other parameters supported by the SCM plugin in its configuration form, using their internal names and values; use _Snippet Generator_ to get a detailed example for your SCM. +It also takes any other parameters supported by the SCM plugin in its configuration form, using their internal names and values; use [_Snippet Generator_](https://jenkins.io/redirect/pipeline-snippet-generator)to get a detailed example for your SCM. Optional parameters can be omitted and will take their default values (to the extent supported by the SCM plugin). For example, to run Mercurial (1.51-beta-2 or higher): diff --git a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly index 8d8f78c..72e56d6 100644 --- a/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly +++ b/src/main/resources/org/jenkinsci/plugins/workflow/steps/scm/GenericSCMStep/help.jelly @@ -5,9 +5,9 @@ This is a special step that will checkout using the configuration options offered by any Pipeline-compatible SCM plugin. Install the corresponding SCM plugin and select it from the list in the - Pipeline Snippet Generator. + Pipeline Snippet Generator. The - Pipeline Snippet Generator + Pipeline Snippet Generator uses the installed SCM plugins of your Jenkins server to suggest pipeline snippets.

This step returns a Map of any variables the SCM plugin would