Write the instruction before choosing the file pattern#
Consider a service that deploys database migrations before replacing its workers. A pull request removes orders.status and updates the new worker to read orders.state. The new code and schema agree, yet a worker from the previous release still needs the column the migration removes.
“Check migrations for breaking changes” leaves the reviewer to guess what counts as a break. Give the reviewer a question it can answer from the change.
For a column rename or drop, find readers and writers that can still run when the migration takes effect, including the rollback version. Cite the SQL and the affected query. If deployment order is unknown, identify what would establish it.
The instruction works in a repository review guide or in a tool that accepts custom rules. The SQL and query establish a code dependency. To say it affects a running worker, a reviewer also needs its deployed version and the order of the rollout. The PostgreSQL rollback exercise demonstrates that distinction with two versions of one query.
Scope one rule to migration files#
Suppose migrations live under db/migrations/. In a reviewer that supports path-scoped rules, attach the instruction to SQL files there. Leave the rest of the pull request available to the reviewer so it can follow a reference from the migration into application code.
Here is a complete .proofline.yaml example. The leading slash anchors the pattern at the repository root. The double asterisk includes subdirectories.
version: 2
rules:
- key: migration-rollback
path_globs:
- "/db/migrations/**/*.sql"
text: >-
For a column rename or drop, find readers and writers that can
still run when the migration takes effect, including the rollback
version. Cite the SQL and the affected query. If deployment order
is unknown, identify what would establish it.
Try it on two pull requests targeting the same branch.
| Pull request | Expected result |
|---|---|
Drop orders.status in db/migrations/042_orders.sql and change a worker query | The SQL path activates the rule. Inspect whether the reviewer identifies the old worker query and checks when it can run. |
Change only docs/orders.md to document the new field | The migration rule has no matching path. Other applicable review rules can still run. |
An additive migration also matches the path pattern. A match tells the reviewer to consider the instruction. It still needs a relevant rename or drop and supporting evidence to report this particular problem.
Decide what “only on experimental branches” means#
A pull request from experiment/new-storage into main has main as its base. A second pull request from fix/worker into experiment/new-storage has experiment/new-storage as its base. A filter for experimental base branches selects the second request. A team that organizes experiments by source-branch name is asking for a different filter.
In Proofline, reviews.base_branches restricts which pull requests the repository reviews. It affects the whole review. A rule's path_globs determines where that one instruction applies. Keep the review-wide branch filter unset if ordinary reviews should continue on main. For an experiment kept under a dedicated directory, a rule on that directory can apply alongside the team's normal checks. Review scope and branch filters
Validate the draft configuration, merge it, and try the two pull requests above. Proofline reads the file at the merge base, so the pull request introducing a rule still uses the earlier configuration. Manage custom review rules