Plugin Release Tips

Before you release a plugin, you should exercise it in ways that you probably didn’t try while you were developing. Walking through these steps yourself can save you a first round of bug reports from your users, and thus make your plugin higher quality and lower cost to deploy.

Test with agents

Be sure to test the plugin with agent nodes running on remote machines before you release.

Watch for exceptions in logs

Watch the Jenkins console (not just the build output) for exceptions.

Test with java -jar jenkins.war (not just hpi:run)

Just testing a plugin with mvn hpi:run is insufficient. It will not expose classloader issues. Run Jenkins with java -jar jenkins.war and install your plugin into it.

Test with real builds in a non-production server

Test a new plugin in a non-production clone of a production server, with the actual projects that the plugin will run on in production. Often plugin bugs are revealed by real data that weren’t revealed by test data. Beware hubris! When you are testing a plugin and trying to simulate real-world usage, you have to restart Jenkins whenever you think you’ve got a release candidate. Doing this on a production server will aggravate users and make Jenkins look flaky.

Publish release notes via GitHub releases

If you don’t cut releases via CD yet, we recommend using GitHub releases for release notes. The plugin portal has a native integration with GitHub releases, making it easier for users to keep track of changes in the plugin. Simply add the "Publish changelogs to GitHub Release" workflow to your repository, by replacing "yourPlugin" with your plugin name: https://github.com/jenkinsci/yourPlugin/actions/new and follow the steps in the workflow. Publishing release notes in a separate file, such as "Changes.md", is considered dated and not recommended. GitHub releases allow users to quickly view what has changed, including new features or bug fixes. That makes it easier for them to decide whether to upgrade.