Merge pull request #1366 from daniel-beck/build-process-intro

Add introduction to parent POM and Maven HPI plugin

content/doc/developer/plugin-development/_chapter.yml

@@ -1,5 +1,6 @@
 ---
 sections:
+- build-process
 - dependencies-and-class-loading
 guides:
 - updating-parent

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 <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 the https://github.com/jenkinsci/plugin-compat-tester[plugin compatibility tester] to determine whether their plugin is compatible with newest Jenkins releases.