Documentation
Jérôme Godbout
I agree about the server having his own version with actual plugin install is a good idea. Preventing access to it?! why?! security so I do not expose the version of the plugins used? Having an online version up to date is also a good thing, people can see what they are missing from not updating. Arguments or options showing “starting at verison x.x.x” on it would be even better.
When you dig to do something as banal as checkout git with submodules:
checkout([$class: 'GitSCM'
, branches: [[name: 'master']]
, browser: [$class: 'BitbucketWeb', repoUrl: 'https://bitbucket.org/amotus/amotus_jenkins.git']
, doGenerateSubmoduleConfigurations: false
, extensions: [[$class: 'CloneOption', noTags: false], [$class: 'LocalBranch', localBranch: "**"], [$class: 'SubmoduleOption', disableSubmodules: false, parentCredentials: true, recursiveSubmodules: true, reference: '', trackingSubmodules: false], [$class: 'CleanCheckout']]
, submoduleCfg: []
, userRemoteConfigs: [[credentialsId: 'BitBucketAmotus', url: 'https://bitbucket.org/amotus/amotus_jenkins.git']]
]);
https://www.jenkins.io/doc/pipeline/steps/workflow-scm-step/#checkout-check-out-from-version-control
Digging the class depth enough to figure out what you actually need to do it is pretty bad, add a gazillion of option that the documentation doesn’t specify the default value when unspecify. So you wonder what will actually happen if I do not specify that Boolean exactly, is it true or false by default?! Add the pain to keep track of the documentation web view alignment of the options and data from scrolling down that documents page, is that options child of it or the other level above (let me put the cursor back there and scroll up again to see what it align with exactly.
I would love to have the default value along the type, and that syntax make it pretty hard to read quickly what is going on, spotting anything missing, nearly impossible unless you do it a lot of Jenkins pipeline scripts. At some point you look at it, and you wonder why you just did not invoke sh/bat shell instead. Have something that make it easier to follow the options depth into the web view like above, class in class in class that span over 3x you screen and you only have white blank space to keep you understand the options location.
I wish I could provide better description as you said, but I have no clue most of it of what it actually does, the plugin should give information about the command that are decent. That also apply to base command of pipeline too. Having type: string is just plain not enough for user to understand what you want and what kind of format that option should take. Some are well done, the branches options into the gitscm was well done, but the quality is not to that level everywhere, and the end user cannot filled those sadly or maybe some advance user can, but you just raise the bar for some developers.
From: jenkins...@googlegroups.com <jenkins...@googlegroups.com>
On Behalf Of Mark Waite
Sent: February 9, 2021 1:48 PM
To: Jenkins Users <jenkins...@googlegroups.com>
Subject: Re: Permissions to see pipeline syntax
I agree wholeheartedly that the online Pipeline Syntax reference inside your Jenkins controller is the best choice. It presents help for exactly the current installed plugins and their versions. I recently added a section to the git plugin documentation that encourages Pipeline users to use the Pipeline Syntax Helper. It seemed more effective to do that than to provide many, many examples of different options.
The online collection at https://www.jenkins.io/doc/pipeline/steps/ presents the set of all plugins at their latest versions, whether or not they are installed on your system. That's more information than most people need and potentially incorrect information unless they are using the latest plugin version.
The text is collected from the same sources, the plugins themselves. If you would like a better description of a parameter or a Pipeline step for a specific plugin, please provide that better text to the plugin maintainers as a pull request.
We have Documentation office hours twice a week (Monday at 23:00 UTC and Thursday at 18:00 UTC). We'd be happy to use one of those sessions to show how to update Pipeline step documentation for a plugin. I've added the topic to the office hours for next Monday so that we'll have a recording of the example that others can use as they propose improvements to Pipeline specific online help for plugins.
Mark Waite
On Tuesday, February 9, 2021 at 8:08:50 AM UTC-7 Jérôme Godbout wrote:
+1 online pipeline syntax generator. The online documentation is such a pain, page too long to scroll, no type or any example, no freaking idea what the hell the value shape must be sometime. You kind of need deep knowledge of Java/Jenkins Groovy to have a slight idea of what the value are or make reference too.
When you see crap documentation like this, you known the documentation is a failure, oh look great I should put a value of string! what value, what effect, is it a path or something, go figure, what does the name actually does?!? this is pretty bad, I almost always need to find example, the doc is useless:
Or the so verbose description of script!
I wish I could make a better pun, but I don’t see anything to add 😉
Who ever made the documentation layout and descriptions (or if you prefer the lack of both) did a poor job. The collapsing on a single page make navigation of it a nightmare too. Live search maybe, link to an actual page with actual doc for the function/method/options. Take a look at Qt/Microsoft C# documentation or many other online. That would actually help people. And like the comment above, why is this not online available to all?
My 2 cents about the snippets/doc, you might disagree, but figuring out the command should not be the challenge of using a tools.
From: jenkins...@googlegroups.com <jenkins...@googlegroups.com> On Behalf Of Jeremy Mordkoff
Sent: February 9, 2021 9:45 AM
To: Jenkins Users <jenkins...@googlegroups.com>
Subject: Permissions to see pipeline syntax
What permission(s) do I need to grant to a new user in order for them to see the pipeline syntax option?
I am a full admin and I see it.
They are authenticated but they only have rights to start and stop jobs right now. I created a job for them that invokes a JenkinsFile and they are busy writing the script. But at the moment they are flying blind since they cannot see the pipeline syntax page and the snippet generator.
Perhaps there is a standalone instance of this function somewhere?
--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-use...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/df291aff-7fc6-483e-8158-481168b12a35n%40googlegroups.com.
--
You received this message because you are subscribed to the Google Groups "Jenkins Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
jenkinsci-use...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/jenkinsci-users/eb5ff368-84f8-4045-8336-765944c956dcn%40googlegroups.com.
Mark Waite
I agree about the server having his own version with actual plugin install is a good idea. Preventing access to it?! why?! security so I do not expose the version of the plugins used? Having an online version up to date is also a good thing, people can see what they are missing from not updating. Arguments or options showing “starting at verison x.x.x” on it would be even better.
When you dig to do something as banal as checkout git with submodules:
checkout([$class: 'GitSCM'
, branches: [[name: 'master']]
, browser: [$class: 'BitbucketWeb', repoUrl: 'https://bitbucket.org/amotus/amotus_jenkins.git']
, doGenerateSubmoduleConfigurations: false
, extensions: [[$class: 'CloneOption', noTags: false], [$class: 'LocalBranch', localBranch: "**"], [$class: 'SubmoduleOption', disableSubmodules: false, parentCredentials: true, recursiveSubmodules: true, reference: '', trackingSubmodules: false], [$class: 'CleanCheckout']]
, submoduleCfg: []
, userRemoteConfigs: [[credentialsId: 'BitBucketAmotus', url: 'https://bitbucket.org/amotus/amotus_jenkins.git']]
]);
https://www.jenkins.io/doc/pipeline/steps/workflow-scm-step/#checkout-check-out-from-version-control
Digging the class depth enough to figure out what you actually need to do it is pretty bad, add a gazillion of option that the documentation doesn’t specify the default value when unspecify. So you wonder what will actually happen if I do not specify that Boolean exactly, is it true or false by default?! Add the pain to keep track of the documentation web view alignment of the options and data from scrolling down that documents page, is that options child of it or the other level above (let me put the cursor back there and scroll up again to see what it align with exactly.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/QB1PR01MB384431CC00C93454CB8B69A9CD8E9%40QB1PR01MB3844.CANPRD01.PROD.OUTLOOK.COM.
Jérôme Godbout
Hi,
good to know those are going to improve, thanks for the heads up.
regards,
Jerome
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-users/CAO49JtF_iY5%3DEKbt4PxosfzaCovKJr4C1ZCFERN9Y0%3DO6LxjXQ%40mail.gmail.com.