Using Qodana Baselines to Ignore Legacy Issues While Enforcing New‑Code Quality

When a codebase already carries hundreds of inspections, a fresh Qodana run can drown pull‑request comments in legacy warnings, making it hard to spot real regressions. Teams often want to keep the existing debt visible for future cleanup but enforce a strict “no new warnings” rule for new code. Qodana’s baseline feature solves exactly this problem: it records the current set of issues in a file and, on subsequent runs, reports only those that are newly introduced.

Generating and committing a baseline

First, run Qodana with the --baseline flag on a clean checkout of your project. The command writes a baseline XML file (by default named qodana-baseline.xml) into the output directory you specify.

# Run from the repository root; adjust the output directory as needed
qodana --baseline --output-dir qodana-results

You need read access to the source files and write permission to the output directory. No special privileges are required beyond those used for a normal Qodana analysis. After the command finishes, verify that qodana-baseline.xml appears in qodana-results.

Commit this file to version control so every developer and CI agent uses the same reference point:

git add qodana-results/qodana-baseline.xml
git commit -m "Add Qodana baseline for legacy issue suppression"

Configuring the baseline in qodana.yaml

Instead of relying on the CLI flag each time, you can declare the baseline in your project’s qodana.yaml. This makes the behavior part of the project configuration and ensures that IDE integrations and CI pipelines pick it up automatically.

# qodana.yaml
baseline: true
# Optional: adjust severity thresholds to exclude low‑priority checks from the baseline
# inspections:
#   - id: "JavaDoc"
#     enabled: false

With baseline: true set, Qodana automatically looks for qodana-baseline.xml in the working directory (or the path you specify with baselinePath) and compares the fresh analysis against it.

Worked example: catching a new TODO

Assume the baseline has been committed and the CI runs Qodana on every pull request. A developer adds a new TODO comment, which triggers the "Java: TODO comment" inspection.

1. Developer pushes a branch with the change.
2. CI checks out the branch, runs Qodana.
3. Qodana loads the baseline, runs fresh analysis, and compares the two sets.
4. Only the newly introduced TODO appears in the report; all pre‑existing warnings are suppressed.
5. The CI posts a comment on the PR linking to the new issue, allowing the team to address it immediately.

To verify this locally, you can deliberately introduce a violation after the baseline is committed:

# Add a TODO to a source file
sed -i '1s/^/\/\/ TODO: investigate later\n/' src/Main.java
# Run Qodana again
qodana --output-dir qodana-results
# Inspect the results; you should see only the TODO violation
cat qodana-results/report.html | grep -i todo

If you remove the baseline file and run Qodana once more, the full set of warnings (including the TODO and all legacy issues) reappears, confirming that the baseline is what suppressed the known problems.

Trade‑offs and maintenance considerations

• Stale baselines: If you intentionally fix existing issues and do not regenerate the baseline, those fixes remain hidden, giving a false impression of improvement. Schedule a baseline refresh after major refactoring or when you close a significant number of warnings.
• File size: Projects with many inspections can produce large XML baselines. Periodically review the file for obsolete entries (e.g., checks you have disabled) and consider regenerating it to keep the size manageable.
• Format immutability: Qodana currently only supports the XML baseline format. Switching to another format would require discarding the old baseline and creating a new one from scratch.

Actionable next steps

1. Generate a baseline on your main branch: qodana --baseline --output-dir qodana-results.
2. Commit qodana-baseline.xml to your repository.
3. Add baseline: true (or baselinePath: qodana-results/qodana-baseline.xml) to qodana.yaml.
4. Verify the setup by adding a small, intentional violation and confirming that only that violation appears in the Qodana output.
5. Set a reminder (e.g., quarterly) to regenerate the baseline after you resolve a batch of legacy warnings.

By treating the baseline as a living artifact—updated when you genuinely improve the codebase—you gain the ability to enforce a clean‑slate policy for new work without being overwhelmed by historical debt.