Hacktoberfest: Plugin Development Lessons Learned & Best Practices

[steven...@gmail.com]

Hello all! 

In preparation for Hacktoberfest, the Pipeline Authoring SIG was discussing good first issues and opportunities for improvement.  The topic of documentation came up, specifically Plugin Developer documentation. 

If you've written a plugin before, there many lessons learned and best practices that would have been great to know up front. 

I'm starting this thread to hear from you all: 

What lessons have you learned while developing a Jenkins plugin that you wish you knew up front? 

Some high level topics to help kickstart the conversation: 

1. Unit Testing
   1. Jenkins Test Harness
   2. Specific examples testing particular use cases
   3. How to mock a remote source code repository
   4. Validating configurations in the UI work as expected
2. Plugin Development Lifecycle
   1. Productivity tips for how to simplify plugin development
3. Backwards maintainability best practices
4. Ecosystem compatibility best practices 

We would love to hear examples of topics that could be good first issues for folks to help build out the plugin developer document. 

Thank you for your help!

[Matt Sicker]

One thing I noticed pretty early on that's not super consistent
elsewhere is using serialization proxies for storing and loading
config data rather than relying on the autogenerated XML from your
class structure. It's a best practice for real serializable classes
(even though Jenkins/XStream support non-serializable classes, too),
and it helps avoid JEP-200-related errors or the need to attempt to
request ConcurrentHashMap.newKeySet() to be added to the allow list
(I've done that before and almost re-requested in multiple times;
serialization proxy is the way to go).

There's a little bit of info documented about making sure to use the
Secret class for storing sensitive data rather than String or similar.
For credentials management in general, I highly recommend linking or
integrating content from the credentials manual, specifically
https://github.com/jenkinsci/credentials-plugin/blob/master/docs/consumer.adoc

There are bound to be a collection of gotchas that would be great to
document in a central location. For example, Stapler databinding
involving a collection of items will not allow the collection to be
cleared unless you explicitly reset the collections before binding the
JSON like in https://github.com/jenkinsci/extended-security-settings-plugin/blob/f2a07b0dbb043ee16cd8d67deca754bb50b6c340/src/main/java/io/jenkins/plugins/extendedsecuritysettings/ExtendedSecuritySettings.java#L90-L95

For testing configurations, there's the JenkinsRule.configRoundtrip
family of functions:
https://javadoc.jenkins.io/component/jenkins-test-harness/org/jvnet/hudson/test/JenkinsRule.html#configRoundtrip--

See also configuration-as-code:
https://github.com/jenkinsci/configuration-as-code-plugin/blob/master/docs/PLUGINS.md

> --
> 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/df7c8aa0-2795-4e00-8856-d6656d110182n%40googlegroups.com.



--
Matt Sicker
Senior Software Engineer, CloudBees

[steven...@gmail.com]

Thank you Matt! These are great.