The Maven project object model ("POM") defines a parent project object model that provides default settings. An update of the parent POM will allow this plugin to compile with recent Java versions. The most recent parent POM files also provide additional static analysis like spotbugs and optional automated source code formatting.
In a local copy of your fork of the plugin repository create a git branch for your work with the command:
git checkout -b update-parent-pom master
Jenkins plugins are built with Apache Maven.
Download Maven from the Apache Maven website.
Make sure to download one of the binary archives (with bin
in their name).
Many Linux distributions provide packages for Maven for an easier install and upgrade experience. Consult your distribution’s documentation for details. On macOS, the Homebrew package manager offers Maven packages. Make sure a recent version of Maven 3, ideally 3.8.6 or newer, is provided if you decide to go this route. |
Next, you will need to extract Maven and take note of its location. When you extract the Maven files, make sure you extract them directly into the target directory. For example, extract the files straight into C:\Program Files (x86)\Maven; do not extract the files to a different location and then copy the files.
Then, add the full path of the bin/
subdirectory extracted (for example, ~/Applications/apache-maven/bin
or C:\Program files\Maven\bin
) to the PATH
variable in your OS.
This will let you invoke Maven using mvn
.
The rest of the tutorial assumes that Maven is on your PATH
environment variable.
Apache Maven needs to be configured for Jenkins plugin development. The hpi plugin for Apache Maven requires some additional global configurations to function correctly with older Jenkins plugin environments.
Improper configuration settings can cause Maven to report errors or warnings, including failure to download artifacts during the update process.
To avoid issues, include the following content in the settings.xml
file in your ~/.m2
directory (Windows users will find them in %USERPROFILE%\.m2\settings.xml
):
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
http://maven.apache.org/xsd/settings-1.0.0.xsd">
<pluginGroups>
<pluginGroup>org.jenkins-ci.tools</pluginGroup>
</pluginGroups>
<profiles>
<profile>
<id>jenkins</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>repo.jenkins-ci.org</id>
<url>https://repo.jenkins-ci.org/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>repo.jenkins-ci.org</id>
<url>https://repo.jenkins-ci.org/public/</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
</settings>
Use Apache Maven to compile the plugin and run its automated tests with the command:
mvn clean verify
When modernizing older plugins, You may need to use Java 8 to compile the plugin initially. Once the parent POM has been updated, you’ll be able to compile and test with recent Java versions.
Use Apache Maven to update the parent POM:
mvn -ntp versions:update-parent
[INFO] Scanning for projects... [INFO] [INFO] ---------------< org.jenkins-ci.plugins:your-plugin >---------------- [INFO] Building Schedule Build Plugin 1.0.0-SNAPSHOT [INFO] --------------------------------[ hpi ]--------------------------------- [INFO] [INFO] --- versions-maven-plugin:2.8.1:update-parent (default-cli) @ your-plugin --- [INFO] Updating parent from 3.50 to 4.47 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 3.013 s [INFO] Finished at: 2021-09-26T20:03:00-06:00 [INFO] ------------------------------------------------------------------------
Review the change that Apache Maven performed for you with the command:
git diff
diff --git a/pom.xml b/pom.xml index e6a8356..3a42d47 100644 --- a/pom.xml +++ b/pom.xml @@ -3,7 +3,7 @@ <parent> <groupId>org.jenkins-ci.plugins</groupId> <artifactId>plugin</artifactId> - <version>3.50</version> + <version>4.80</version> </parent> <artifactId>your-plugin</artifactId>
Use Apache Maven to compile the plugin and run its automated tests with the command:
mvn clean verify
java.level
propertyIf there is a <java.level>
property defined in the POM, remove it.
The minimum version required for a specific pom is now implicit in the POM.
The plugin maintainer does not need to specify a <java.level>
property.
In many cases, other changes will be needed to the pom.xml file in order to use the most recent parent POM. Some of the other changes may include:
Resolve spotbugs warnings
Resolve upper bounds dependency warnings
Prevent cross-site scripting by escaping expressions in Jelly pages
Resolve ambiguous property encodings by converting translations with native2ascii
Commit that change:
git add pom.xml
git commit -m "Use most recent parent pom"
Push the change to GitHub:
git push origin --set-upstream update-parent-pom
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 remote: remote: Create a pull request for '{task-identifier}' on GitHub by visiting: remote: https://github.com/user/your-plugin/pull/new/{task-identifier} remote: To github.com:user/your-plugin.git * [new branch] {task-identifier} -> {task-identifier} Branch '{task-identifier}' tracking remote branch '{task-identifier}'.
Notice that the output of the command includes the URL, which can be used to open a pull request. Copy that URL in your web browser and submit a pull request.