Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-58503

Symbols for Extensions

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed (View Workflow)
    • Priority: Minor
    • Resolution: Duplicate
    • Component/s: git-plugin
    • Labels:
      None
    • Environment:
      2.176.1
    • Similar Issues:

      Description

      Its currently possible to use the following dsl below when checking out code in a declarative pipeline:

      checkout(
        git(
          branches: [[name: '*/master']],
          extensions: [[
            $class: 'RelativeTargetDirectory', 
            relativeTargetDir: 'some-dir'
          ]]
        )
      )

       

      It would be nice if it could support a richer dsl rather than the current $class syntax for extensions. e.g. something like:

       

      checkout(
        git(
          branches: [[name: '*/master']],
          extensions: [[
            relativeTargetDir('some-dir')
          ]]
        )
      )

       

      This could be something i could help contribute if its acceptable?!

      Implementation Process

      • List existing symbol definitions from configuration as code matched with $Class samples for that symbol (create a checklist of symbols to create)
      • Select a symbol and add a test for the symbol as a $Class form
      • Add the symbol
      • Add a test that uses the symbol instead of the $Class form
      • Confirm symbol appears in Pipeline syntax generator
      • Confirm symbol appears in Configuration as Code
      • Confirm configuration as code can still read previous configuration files
      • Write help for the symbol, assure it is clear, correct, complete, and visible in the online Pipeline syntax
      • Write documentation for the symbol in the plugin README so that it is available outside of Jenkins

      Existing Symbol Definitions

      JCasC Parent JCasC Symbol Class Sample Symbol Sample
      Col A0 Col A1 Col A2  
      git branches branches  
      branches name branches: [[name: 'origin/master']] branches: [[name: 'origin/master']]
      extensions localBranch [$class:'LocalBranch', localBranch: '**'] localBranch('**')
      traits localBranch N/A (not in a Jenkinsfile) localBranchTrait

      See the Karl Shultz pull request for progress.

        Attachments

          Issue Links

            Activity

            Hide
            markewaite Mark Waite added a comment -

            Thanks for offering! I'm happy to consider a pull request that adds symbols for the Pipeline checkout step and the Pipeline syntax section. I'm not willing to consider additions to the git step unless they are also available in the checkout step. The syntax you used in your example with a git step nested inside a checkout step is not a syntax I recognize.

            I'm accustomed to the syntax generated by the Snippet Generator inside Jenkins. Today it creates a snippet that looks like this:

            checkout(
                [$class: 'GitSCM',
                    branches: [[name: 'stable-2.176']],
                    extensions: [
                        [$class: 'CloneOption', depth: 1, honorRefspec: true, noTags: true, reference: '/var/lib/git/jenkinsci/jenkins.git', shallow: true],
                        [$class: 'LocalBranch', localBranch: 'stable-2.176'],
                        [$class: 'ChangelogToBranch', options: [compareRemote: 'origin', compareTarget: 'stable-2.164']
                        ]
                    ],
                    gitTool: 'Default',
                    userRemoteConfigs: [
                        [refspec: '+refs/heads/stable-2.176:refs/remotes/origin/stable-2.176 +refs/heads/stable-2.164:refs/remotes/origin/stable-2.164',
                            url: 'https://github.com/jenkinsci/jenkins.git'
                        ]
                    ]
                ]
            )
            

            I'd be interested in a pull request that would make it look something more like this:

            checkout(
                [$class: 'GitSCM',
                    branches: [[name: 'stable-2.176']],
                    extensions: [
                        cloneOption(depth: 1, honorRefspec: true, noTags: true, reference: '/var/lib/git/jenkinsci/jenkins.git', shallow: true),
                        localBranch('stable-2.176'),
                        changelogToBranch('origin', 'stable-2.164')
                    ],
                    gitTool: 'Default',
                    userRemoteConfigs: [
                        [refspec: '+refs/heads/stable-2.176:refs/remotes/origin/stable-2.176 +refs/heads/stable-2.164:refs/remotes/origin/stable-2.164',
                            url: 'https://github.com/jenkinsci/jenkins.git'
                        ]
                    ]
                ]
            )
            

            Also, the specific example of relativeTargetDir should not be added as a symbol. The dir and ws steps in Pipeline are the preferred way to perform a checkout to a subdirectory of a workspace in a Pipeline. I don't think we should add convenience symbols for extensions that are not intended to be used in Pipeline. The extensions continue to exist and continue to behave as they did before, but we should not encourage further use in Pipelines when there are more general purpose ways to do the same thing.

            Reviewing such a pull request would likely need help from Jesse Glick or Andrew Bayer since I'm not deeply experienced in the coding patterns for Pipeline support.

            Show
            markewaite Mark Waite added a comment - Thanks for offering! I'm happy to consider a pull request that adds symbols for the Pipeline checkout step and the Pipeline syntax section. I'm not willing to consider additions to the git step unless they are also available in the checkout step. The syntax you used in your example with a git step nested inside a checkout step is not a syntax I recognize. I'm accustomed to the syntax generated by the Snippet Generator inside Jenkins. Today it creates a snippet that looks like this: checkout( [$class: 'GitSCM', branches: [[name: 'stable-2.176']], extensions: [ [$class: 'CloneOption', depth: 1, honorRefspec: true, noTags: true, reference: '/var/lib/git/jenkinsci/jenkins.git', shallow: true], [$class: 'LocalBranch', localBranch: 'stable-2.176'], [$class: 'ChangelogToBranch', options: [compareRemote: 'origin', compareTarget: 'stable-2.164'] ] ], gitTool: 'Default', userRemoteConfigs: [ [refspec: '+refs/heads/stable-2.176:refs/remotes/origin/stable-2.176 +refs/heads/stable-2.164:refs/remotes/origin/stable-2.164', url: 'https://github.com/jenkinsci/jenkins.git' ] ] ] ) I'd be interested in a pull request that would make it look something more like this: checkout( [$class: 'GitSCM', branches: [[name: 'stable-2.176']], extensions: [ cloneOption(depth: 1, honorRefspec: true, noTags: true, reference: '/var/lib/git/jenkinsci/jenkins.git', shallow: true), localBranch('stable-2.176'), changelogToBranch('origin', 'stable-2.164') ], gitTool: 'Default', userRemoteConfigs: [ [refspec: '+refs/heads/stable-2.176:refs/remotes/origin/stable-2.176 +refs/heads/stable-2.164:refs/remotes/origin/stable-2.164', url: 'https://github.com/jenkinsci/jenkins.git' ] ] ] ) Also, the specific example of relativeTargetDir should not be added as a symbol. The dir and ws steps in Pipeline are the preferred way to perform a checkout to a subdirectory of a workspace in a Pipeline. I don't think we should add convenience symbols for extensions that are not intended to be used in Pipeline. The extensions continue to exist and continue to behave as they did before, but we should not encourage further use in Pipelines when there are more general purpose ways to do the same thing. Reviewing such a pull request would likely need help from Jesse Glick or Andrew Bayer since I'm not deeply experienced in the coding patterns for Pipeline support.
            Hide
            jglick Jesse Glick added a comment -

            It would be nice if it could support a richer dsl rather than the current $class syntax

            See JENKINS-37227. I do not advocate making any changes to the git step; it should be considered a dead end, to be superseded by checkout.

            Anyway adding symbols for extensions is orthogonal to that.

            Show
            jglick Jesse Glick added a comment - It would be nice if it could support a richer dsl rather than the current $class syntax See JENKINS-37227 . I do not advocate making any changes to the git step; it should be considered a dead end, to be superseded by checkout . Anyway adding symbols for extensions is orthogonal to that.
            Hide
            markewaite Mark Waite added a comment -

            Goal is to release the symbol extensions as part of git plugin 4.3.0

            Show
            markewaite Mark Waite added a comment - Goal is to release the symbol extensions as part of git plugin 4.3.0

              People

              Assignee:
              markewaite Mark Waite
              Reporter:
              a1dutch Andrew Holland
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: