Skip to content

[JENKINS-62130] Simplify Pipeline authoring with symbols - #1373

Merged
MarkEWaite merged 2 commits into
jenkinsci:masterfrom
MarkEWaite:add-symbols
Dec 28, 2022
Merged

[JENKINS-62130] Simplify Pipeline authoring with symbols#1373
MarkEWaite merged 2 commits into
jenkinsci:masterfrom
MarkEWaite:add-symbols

Conversation

@MarkEWaite

@MarkEWaite MarkEWaite commented Dec 6, 2022 •
edited
Loading

Copy link
Copy Markdown
Contributor

JENKINS-62130 Simplify Pipeline authoring with symbols

Pipeline authoring is easier from the Pipeline snippet syntax generator when symbols are provided by the plugin.

Special thanks to Karl Schultz for starting this project.

Checklist

  • I have read the CONTRIBUTING doc
  • I have referenced the Jira issue related to my changes in one or more commit messages
  • I have added tests that verify my changes
  • Unit tests pass locally with my changes
  • I have added documentation as necessary
  • No Javadoc warnings were introduced with my changes
  • No spotbugs warnings were introduced with my changes
  • Documentation in README has been updated as necessary
  • Online help has been added and reviewed for any new or modified fields
  • I have interactively tested my changes
  • Any dependent changes have been merged and published in upstream modules (like git-client-plugin)

Types of changes

  • New feature (non-breaking change which adds functionality)

Further comments

A number of questions will arise as part of the testing and exploration of this pull request.

Configuration as code changes

Several configuration as code symbols have been made obsolete, with a newer symbol as the preferred value. Those symbols include:

Configuration as Code obsolete file format:

  • 'git' is obsolete, please use 'scmGit'
  • 'localBranchTrait' is obsolete, please use 'localBranch'
  • 'discoverOtherRefsTrait' is obsolete, please use 'discoverOtherRefs'

Known issues in progress

  • Obsolete file format warning for "'git' is obsolete" cannot be resolved. - legacyScm has a sub-item that is currently git and needs to be changed to scmGit. See the before line and the after line for the example.
  • Fix submodule option class so that it uses a symbol. Instead of [$class: 'SubmoduleOption', depth: 1, shallow: true] it should be submodule(depth: 1, shallow: true). Done in 89f648a

