ESLint warn severities and the CI --max-warnings gate: advisory alerts or errors-only policy?

Question

ESLint documents three per-rule severities — off, warn, and error — set in eslint.config.js (flat config, the default in ESLint v9+) or a legacy .eslintrc file. The intent is that error fails the run while warn surfaces advisory findings, letting teams introduce new or stylistic rules without breaking existing code.

The friction sits between the two integrations consuming these severities. Editor extensions such as the VS Code ESLint extension render warn inline in the same squiggle channel as error, so a large warning backlog can become visual noise that developers learn to dismiss. In CI, the documented --max-warnings flag makes the process exit non-zero once total warnings exceed a threshold, but the count spans all linted files, so one noisy generated or vendored file can trip the gate unless excluded through ignores.

That leaves a policy decision ESLint itself does not prescribe: some teams adopt an errors-only setup where every rule is either enforced or off, arguing that ungated warnings inevitably decay into ignored noise.

When does a warn severity paired with a --max-warnings ratchet produce better long-term signal than an errors-only policy?
Should the CI warning budget be zero, or a tracked decreasing count during a rule rollout?
What criteria should trigger promoting a rule from warn to error?

Muntasir · Answer

Answer

Use a non‑zero warning budget together with a decreasing --max-warnings threshold while keeping new rules at warn severity. This gives a visible, failing CI signal when the warning count stops improving, which an errors‑only policy cannot provide during early rollout. Switch to an errors‑only policy only when the team cannot tolerate any advisory output or when warnings are dominated by noisy generated/vendored code that cannot be ignored.

Confirmed facts

ESLint treats error as a failure (non‑zero exit) and warn as advisory.
The CLI flag --max-warnings <n> makes the process exit non‑zero when the total warning count exceeds n.
In both flat config (ESLint v9+) and legacy .eslintrc the severity per rule is set via "error" or "warn" (or "off").
The VS Code ESLint extension renders warn with the same squiggle style as error.

Likely explanation / recommendation

A non‑zero warning budget paired with a ratcheting --max-warnings limit lets teams surface new rules incrementally while still failing CI when the warning count stops decreasing. This provides a signal that an errors‑only setup would miss during the rollout phase, because errors‑only would either block the merge immediately (if set to error) or hide the rule entirely (if left off).

Steps for this case

Add the new rule to your ESLint config with severity "warn".
Determine a starting warning budget that reflects the current count (e.g., run npx eslint . --max-warnings 0 locally, note the count, then set --max-warnings <current‑count> in CI).
In CI, configure the lint step to use a decreasing threshold, for example reduce the allowed warnings by 10 % each week or by a fixed number after each successful merge.
Monitor the warning count in CI logs; when the count stays below the threshold for a defined period (e.g., two weeks) and fixing the remaining warnings does not require large‑scale refactor or changes to generated files, promote the rule to "error".
If a single generated or vendored file dominates the warning count, add an eslintIgnore pattern for that file and recompute the budget.

When to ask for a missing detail

Only ask for the proportion of warnings coming from ignored/generated files if that proportion is high enough to make the --max-warnings gate unreliable; otherwise the above steps suffice.

ESLint warn severities and the CI --max-warnings gate: advisory alerts or errors-only policy?

1 answer

Answer

Confirmed facts

Likely explanation / recommendation

Steps for this case

When to ask for a missing detail

Your perspective belongs here.

0 question comments