Documentation
¶
Overview ¶
Command ratchetpatch narrows the maintainability ratchet to the files a change actually changed the CODE of.
A ratchet in CI runs a golangci-lint config's budgets with `--new-from-rev=<merge-base> --whole-files`, so every file a branch touches is judged in full. That flag is correct and load-bearing -- adding branches to the body of an existing function is the most common way debt gets created, and hunk scoping waves it through, because every complexity linter anchors its finding to the `func` line well above the hunk.
The cost is that `--whole-files` cannot tell a code change from a comment change. Adding one doc comment to internal/store/order.go surfaces the 11 findings that file already carried, so the edit that pays down MISSING_DOC_COMMENT (#1637, 483 findings, ~31% of the scan total) is charged for FUNCTION_SIZE_RISK and PARAMETER_RISK debt it did not create. That is not the forcing function working, it is the forcing function pointed backwards: the cheapest, most mechanical, zero-design-risk class of remediation in the backlog is also the one the gate makes most expensive. #1713 and #1715 both hit this.
So this tool computes the diff the ratchet should see. A .go file whose only change is comments, blank lines or formatting is dropped from the patch; every other changed file stays, and is still judged in full. golangci-lint then runs with `--new-from-patch` instead of `--new-from-rev`, which is the same ratchet over a smaller file set rather than a weaker one.
cd api && go run <this> -base "$MERGE_BASE" -out changed.patch
Two comment classes are deliberately NOT exempt, because both change what the compiler or the linter does:
- Directives (`//go:build`, `//go:generate`, `//nolint`, `//lint:ignore`). A `//nolint` is the single most consequential comment in a linted file -- it deletes a finding -- and SUPPRESSED_WARNING (#1636) is itself one of the tickets. Waving those through would let a change disable a linter with the gate exempting it for being "comment only".
- Anything in a file that does not parse. An unparseable file cannot be compared, so it is included and the normal gate applies.
Source Files