With the release of SonarQube 4.0, we now have three different paradigms for SonarQube analysis. There’s full analysis, which updates the central database and provides organizational visibility of code quality. There’s preview analysis, which tells you whether the code in question is good enough to move forward with (E. G. merging it into the Git master). And now that SonarQube has the ability to limit preview analysis to only changed files, there’s also incremental preview analysis, or “incremental analysis”.

Let’s talk about when you would use each one. I’ll start with the new guy: incremental analysis.

Incremental

The use case for this is on the developer’s machine, before code is checked in. If you’ve only changed one or two files, waiting for the preview analysis (previously called “dry run” in some contexts) seems burdensome. I’ve been there myself on my day job, with some medium-large projects. Even though I’ve got a fairly fast machine, preview analysis takes long enough to be irritating, but not long enough for a bathroom break and a chat. My colleagues on larger projects are closer to the bathroom break range, and since they can make many small changes in a day, they’ve complained that the time to run a pre-commit preview analysis is a productivity drag. (So guess what doesn’t happen.)

Fortunately, the developers at SonarSource have heard those complaints. (Hmmm… They maintain a large project too…) Now, you can restrict a preview analysis to just the files you’ve made your small changes in, and you have your results almost immediately. The mechanism is a new analysis property that was introduced in 4.0: sonar.analysis.mode. It has three valid values:

• analysis – this is the default. It tells SonarQube to perform a full, store-it-in-the-database analysis.
• preview – this was previously known as the dryRun mode. It performs a full analysis, but doesn’t store the results in the database.
• incremental – this is the new option. It performs a preview analysis on only the changed files, allowing impatient developers to perform a pre-commit check of their changes without sinking a lot of time into the endeavor.

Incremental mode is already available if you’re using Issues Report, and it’s the new default in the Eclipse plugin.

Preview

So where does that leave preview analysis? Now that the developers’ desktop needs are satisfied, is there still a need for a preview analysis of the whole codebase? Absolutely. But the use case moves to the Continuous Integration server. Similar to the way unit testing helps you ensure your new code hasn’t broken what was already working, a preview analysis helps you ensure your new code hasn’t caused a regression in code quality levels (by introducing new issues, new duplications, and so on.)

To add a preview analysis to a CI build, you’ll use most of the same properties you need for a full analysis. You won’t need the database connection credentials – after all, you won’t be updating the database – and you’ll need to add in a couple of other properties, the most notable of which is sonar.analysis.mode=preview. It’s this property that distinguishes an analysis from a preview analysis at a functional level.

You’ll also need the Build Breaker Plugin installed on your SonarQube instance. It will mark the build failed if new alerts are raised during analysis (you can configure the behavior on a project-by-project basis). Install Build Breaker, set up alerts in the relevant quality profiles and you’re ready to go. Those alerts can be as simple as Blocker Issues > 0, or more complex, like Coverage on new code < 90%.

When the build fails, your continuous integration server will send out the usual failure notice to the developer(s) involved.

The only downside to this setup is that your build server admin will need to maintain extra jobs. In addition to the Continuous-Integration-with-Preview-Analysis job, he’ll also need to set up a separate, nightly build to run the main analysis. You know, the one that actually updates the SonarQube database and provides organizational visibility of code quality.