From bd111141aa118e03c969f878540a75381d1c6e9a Mon Sep 17 00:00:00 2001 From: Glen Choo Date: Thu, 27 Apr 2023 22:22:22 +0000 Subject: [PATCH 1/2] cocci: add headings to and reword README - Drop "examples" since we actually use the patches. - Drop sentences that could be headings instead Signed-off-by: Glen Choo Signed-off-by: Junio C Hamano --- contrib/coccinelle/README | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README index d1daa1f626..9b28ba1c57 100644 --- a/contrib/coccinelle/README +++ b/contrib/coccinelle/README @@ -1,7 +1,9 @@ -This directory provides examples of Coccinelle (http://coccinelle.lip6.fr/) -semantic patches that might be useful to developers. += coccinelle -There are two types of semantic patches: +This directory provides Coccinelle (http://coccinelle.lip6.fr/) semantic patches +that might be useful to developers. + +== Types of semantic patches * Using the semantic transformation to check for bad patterns in the code; The target 'make coccicheck' is designed to check for these patterns and @@ -42,7 +44,7 @@ There are two types of semantic patches: This allows to expose plans of pending large scale refactorings without impacting the bad pattern checks. -Git-specific tips & things to know about how we run "spatch": +== Git-specific tips & things to know about how we run "spatch": * The "make coccicheck" will piggy-back on "COMPUTE_HEADER_DEPENDENCIES". If you've built a given object file From 3bd0097cfcd99e8a8d767e337cfe589e35b03042 Mon Sep 17 00:00:00 2001 From: Glen Choo Date: Thu, 27 Apr 2023 22:22:23 +0000 Subject: [PATCH 2/2] 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 Signed-off-by: Junio C Hamano --- contrib/coccinelle/README | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README index 9b28ba1c57..055ad0e06a 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".