[JENKINS-26126] Syntax schema

[jglick]

JENKINS-26126

• API design
• basic tests
• tests for help text
• implementation
• prototype static documentation generation

@reviewbybees esp. @abayer

[abayer]

Yaaaay - looking forward to utilizing this a bunch.

[ghost]

This pull request originates from a CloudBees employee. At CloudBees, we require that all pull requests be reviewed by other CloudBees employees before we seek to have the change accepted. If you want to learn more about our process please see this explanation.

[amuniz]

@jglick It seems like this PR is partially commited to master (?) 3a3d8a1

[amuniz]

Oh, ok, it's not master, it's your feature branch, is there any reason to use an origin branch in this case instead of a fork?

[amuniz]

BTW every commit in this PR is spamming the JIRA issue with comments.

[amuniz]

DescribableHelper.CLAZZ instead of $class?

[abayer]

Prototype site generation looks like a great start - obviously lots of tweaks to the presentation needed, and we need to add GDSL/DSLD generation, but that all can come after the guts here go in. Can't speak to the code specifically, but the output seems to do all we need it to do.

[abayer]

I'm 🐝 on this - it may not be perfect yet, but it's far enough that it can be built on for more.

[jglick]

is there any reason to use an origin branch in this case instead of a fork?

Yes—@abayer said he might want to work on it directly. But if he agrees with the contents so far, it could just be merged.

every commit in this PR is spamming the JIRA issue with comments.

I know, this is a bug in the JIRA link daemon, that it does not pay attention to branch. Feel free to fix it.

[abayer]

fwiw, a copy of the initial HTML output is up at https://rawgit.com/abayer/10ad3f9e9fd57bf9b1a5/raw/35adaabd9b2e0f2d6eec9e45c5c15912ddd2bf6d/workflow-reference.html

[abayer]

@jglick - curious - do you remember where the JIRA link daemon source is?

[jglick]

do you remember where the JIRA link daemon source is?

No, ask on #infra.

[KostyaSha]

@abayer separate org in GH jenkins-infra

[amuniz]

do you remember where the JIRA link daemon source is?

I was going to ask that :) If you point me to that repo I'll fix it.

About the HTML format, I would suggest a little change: move the Type to same line that the attr name.
For example:

archive: Archive artifacts

Archives build output artifacts for later use.

includes (Type:String)
Include artifacts matching this Ant style pattern. Use a comma separated list to add more than one expression.

I know this clean up work will be done later in sepatate PRs, but I'm sure I'll forget to send this comment later, so here it is 😄

[jglick]

About the HTML format, I would suggest a little change

Oh, there are many changes that should be made. The current output is just a proof of concept to validate that the relevant data is included.

[abayer]

So starting some work on gdsl generation and there is one thing we're not reporting for steps, so far as I can tell - return type. It's generally void, but there are some cases (readFile, e.g.) where it's something else, and gdsl, at least, needs that.

[jglick]

there is one thing we're not reporting for steps, so far as I can tell - return type

Sorry, this information is not available by reflection. Anyway several steps return different types depending on the options you selected. I think all we can do is display the help.html and treat the return type as Object for purposes of completion.

I somehow lucked out and got a clean build, so seeking rebees (or whatever you think appropriate) from @abayer / @amuniz. With this in master, various data sinks could be done as parallel PRs.

[abayer]

🐝 it is.

[abayer]

Ah, I see that @rsandell's script does that via Groovy magic and guesswork - https://github.com/abayer/workflow-experiments/blob/master/workflow-gdsl.groovy#L125

[abayer]

@jglick Is there a way to tell whether the step has a return value at all vs a void one? If I can't even tell that, either all steps are going to have to go in the GDSL as return type void or as return type Object...

[amuniz]

🐝

[jglick]

via Groovy magic and guesswork

Only works for steps which happen to use AbstractSynchronousStepExecution or AbstractSynchronousNonBlockingStepExecution; will not work for asynchronous steps, or for steps which choose to use a different StepExecution implementation for whatever reason. (I think it was with @tfennelly, but maybe @amuniz, that I discussed the possibility of deprecating AbstractStepImpl, AbstractStepDescriptorImpl, AbstractStepExecutionImpl, and StepContextParameter in favor of simple nonreflective code, in which case AbstractSynchronousStepExecution and AbstractSynchronousNonBlockingStepExecution would also be deprecated and replaced. In such a case there is no way such guesses would work for any steps.)

Is there a way to tell whether the step has a return value at all vs a void one?

No. All you can do is treat them as returning Object (which subsumes a null return value ~ void).

If information about the return value is critical, then we will need a new API in StepDescriptor. Again there are some existing steps which would have to give the value as Object.class since their return type can vary according to the mode of invocation; in many cases you could pin down a specific type based on a Step instance, but that is useless for your purposes anyway.

Also note that many block-scoped steps—but not all—return any value returned by (some invocation of) their block. So the logical type is something like

<T> T theStep(String someParameter, Closure<T> body)

[abayer]

Ok, for now, I'll just go with Object and we'll see if that creates any problems.