Add introduction to parent POM and Maven HPI plugin #1366
Conversation
There was a problem hiding this comment.
👍
I'm not clear on what the overall structure/plan is for /doc/developer, so I don't know whether this page is intended to be basic for now and expanded upon, but I added some comments on things that would be nice-to-have.
But as discussed at FOSDEM, it's good to have a "upgrade your POM" reference that we can point people at 👍
| Jenkins plugins typically use the Jenkins plugin parent POM, which provides a sensible default configuration for the build. | ||
| Up to Jenkins 1.645, the plugin POM was kept in sync with Jenkins releases, so that the minimum required Jenkins version for a plugin determined the versions of the tools used to build the plugin. | ||
| As of Jenkins 1.646, they've been decoupled: | ||
| Plugin POM 2.0 and newer allow specifying the core version dependency independent of its version, so that even plugins compatible with older Jenkins releases can benefit from fixes and improvements in the parent POM. |
There was a problem hiding this comment.
The uncoupling happened two years ago — it's probably not worth mentioning the historic info (IMO).
There was a problem hiding this comment.
Still relevant in plenty of plugins with old baselines.
There was a problem hiding this comment.
I would explicitly say that Plugin POM 2.x is recommend and required for new plugin hosting requests, WDYT? CC @slide
There was a problem hiding this comment.
This is literally the next paragraph.
There was a problem hiding this comment.
Still relevant in plenty of plugins with old baselines.
Then I think I'm not understanding who this page is aimed at.
If it's new plugin developers, they'll get 2.x (or preferably 3.x) from the archetypes. If it's existing plugin developers, I'm not sure why they'd read this page but most likely it would be because someone's linked them to the next section, telling them about the benefits of updating to a newer parent version.
My point was that the historic information is perhaps interesting to Jenkins core developers, but to everyone else it's irrelevant, and a waste of time for people to read.
There was a problem hiding this comment.
It is reference documentation. It describes how things are.
There was a problem hiding this comment.
Notably, if you follow hosting requests, you will see new plugins still get created with years old parent POMs. (1.x or the first few releases of 2.x.) It's far from irrelevant today.
|
|
||
| Most Jenkins plugins are built with link:https://maven.apache.org[Maven]. The link:https://github.com/jenkinsci/maven-hpi-plugin/[Maven HPI plugin] does the heavy lifting, such as bundling plugins in the HPI/JPI archive format, or running a debug Jenkins instance with the plugin. | ||
|
|
||
| Jenkins plugins typically use the Jenkins plugin parent POM, which provides a sensible default configuration for the build. |
There was a problem hiding this comment.
"use the Jenkins plugin POM as their parent"?
Linking to the plugin-pom repo here would be nice (even if it is in references).
There was a problem hiding this comment.
Briefly mentioning what a POM is, or at least providing a link (e.g. https://maven.apache.org/pom.html), would be helpful.
There was a problem hiding this comment.
It seems like these paragraphs should perhaps be in a different order, e.g.:
Jenkins plugins are built with Maven. They use the Jenkins plugin POM as their parent. This provides various tools, including the Maven HPI Plugin, which does all the magic.
There was a problem hiding this comment.
Similarly, since this is the page about how the plugin build process, it seems like there should be an explanation of what a "HPI/JPI" is, and potentially why we have a special plugin for it…
|
|
||
| == Keeping up to date | ||
|
|
||
| It is generally recommended to continually update to recent plugin parent POMs for multiple reasons: |
There was a problem hiding this comment.
Remove "generally".
continually -> frequently?
"to a recent plugin parent POM"
There was a problem hiding this comment.
There should be instructions about how to find the latest plugin-pom version.
(https://github.com/jenkinsci/plugin-pom/blob/master/CHANGELOG.md)
There was a problem hiding this comment.
"Generally" is code for "Perhaps not if you're the person from HOSTING-481".
| * Plugin developers and users benefit from bug fixes and improvements to the parent POM and the tools it specifies | ||
| * Additions to the default build like static code analysis and general tests aim to improve the overall quality of plugins. | ||
| // TODO Need a good reference for that before including it as example: | ||
| // For example, plugins depending on the plugins parent POM 1.596 (with maven-hpi-plugin 1.110) or newer will need to specify the <code>escape-by-default</code> in all Jelly files for the InjectedTest to pass. Plugins depending on older releases may have hidden XSS vulnerabilities. |
| * Additions to the default build like static code analysis and general tests aim to improve the overall quality of plugins. | ||
| // TODO Need a good reference for that before including it as example: | ||
| // For example, plugins depending on the plugins parent POM 1.596 (with maven-hpi-plugin 1.110) or newer will need to specify the <code>escape-by-default</code> in all Jelly files for the InjectedTest to pass. Plugins depending on older releases may have hidden XSS vulnerabilities. | ||
| * Recent versions of the tools (inherited from the parent plugins POM) allow developers to use more advanced tools like PCT (plugin compatibility tester) to determine whether their plugin is compatible with newest Jenkins releases. |
There was a problem hiding this comment.
Is there a good PCT link we can add?
There was a problem hiding this comment.
After my recent patches to PCT landing is good enough: https://github.com/jenkinsci/plugin-compat-tester . I am about extending this section later
|
|
||
| It is generally recommended to continually update to recent plugin parent POMs for multiple reasons: | ||
|
|
||
| * Plugin developers and users benefit from bug fixes and improvements to the parent POM and the tools it specifies |
There was a problem hiding this comment.
Updated test harness versions is another benefit. Though arguably that's covered by "the tools it specifies".
No description provided.