Merging multiple build steps into one (with nested Describables)

[Tim Van Holder]

Hi,

I'm in the process of adjusting a plugin that has a dozen build steps to use a single step instead (all steps are subcommands of a single executable and/or subcommands of those subcommands). There are two parts to this.

The first is writing the new step/builder. The idea is to use a new extension point / describable for each "level" of command. This mostly seems to work fine.
However, I ran into two issues so far:

1. you can use @Symbol to assign a simple symbol to make things like "dotnet(buildServer(shutdown())" work; but there seems to be no checking that such a symbol is valid/usable, neither at build time nor at run time. For example, I had "package" as symbol (for "dotnet list package"); it was only when I tried to use it in a pipeline that any error occurred (because package is a reserved word). It would certainly be useful to get a diagnostic for that at maintenance/build time (this assumes Groovy is the only supported/intended context for those symbols; otherwise checking for reserved words might be tricky).
   
2. I'm using <f:dropdownDescriptorSelector> for the nested describables which mostly works nicely. However, this does not surface any help files for the selected describable in the UI. Is that a bug or by design? I tried adding
   

   <div class="setting-main help-sibling">
     <f:helpLink url="${descriptor.getHelpFile()}"/>
   </div>
   

   to the config.jelly for such a describable, but although that does render the question mark icon, it doesn't actually do anything when clicked. If it's a bug (or missing feature), what's the appropriate place to report it? Otherwise, what's the best way to make it work? Should I copy the  dropdownDescriptorSelector jelly and modify that?
   

The second part is dealing with deprecating the "old" build steps.

For free-style projects this was very easy. I just adjusted their descriptors to return false from isApplicable(). That hides them from the UI for new configuration but leaves existing projects usable. I then added a "this step is deprecated" banner to their config.jelly (note: it would be really useful if the Jenkins Design Library also documented style elements, such as using a div with class="alert alert-warning" for a warning banner). Great - clutter removed from the "Add build step" UI.

The only thing that would be additionally useful is an automated migration step; I wonder if there's any way I could have a button/link in the config.jelly that would allow me to construct the new step based on the old step's properties and have the UI take that new step into account for the project being edited?

However, these are all Builders implementing SimpleBuildStep to be usable from pipelines as well. And there seems to be no way to mark those as "do not use". While the snippet generator does have a "deprecated/advanced" section, that is entirely based on a StepDescriptor implementing isAdvanced() - but these are Builders, so they have no StepDescriptor. What are my options for this? I don't think I can just have a second descriptor for the same class, moving the @Symbol to that one. So my only option would seem to be to essentially create a new set of Steps just so they could have descriptors marking themselves as advanced - but that would involve the symbols being associated with those new classes; would that break anything? The old class would remain a Builder and executable the same way, so if the old class name got persisted anywhere (e.g. for a job that was suspended), that should still work. Or should I just not care about clutter in the snippet generator interface at all?

I do still think it would be a useful thing if there was a way to set up a builder/step so that the snippet generator hides it in its entirety. This could be as easy as calling descriptor.isApplicable, passing in either a "fake" AbstractProject implementation (SnippetGeneratorProject or something) or by passing in whatever AbstractProject applies to pipeline projects.

Alternatively, perhaps it could move steps to the deprecated/advanced section if they are marked @Deprecated? Or is all this just a consequence of the steps in question getting run via a meta-step?

[Tim Jacomb]

What version are you building against? I think recent weekly (and the upcoming LTS) has that help issue fixed

RE: design library and warnings, mind filing an issue for that?

--
You received this message because you are subscribed to the Google Groups "Jenkins Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jenkinsci-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jenkinsci-dev/CAKMi--C2%3Dhm77jbPZ1zEvVeZ_8ZMXhg8zzW5%2Bkfi2FeYd%2BExfA%40mail.gmail.com.

[Daniel Beck]

On Sun, Aug 14, 2022 at 6:14 PM Tim Van Holder <tim.va...@gmail.com> wrote:

The only thing that would be additionally useful is an automated migration step; I wonder if there's any way I could have a button/link in the config.jelly that would allow me to construct the new step based on the old step's properties and have the UI take that new step into account for the project being edited?

You may be able to readResolve them to the new type on deserialization. (Won't work for pipelines though).

[Jesse Glick]

On Sun, Aug 14, 2022 at 12:14 PM Tim Van Holder <tim.va...@gmail.com> wrote:

there seems to be no checking that such a symbol is valid/usable, neither at build time nor at run time. […] It would certainly be useful to get a diagnostic for that at maintenance/build time

Might be possible at runtime.

I'm using <f:dropdownDescriptorSelector> for the nested describables which mostly works nicely. However, this does not surface any help files for the selected describable in the UI. Is that a bug

Try updating to latest core.

So my only option would seem to be to essentially create a new set of Steps just so they could have descriptors marking themselves as advanced

Yes.

that would involve the symbols being associated with those new classes; would that break anything?

No, symbols must only be unique per domain.

The old class would remain a Builder

Just make it not be a `SimpleBuildStep`.

is all this just a consequence of the steps in question getting run via a meta-step?

Yes.