Pending investigation

  • Short form of many extensions (submodule, cloneOption, ...) display the default values in the Pipeline snippet syntax generator instead of hiding those default values. Find a way to hide the default values rather than displaying them. For example, instead of submodule(timeout:null) when null is the default value for timeout, it should offer submodule() (won't do)

@MarkEWaite MarkEWaite added the enhancement Improvement or new feature label Dec 6, 2022
@github-actions github-actions Bot added dependencies Dependency related change documentation Improvements or additions to documentation test labels Dec 6, 2022
MarkEWaite added a commit to MarkEWaite/bom that referenced this pull request Dec 6, 2022
@MarkEWaite
Use git plugin 5.0.0 incremental with symbols added
a767f65 
jenkinsci/git-plugin#1373

https://ci.jenkins.io/job/Plugins/job/git-plugin/view/change-requests/job/PR-1373/
basil
basil approved these changes Dec 6, 2022
View reviewed changes

@basil basil left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice! Some optional feedback for your consideration: consider using the camel case convention defined by Google which would result in e.g. gitScm and gitLfsPull over gitSCM and gitLFSPull.

Arguments in favor of Google convention: highly logical and deterministic.

Arguments against Google convention: other Jenkins classes and symbols don't follow the Google convention, diminishing the value of following the Google convention in just this one place (and perhaps even resulting in a jarring difference in conventions, if the existing Jenkins style could even be called a convention).

Anyway, no strong feeling from my side, and certainly happy with the improvement as-is.

@MarkEWaite

MarkEWaite commented Dec 16, 2022 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Very nice! Some optional feedback for your consideration: consider using the camel case convention defined by Google which would result in e.g. gitScm and gitLfsPull over gitSCM and gitLFSPull.

Arguments in favor of Google convention: highly logical and deterministic.

Arguments against Google convention: other Jenkins classes and symbols don't follow the Google convention, diminishing the value of following the Google convention in just this one place (and perhaps even resulting in a jarring difference in conventions, if the existing Jenkins style could even be called a convention).

Anyway, no strong feeling from my side, and certainly happy with the improvement as-is.

Thanks for the comment. The Pipeline Multibranch plugin follows the Google convention with resolveScm. My first search of the Pipeline steps reference found no cases of any plugin using the casing that I've used for gitSCM. I've changed it to scmGit so that it looks closer to checkout scm when it says checkout scmGit.

@MarkEWaite
MarkEWaite marked this pull request as ready for review December 17, 2022 22:22
@MarkEWaite MarkEWaite changed the title Simplify Pipeline authoring with symbols [JENKINS-62130] Simplify Pipeline authoring with symbols Dec 18, 2022
MarkEWaite added a commit to MarkEWaite/pipeline-groovy-lib-plugin that referenced this pull request Dec 18, 2022
@MarkEWaite
Adapt test for git plugin 5.0
01b9885 
Git plugin 5.0 will require Java 11 and will add symbols to improve
the Pipeline syntax editing experience.  The test being modified in
this pull request checks the specific syntax of the Pipeline snippet
syntax generator.  Adapt the test to check for current syntax with git
plugin 4.x releases and for new syntax with any other releases.

jenkinsci/git-client-plugin#939 is the git
client plugin pull request that prepares git client plugin 4.0.0.
It will require Java 11 and will upgrade from JGit 5.13.1 to JGit 6.4.0.

jenkinsci/bom#1619 is the bom draft pull request
that confirms git client plugin 4.0.0 pre-release works in the plugin bom.

jenkinsci/git-plugin#1367 is the git plugin pull
request that prepares git plugin 5.0.0.  It will require Java 11.

jenkinsci/bom#1624 is the bom draft pull request
that tests git plugin 5.0.0 works in the plugin bom.

jenkinsci/git-plugin#1373 is the git plugin pull
request that relies on jenkinsci/git-plugin#1367
and adds symbols to the git plugin.

jenkinsci/bom#1625 is the bom draft pull request
that tests git plugin 5.0.0 with added symbols works in the plugin bom.
It detected this test failure when run with git plugin 5.0.0 pre-release.
@MarkEWaite MarkEWaite mentioned this pull request Dec 18, 2022
Merged
6 tasks
@github-actions github-actions Bot removed the dependencies Dependency related change label Dec 25, 2022
@MarkEWaite
Add symbols for easier Pipeline authoring
e752625 
Pipeline authoring with the git plugin has not been using the symbol
facility that is used elsewhere in Jenkins.

Previously, a Pipeline checkout might look like this:

    checkout([$class: 'GitSCM',
              userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.gi' ]],
              branches: [[name: 'master']],
              extensions: [[$class: 'CloneOption', noTags: true, timeout: 3],
                           [$class: 'LocalBranch', localBranch: branch],
                          ],
             ])

With the addition of symbols, the earlier Pipeline checkout continues
to be supported, but it can also be written as:

    checkout scmGit(
              userRemoteConfigs: [[url: 'https://github.com/jenkinsci/git-plugin.gi' ]],
              branches: [[name: 'master']],
              extensions: [cloneOption(noTags: true, timeout: 3),
			   localBranch('master')
			  ],
             )

The symbols make it easier to read and easier to understand.

Change includes updated documentation with Pipeline examples and
screenshots taken with Jenkins 2.375.1.

Thanks to Karl Shultz for starting the work on this improvement.
@MarkEWaite MarkEWaite removed documentation Improvements or additions to documentation test labels Dec 28, 2022
@MarkEWaite
MarkEWaite enabled auto-merge (rebase) December 28, 2022 19:59
@MarkEWaite
Use teamFoundation for TFS browser name
7daf54a 
Clearer name and does not embed Microsoft in the symbol value
@github-actions github-actions Bot added documentation Improvements or additions to documentation test labels Dec 28, 2022
@MarkEWaite
MarkEWaite merged commit 12d6962 into jenkinsci:master Dec 28, 2022
@MarkEWaite
MarkEWaite deleted the add-symbols branch December 28, 2022 21:01
@MarkEWaite MarkEWaite removed documentation Improvements or additions to documentation test labels Dec 28, 2022
@MarkEWaite MarkEWaite mentioned this pull request Jan 2, 2023
Merged
@jglick jglick mentioned this pull request Sep 30, 2025
Merged
@MarkEWaite MarkEWaite mentioned this pull request Dec 7, 2025
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@basil basil basil approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

enhancement Improvement or new feature

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@MarkEWaite @basil