Choose Which Checks Block a Merge

Your CI runs the tests, mypy, Ruff, a coverage report and a complexity score. A pull request fails on the complexity score, and its author adds # noqa to get it merged. The check fired, and nobody learned anything. Not every check deserves the same response, so decide what each one is for before you decide whether it blocks a merge.

Required checks and review signals

A required check blocks the merge until it passes. Good candidates are the tests, the type check, the package build and the formatter. Each one needs a failure the author can reproduce on their own machine and a clear way to fix it. The formatter enforces a style. Passing it says nothing about whether the code works.

A failing test can mean a bug, a flaky test or a broken environment, so track flaky runs separately from real failures. Re-running a job until it passes hides a check that is unreliable.

A review signal points a reviewer at something that needs judgment, such as new complexity, duplicated logic, an untested branch or a module that keeps growing. Show the findings and where they are. A score from 0 to 100 can sum them up, but explain how you weight each finding, and never let an average hide one serious finding.

The same rule can play either role. Start a new rule as a review signal while you learn how often it is useful. Make it required once you know its scope, the fix it expects and how an author asks for an exception. Some risks justify blocking from the first day.

Judge a rule by what it does for you

For each candidate rule, ask:

• What failure does it catch, and how serious is that failure?
• How often is a finding worth acting on, and how do you know?
• Can the author reproduce the result and fix it?
• What important cases does it miss?
• Who updates it when tools, dependencies or conventions change?

Say what went wrong and how to fix it

Keep the rule's code, such as E722, so authors can look it up. Then explain the finding in the context of their code. A useful message for a bare except: reads:

This handler also catches KeyboardInterrupt and SystemExit. If it ignores them, Ctrl+C or an explicit exit stops working. Catch the exceptions you expect, or re-raise after any cleanup that must run.

except Exception lets those two through, but it can still hide unrelated errors, so catch only the exceptions the code knows how to handle. See Ruff's bare-except rule.

Be as exact with other findings. Python creates a mutable default argument once and shares it across calls, so if the function changes it, later calls see earlier data. That sentence explains the risk better than "mutable defaults are bad".

Count the mistakes against the right total

A good merge policy tells an author what a failed check means and what to do next, and it lets maintainers remove a check whose findings nobody acts on.