Add more spotbugs checks

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Add more thorough spotbugs checks

The Jenkins plugin pom enables static analysis with spotbugs. Plugin maintenance can be improved in some cases by increasing the depth of spotbugs analysis.

Create a branch

In a local copy of your fork of the plugin repository create a git branch for your work with the command:

git checkout -b {task-identifier} master

Increase spotbugs checks

To increase the spotbugs analysis checks, add the spotbugs properties entries in the properties section of the pom.xml file:

   <properties>
     <spotbugs.effort>Max</spotbugs.effort>
     <spotbugs.threshold>Low</spotbugs.threshold>
   </properties>

Review and fix spotbugs warnings

When the spotbugs analysis checks are increased, they often report new issues that need to be resolved or suppressed. Spotbugs checks are included in the Apache Maven verify step. Run the spotbugs analysis checks as part of the Apache Maven verify step with the command:

mvn clean -DskipTests verify

It is generally preferred to fix a spotbugs warning rather than suppress the warning message. However, in those cases where a spotbugs message is incorrect or is infeasible to fix, it can be suppressed with the SuppressFBWarnings annotation. A suppression might look like this:

import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
/* ... preceding a method that returns a Boolean and may return null */
    @SuppressFBWarnings(
            value = "NP_BOOLEAN_RETURN_NULL",

            justification = "Null return indicates others should evaluate further")

Add a spotbugs exclusions file (if needed)

Sometimes the number of spotbugs exclusions make it inconvenient or tedious to place the exclusions in the source files. In those cases, a spotbugs exclusions file can be used to list the spotbugs warnings that are being excluded and the classes, methods, and fields involved.

A good example of the spotbugs exclusions file and its configuration is available from Jenkins core. See the src/spotbugs/excludesFilter.xml source file for examples. The exclusions in the filter file are enabled automatically with recent versions so long as the exclusion file is named src/spotbugs/excludesFilter.xml.

An example excludes filter file is also included here:

<?xml version="1.0"?>
<FindBugsFilter>
  <!--
    Exclusions in this section have been triaged and determined to be
    false positives.
  -->

  <!--
    Here lies technical debt. Exclusions in this section have not yet
    been triaged. When working on this section, pick an exclusion to
    triage, then:

    - Add a @SuppressFBWarnings(value = "[...]", justification = "[...]")

      annotation if it is a false positive.  Indicate the reason why
      it is a false positive, then remove the exclusion from this
      section.

    - If it is not a false positive, fix the bug, then remove the
      exclusion from this section.
   -->
  <Match>
    <Or>
      <And>
        <Bug pattern="ES_COMPARING_PARAMETER_STRING_WITH_EQ"/>
        <Class name="io.jenkins.plugin.example.ExampleAction"/>
      </And>
      <And>
        <Bug pattern="DM_BOXED_PRIMITIVE_FOR_PARSING"/>
        <Class name="io.jenkins.plugin.example.SomeFeature"/>
      </And>
    </Or>
  </Match>
</FindBugsFilter>

Compile the plugin

Use Apache Maven to compile the plugin and run its automated tests with the command:

mvn clean verify

Confirm that no spotbugs warnings are reported. If spotbugs warnings are reported, resolve them.

Create a pull request

Commit that change:

git add {modified-files}
git commit -m "{task-description}"

Push the change to GitHub:

git push origin --set-upstream {task-identifier}

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.