cocci: codify authoring and reviewing practices
These practices largely reflect what we are already doing on the mailing list, which should help new Coccinelle authors and reviewers get up to speed. Signed-off-by: Glen Choo <chooglen@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Glen Choo committed
Apr 27, 2023 at 22:22 UTC
3bd0097cfcd99e8a8d767e337cfe589e35b03042
1 file changed
+30
contrib/coccinelle/README
+30
@@ -92,3 +92,33 @@ that might be useful to developers.
92
93
The absolute times will differ for you, but the relative speedup
94
from caching should be on that order.
95
+
96
+== Authoring and reviewing coccinelle changes
97
+
98
+* When a .cocci is made, both the Git changes and .cocci file should be
99
+ reviewed. When reviewing such a change, do your best to understand the .cocci
100
+ changes (e.g. by asking the author to explain the change) and be explicit
101
+ about your understanding of the changes. This helps us decide whether input
102
+ from coccinelle experts is needed or not. If you aren't sure of the cocci
103
+ changes, indicate what changes you actively endorse and leave an Acked-by
104
+ (instead of Reviewed-by).
105
+
106
+* Authors should consider that reviewers may not be coccinelle experts, thus the
107
+ the .cocci changes may not be self-evident. A plain text description of the
108
+ changes is strongly encouraged, especially when using more esoteric features
109
+ of the language.
110
+
111
+* .cocci rules should target only the problem it is trying to solve; "collateral
112
+ damage" is not allowed. Reviewers should look out and flag overly-broad rules.
113
+
114
+* Consider the cost-benefit ratio of .cocci changes. In particular, consider the
115
+ effect on the runtime of "make coccicheck", and how often your .cocci check
116
+ will catch something valuable. As a rule of thumb, rules that can bail early
117
+ if a file doesn't have a particular token will have a small impact on runtime,
118
+ and vice-versa.
119
+
120
+* .cocci files used for refactoring should be temporarily kept in-tree to aid
121
+ the refactoring of out-of-tree code (e.g. in-flight topics). Periodically
122
+ evaluate the cost-benefit ratio to determine when the file should be removed.
123
+ For example, consider how many out-of-tree users are left and how much this
124
+ slows down "make coccicheck".