Hey brianjmurrell, I just started maintaining this plugin recently and I share your frustration at the terse documentation for the various recipient providers. I don't understand all of them yet myself! Don't be afraid to dive into the source code if some particular aspect of their behavior is unclear. And if you see a way that the descriptions could be improved, feel free to file a PR to clarify the help text.

(Another, slightly more advanced, way of learning about these recipient providers is to read (or write!) an integration test for one of them. This requires some basic knowledge of Jenkins internals but it can be very helpful. For example, I recently wrote UpstreamComitterRecipientProviderTest, which taught me a lot about how UpstreamComitterRecipientProvider works and allowed me to step through it in the debugger while running various Pipeline jobs. Test coverage for the recipient providers is incomplete, but perhaps an existing test will answer some of your questions. And if not, adding test coverage gives you a chance to answer your questions about the recipient provider with the benefit of an IDE's debugger.)

Something like value_of([$class: 'DevelopersRecipientProvider']) could be implemented as a new step, at the same level as EmailExtRecipientStep, but that may be overkill: steps require a lot of boilerplate code, and I don't get the sense that a value_of step would be used all that much except during the development of a Pipeline job. Another downside is that this would only work for Pipeline jobs, not Freestyle jobs (note that this plugin supports both).

The "dry run" mode you have proposed seems to be a better fit. It could be implemented in ExtendedEmailPublisher, which is used for both Freestyle and (via EmailExtRecipientStep) Pipeline jobs. This would be simpler to implement since it doesn't require a custom step; rather, in ExtendedEmailPublisher#sendMail we could let the code run past the part where it prints "Sending email to:" and then just return early in dry-run mode before it gets to Transport transport = session.getTransport(); (where it makes the connection to the mail server and sends the message). This also has the benefit of being a fairly realistic dry-run, since we would execute all normal code paths right up to the point where the message would otherwise be sent. If you're interested in working on a dry-run mode, PRs are welcome! I'd be happy to review and eventually release such a feature.

Actually looks like this already exists (but is not documented!) in the form of the emailextrecipients step.

basil Can you expand?

I can clearly see that the various recipient providers are documented there, but nothing about how to get their values, or do a dry-run of any sort that results in getting the values without actually ending e-mail (spamming) them.

Well, I did write that emailextrecipients is not documented, didn't I? Unfortunately you're going to have to read the source code to figure out how to invoke it. From first glance it looks like it is invoked with a list of recipient providers and returns a string of the email addresses that the message would be sent to, but I've never actually tried it. (It was written by the previous maintainer of this plugin.) If you figure out how to use it, feel free to submit a PR to add some documentation!

Well, calling it undocumented and then pointing at something written about it was confusing. It's probably more accurate to say that it's poorly documented.

I added feedback about that page to that effect. However the very long list of unfixed documentation feedback comments doesn't leave me with a warm feeling that the time i spent leaving a comment was time well spent. That spreadsheet looks like a /dev/null to be honest given the number of comments on even just the https://www.jenkins.io/doc/pipeline/steps/email-ext/ page that have not been acted on.

Anyway, I will look into the emailextrecipients step a bit more. Thanks for the pointer.

pointing at something written

Well what I pointed at was not written (by a human) but rather autogenerated (by a computer) from EmailExtRecipientStep, as I will explain below.

I added feedback

Better would be to open a pull request fixing the problem. Documentation for Pipeline steps is not managed centrally at jenkins-infra/jenkins.io but rather autogenerated from the Jelly code in each plugin's source tree. To fix this, you'll need to add two files to jenkinsci/email-ext-plugin:

• src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help.html (main description for the step)
• src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help-recipientProviders.html (description for the recipientProviders argument to the step)

Once added, this help text will be visible both in the Snippet Generator (in the Jenkins UI) and in the (autogenerated!) Pipeline Steps Reference.

have not been acted on

Because that feedback page is primarily intended for feedback about content managed centrally at jenkins-infra/jenkins.io. Descriptions for Pipeline steps and their arguments do not fall under this category, as explained above.

Anyway, I will look into the emailextrecipients step a bit more. Thanks for the pointer.

You're welcome, and good luck! Let me know if you need any more help filing the PR I described above.