[JENKINS-38110] Add a libraries section

[abayer]

• JENKINS issue(s):
  • JENKINS-38110
• Description:
  • Initial work on adding a libraries section to Declarative. Current syntax looks like:

libraries {
    lib('foo@1.2.3')
    lib('bar')
}

Yes, I'd prefer not to have that pointless lib there, but the alternative is something like libraries 'foo@1.2.3', 'bar' and as we may remember from agent back in the day, I do not care for that syntax at all. Plus, we may end up wanting to include the ability to specify a LibraryRetriever (see LibraryRetriever.java in workflow-cps-global-lib for details), in which case going to lib(identifier:'foo@1.2.3', retriever:[$class:...]) is a much better option than anything else I could find.

• Documentation changes:
  • Oh my yes will there need to be doc changes. But not 'til this actually is much closer to done.
• Users/aliases to notify:
  • @reviewbybees
  • @rsandell
  • @bitwiseman
  • @HRMPW
  • @kzantow @michaelneale @i386 (particularly for editor/BO concerns)

[abayer]

Note that this is very preliminary at this point - like, it doesn't
actually call the library step yet, since we don't yet have a release
of workflow-cps-global-lib-plugin with that included to depend on. We
also don't have parsing tests or any of that jazz. But that's ok.

[kzantow]

Could the LibraryRetriever have some special metadata that could list available libraries in some cases? I guess we'd just allow a random string for now or am I missing something?

[HRMPW]

@kzantow LibraryRetriever lets you load a library from an arbitrary source. lib itself could possibly know the list of available libraries based on the configuration in the folder or global but I don't think you can pre-populate LibraryRetriever

[abayer]

Yeah, the LibraryRetriever could specify things like credentials, an alternate repo (since it'd be GitHub by default), etc... I'm also trying to figure out what to do about validation of the library itself - it looks like I'd need the job to be able to validate the identifier string if folder context needs to be taken into account.

[abayer]

@HRMPW LibraryStep allows an optional LibraryRetriever argument. Assuming we do add support for it, the syntax would probably be lib("foo@1.2.3") or lib("foo@1.2.3", modernSCM([$class: 'GitSCMSource', credentialsId: '', excludes: '', id: 'id', ignoreOnPushNotifications: true, includes: '*', remote: 'https://nowhere.net/'])). Ideally, we'll get @Symbols and proper DataBoundConstructor setups on the SCMSource implementations to make that syntax smoother, though.

[kzantow]

Sorry, was conflating things... my goal for the editor is - as much as possible - to give the user choices for things to minimize errors, so as much info as we can pull from jenkins, the better... e.g. which LibraryRetriever types are present, possibly what they resolve, etc., and any known entries for the lib itself.

[abayer]

@kzantow Yup, that we can do to at least some extent - leveraging LibraryStep's auto-complete logic

[jglick]

we don't yet have a release of workflow-cps-global-lib-plugin with that included to depend on

Try: 2.7-20170301.201004-1

[abayer]

Thanks, @jglick - done.

[abayer]

Moving out of work-in-progress - decided to leave out LibraryRetriever for the initial release and wait to see if there's demand.

[reviewbybees]

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.

[rsandell]

If we go with adding folder context to the validation we should also revisit the validation of the credentials function in environment so we can fail there as well fast if the user has entered an non existent credential id.

[rsandell]

🐝

So I'm guessing we deliberately don't support static imports from the dynamic libraries.

[rsandell]

Wasn't it lib('string')?

[abayer]

Fixed!

[jglick]

How would you compatibly extend this to support LibraryRetriever?

[abayer]

By supporting both the current array-of-strings and a new format for LibraryRetriever - anyOf will let us do that easily enough.

[jglick]

Released.

[abayer]

Updated.