New Checkstyle and Spotbugs pattern migration

New Checkstyle and Spotbugs pattern migration

Checkstyle and Spotbugs are linting tools used to report code formatting and potential bugs in the code. The Azure SDK for Java team has updated the Checkstyle and Spotbugs pattern to better align with the Azure SDK for Java codebase. This document will guide you through the process of updating your project to use the new Checkstyle and Spotbugs pattern.

Benefits

1. Checkstyle and Spotbugs suppression files are now in the same location as the library. This makes it easier to find and update the suppression files and makes them specific to the library, preventing accidental suppression of issues in other libraries.
2. Updates to suppression files no longer trigger code-quality-reports to run which validates that changes to the global suppression files don't break other libraries. This pipeline takes a while to run, slowing down the dev cycle.

Migration guide

Migrating the project will require updating the POM file of the project and generating the initial suppression files. In late 2023, Spotbugs was also disabled due to an urgent requirement to upgrade it, meaning there may be many Spotbugs issues to fix. But, the suppressions file generator should disable all Spotbugs issues for now, allowing them to be fixed later if they are considered a true issue.

Here is an example of Storage migrating to the new pattern: https://github.com/Azure/azure-sdk-for-java/pull/39298

Update project configurations

Start by adding the following properties to your project's POM file.

    <checkstyle.suppressionsLocation>checkstyle-suppressions.xml</checkstyle.suppressionsLocation>

    <spotbugs.skip>false</spotbugs.skip>
    <spotbugs.excludeFilterFile>spotbugs-exclude.xml</spotbugs.excludeFilterFile>

• checkstyle.suppressionsLocation is the location of the Checkstyle suppression file, the tool generates it to this location.
• spotbugs.skip is a flag to enable or disable Spotbugs. Set it to false to enable Spotbugs.
• spotbugs.excludeFilterFile is the location of the Spotbugs suppression file, the tool generates it to this location.

Generate the suppression files

Run the following command to generate the suppression files.

python /eng/scripts/linting_suppression_generator.py --project-folder "<path to project file from root of repo>"

Example:

python /eng/scripts/linting_suppression_generator.py --project-folder "sdk/storage/azure-storage-blob"

Gotchas

The Checkstyle check JavadocPackageCheck checks that the package has a package-info.java file. But the way Checkstyle reports errors it requires a file to associate them to, and unfortunately, that association isn't consistent across OSes. This means if the suppression file was generated on Windows and CI runs on Linux the suppression file may not prevent this error from being reported. To fix this issue add the missing package-info.java to the package and include a Javadoc comment in it.

An example of fixing this can be seen in this commit: https://github.com/Azure/azure-sdk-for-java/pull/39298/commits/5e05c8a2fe35e14e118c3914a44198174ff72795