[JENKINS-58503] Symbols for Extensions

Andrew Holland created issue - 2019-07-15 21:56

Mark Waite made changes - 2019-07-15 23:27

Assignee

Original: Mark Waite [ markewaite ]

Mark Waite added a comment - 2019-07-15 23:48

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 jglick or abayer since I'm not deeply experienced in the coding patterns for Pipeline support.

Mark Waite added a comment - 2019-07-15 23:48 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 jglick or abayer since I'm not deeply experienced in the coding patterns for Pipeline support.

Jesse Glick made changes - 2019-07-16 18:30

Link

New: This issue relates to JENKINS-37227 [ JENKINS-37227 ]

Jesse Glick added a comment - 2019-07-16 18:30

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.

Jesse Glick added a comment - 2019-07-16 18:30 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.

Mark Waite made changes - 2020-04-14 02:43

Assignee

New: Mark Waite [ markewaite ]

Mark Waite made changes - 2020-04-23 13:44

Description

Original: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

New: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

Mark Waite made changes - 2020-04-25 12:24

Description

Original: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

New: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

h3. 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']] |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|extensions |localBranch |[$class:'LocalBranch', localBranch: '**'] |localBranch('**') |

Mark Waite made changes - 2020-04-25 12:24

Description

Original: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

h3. 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']] |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|extensions |localBranch |[$class:'LocalBranch', localBranch: '**'] |localBranch('**') |

New: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

h3. Existing Symbol Definitions

||JCasC Parent ||JCasC Symbol ||Class Sample ||Symbol Sample ||
|git |branches |branches | |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|extensions |localBranch |[$class:'LocalBranch', localBranch: '**'] |localBranch('**') |

Mark Waite made changes - 2020-04-25 15:00

Description

Original: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

h3. Existing Symbol Definitions

||JCasC Parent ||JCasC Symbol ||Class Sample ||Symbol Sample ||
|git |branches |branches | |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|extensions |localBranch |[$class:'LocalBranch', localBranch: '**'] |localBranch('**') |

New: Its currently possible to use the following dsl below when checking out code in a declarative pipeline:
{noformat}
checkout(
git(
    branches: [[name: '*/master']],
    extensions: [[
      $class: 'RelativeTargetDirectory',
      relativeTargetDir: 'some-dir'
    ]]
)
){noformat}

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

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

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

h2. 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

h3. 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']] |
|branches |name |branches: [[name: 'origin/master']] |branches: [[name: 'origin/master']] |
|extensions |localBranch |[$class:'LocalBranch', localBranch: '**'] |localBranch('**') |
|traits |localBranchTrait |N/A (not in a Jenkinsfile) |localBranchTrait |

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

Jenkins

Details

Description

Implementation Process

Existing Symbol Definitions

Attachments

Issue Links

Activity

Collapse comment: Mark Waite added a comment - 2019-07-15 23:48

Expand comment: Mark Waite added a comment - 2019-07-15 23:48

Collapse comment: Jesse Glick added a comment - 2019-07-16 18:30

Expand comment: Jesse Glick added a comment - 2019-07-16 18:30

People

Dates