diff --git a/content/doc/developer/plugin-development/_chapter.yml b/content/doc/developer/plugin-development/_chapter.yml index c11882af3e2..17a90a7dd07 100644 --- a/content/doc/developer/plugin-development/_chapter.yml +++ b/content/doc/developer/plugin-development/_chapter.yml @@ -1,5 +1,6 @@ --- sections: +- build-process - dependencies-and-class-loading guides: - updating-parent diff --git a/content/doc/developer/plugin-development/build-process.adoc b/content/doc/developer/plugin-development/build-process.adoc new file mode 100644 index 00000000000..ce29c4d0675 --- /dev/null +++ b/content/doc/developer/plugin-development/build-process.adoc @@ -0,0 +1,30 @@ +--- +layout: developersection +title: Plugin Build Process +references: +- url: ../updating-parent/ + title: Guide to Updating Your Maven Parent POM +- url: https://github.com/jenkinsci/plugin-pom/ + title: Plugin parent POM 2.x and up +- url: https://github.com/jenkinsci/maven-hpi-plugin/ + title: Maven HPI Plugin +--- + +Most Jenkins plugins are built with link:https://maven.apache.org[Maven]. +They typically use the link:https://github.com/jenkinsci/plugin-pom/[Jenkins plugin POM] as their parent link:https://maven.apache.org/pom.html[POM], which provides a sensible default configuration for the plugin build. +The link:https://github.com/jenkinsci/maven-hpi-plugin/[Maven HPI plugin] is one of the plugins configured there. +It does the heavy lifting, such as bundling plugins in the HPI/JPI archive format used for Jenkins plugins, or allowing developers to run a debug Jenkins instance with the plugin. + +Since version 2.0 of the plugin POM, it's possible to specify the core version dependency of the parent POM independent of its version.footnoteref:[1.x,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. These versions should no longer be used.] +This allows plugins compatible with older Jenkins releases to benefit from fixes and improvements in the parent POM. +The link:https://github.com/jenkinsci/plugin-pom/blob/master/CHANGELOG.md[plugin POM changelog] provides more details. + +== Keeping up to date + +It is generally recommended to frequently update to a recent plugin parent POM for multiple reasons: + +* Plugin developers and users benefit from bug fixes and improvements to the parent POM and the tools and libraries 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 escape-by-default 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 the https://github.com/jenkinsci/plugin-compat-tester[plugin compatibility tester] to determine whether their plugin is compatible with newest Jenkins releases.