From: Glen Choo <chooglen@xxxxxxxxxx>
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@xxxxxxxxxx>
---
contrib/coccinelle/README | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)
diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README
index 9b28ba1c57a..055ad0e06a7 100644
--- a/contrib/coccinelle/README
+++ b/contrib/coccinelle/README
@@ -92,3 +92,33 @@ that might be useful to developers.
The absolute times will differ for you, but the relative speedup
from caching should be on that order.
+
+== Authoring and reviewing coccinelle changes
+
+* When a .cocci is made, both the Git changes and .cocci file should be
+ reviewed. When reviewing such a change, do your best to understand the .cocci
+ changes (e.g. by asking the author to explain the change) and be explicit
+ about your understanding of the changes. This helps us decide whether input
+ from coccinelle experts is needed or not. If you aren't sure of the cocci
+ changes, indicate what changes you actively endorse and leave an Acked-by
+ (instead of Reviewed-by).
+
+* Authors should consider that reviewers may not be coccinelle experts, thus the
+ the .cocci changes may not be self-evident. A plain text description of the
+ changes is strongly encouraged, especially when using more esoteric features
+ of the language.
+
+* .cocci rules should target only the problem it is trying to solve; "collateral
+ damage" is not allowed. Reviewers should look out and flag overly-broad rules.
+
+* Consider the cost-benefit ratio of .cocci changes. In particular, consider the
+ effect on the runtime of "make coccicheck", and how often your .cocci check
+ will catch something valuable. As a rule of thumb, rules that can bail early
+ if a file doesn't have a particular token will have a small impact on runtime,
+ and vice-versa.
+
+* .cocci files used for refactoring should be temporarily kept in-tree to aid
+ the refactoring of out-of-tree code (e.g. in-flight topics). Periodically
+ evaluate the cost-benefit ratio to determine when the file should be removed.
+ For example, consider how many out-of-tree users are left and how much this
+ slows down "make coccicheck".
--
gitgitgadget
